In-process LLVM backend: native construction via the C API, opt-in (#7241, engine-plan layer 0)

changelog.d/7241-inprocess-llvm-native-construction.md

@@ -0,0 +1,18 @@
+Opt-in in-process LLVM backend (#7241, engine-plan layer 0): with the
+`llvm-inprocess` cargo feature built in and `PERRY_LLVM_INPROCESS=native`,
+Perry constructs LLVM modules through the C API against pinned LLVM 22 — no
+module-scale IR text, no `.ll` on disk, no `clang` subprocess, no dependence
+on the user's toolchain. All 68 `LlBlock` semantic methods emit typed
+instructions that build directly (`inst.rs`/`dialect.rs`); codegen-unit
+splits build per-unit native modules and partial-link as before; `=diff`
+mode byte-compares the two backends' objects (both corpora byte-identical);
+`PERRY_SAVE_LL`/`--trace llvm`/`PERRY_LLVM_KEEP_IR` print the constructed
+module as the debug view. `=1` selects the transport-only mode (whole-module
+text parsed in-process). The flag participates in the build- and
+object-cache keys; a build without the feature fails loudly if the flag is
+set. The default build is unchanged: no LLVM link dependency, and emitted
+IR is byte-identical to the merge-base (verified over a 12-file corpus; the
+only divergence class is a pre-existing run-to-run closure-name
+registration ordering coin that flips within a single binary).
+`RewriteStatepointsForGC` scheduling in-process is pinned by test —
+the layer-2 (#7174) unblock this branch exists for.

crates/perry-codegen/Cargo.toml

@@ -8,6 +8,15 @@ description = "LLVM code generation backend for Perry"
 [lints]
 workspace = true
 
+[features]
+# exp/llvm-inprocess: compile `.ll -> .o` through the LLVM C API inside this
+# process instead of shelling out to a user-supplied `clang -c`. Off by
+# default — the default build has no LLVM link dependency and the text path
+# is byte-for-byte untouched. Building with this feature requires LLVM 22
+# (`brew install llvm`; set LLVM_SYS_221_PREFIX if llvm-config is not on
+# PATH). The backend still only runs when PERRY_LLVM_INPROCESS=1 at runtime.
+llvm-inprocess = ["dep:inkwell", "dep:llvm-sys"]
+
 [dependencies]
 perry-hir.workspace = true
 perry-dispatch.workspace = true
@@ -18,3 +27,6 @@ thiserror.workspace = true
 log.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+
+inkwell = { version = "0.9.0", features = ["llvm22-1"], optional = true }
+llvm-sys = { version = "221", optional = true }