feat: postcompile (#217)

postcompile is a crate for compiling rust code at runtime in unit tests. Its very useful when writing proc-macro snapshot tests to test the output of the generated code.

Cargo.toml

@@ -15,6 +15,7 @@ members = [
     "crates/metrics",
     "crates/metrics/derive",
     "crates/metrics/examples",
+    "crates/postcompile",
     "crates/pprof",
     "crates/pprof/examples",
     "crates/settings",

README.md

@@ -45,6 +45,7 @@ This repository houses a collection of crates, purpose-built libraries designed
 - 📈 **[scuffle-pprof](./crates/pprof)**:  Helper crate for adding pprof support to your application.
 - ⚙️ **[scuffle-settings](./crates/settings)**:  Tools for managing configuration from environment variables or config files.
 - 📶 **[scuffle-signal](./crates/signal)**:  Ergonomic async signal handling.
+- 📦 **[postcompile](./crates/postcompile)**:  A macro for compiling Rust code at runtime. Useful for snapshot testing.
 
 ## 📦 Apps
 

crates/postcompile/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "postcompile"
+version = "0.0.4"
+edition = "2021"
+build = "build.rs"
+repository = "https://github.com/scufflecloud/scuffle"
+authors = ["Scuffle <[email protected]>"]
+readme = "README.md"
+documentation = "https://docs.rs/postcompile"
+license = "MIT OR Apache-2.0"
+description = "Helper crate for post-compiling Rust code."
+keywords = ["postcompile", "snapshot", "test", "proc-macro"]
+
+[dependencies]
+serde_json = "1.0"
+cargo_metadata = "0.19.1"
+cargo-platform = "0.1"
+target-triple = "0.1"
+serde_derive = "1.0"
+serde = "1.0"
+prettyplease = { version = "0.2", optional = true }
+syn = { version = "2", features = ["full"] }
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(trybuild_no_target)', 'cfg(postcompile_no_target)'] }
+
+[features]
+prettyplease = ["dep:prettyplease"]

crates/postcompile/LICENSE.Apache-2.0

@@ -0,0 +1 @@
+../../LICENSE.Apache-2.0

crates/postcompile/LICENSE.MIT

@@ -0,0 +1 @@
+../../LICENSE.MIT

crates/postcompile/README.md

@@ -0,0 +1,74 @@
+# postcompile
+
+> [!WARNING]  
+> This crate is under active development and may not be stable.
+
+[![crates.io](https://img.shields.io/crates/v/postcompile.svg)](https://crates.io/crates/postcompile) [![docs.rs](https://img.shields.io/docsrs/postcompile)](https://docs.rs/postcompile)
+
+---
+
+A crate which allows you to compile Rust code at runtime (hence the name `postcompile`).
+
+What that means is that you can provide the input to `rustc` and then get back the expanded output, compiler errors, warnings, etc.
+
+This is particularly useful when making snapshot tests of proc-macros, look below for an example with the `insta` crate.
+
+## Usage
+
+```rs
+#[test]
+fn some_cool_test() {
+    insta::assert_snapshot!(postcompile::compile! {
+        #![allow(unused)]
+
+        #[derive(Debug, Clone)]
+        struct Test {
+            a: u32,
+            b: i32,
+        }
+
+        const TEST: Test = Test { a: 1, b: 3 };
+    });
+}
+
+#[test]
+fn some_cool_test_extern() {
+    insta::assert_snapshot!(postcompile::compile_str!(include_str!("some_file.rs")));
+}
+```
+
+## Features
+
+- Cached builds: This crate reuses the cargo build cache of the original crate so that only the contents of the macro are compiled & not any additional dependencies.
+- Coverage: This crate works with [`cargo-llvm-cov`](https://crates.io/crates/cargo-llvm-cov) out of the box, which allows you to instrument the proc-macro expansion.
+
+## Alternatives
+
+- [`compiletest_rs`](https://crates.io/crates/compiletest_rs): This crate is used by the Rust compiler team to test the compiler itself. Not really useful for proc-macros.
+- [`trybuild`](https://crates.io/crates/trybuild): This crate is an all-in-one solution for testing proc-macros, with built in snapshot testing.
+- [`ui_test`](https://crates.io/crates/ui_test): Similar to `trybuild` with a slightly different API & used by the Rust compiler team to test the compiler itself.
+
+### Differences
+
+The other libraries are focused on testing & have built in test harnesses. This crate takes a step back and allows you to compile without a testing harness. This has the advantage of being more flexible, and allows you to use whatever testing framework you want.
+
+In the examples above I showcase how to use this crate with the `insta` crate for snapshot testing.
+
+## Status
+
+This crate is currently under development and is not yet stable, unit tests are not yet fully implemented.
+
+Unit tests are not yet fully implemented. Use at your own risk.
+
+## Limitations
+
+Please note that this crate does not work inside a running compiler process (inside a proc-macro) without hacky workarounds and complete build-cache invalidation.
+
+This is because `cargo` holds a lock on the build directory and that if we were to compile inside a proc-macro we would recursively invoke the compiler.
+
+## License
+
+This project is licensed under the [MIT](./LICENSE.MIT) or [Apache-2.0](./LICENSE.Apache-2.0) license.
+You can choose between one of them if you use this work.
+
+`SPDX-License-Identifier: MIT OR Apache-2.0`

crates/postcompile/build.rs

@@ -0,0 +1,3 @@
+/// This is a dummy build script, it does nothing.
+/// But we need to get the `OUT_DIR` from the environment so that we can determine where the target directory is.
+fn main() {}