Add --aot AOT backend producing arm64-apple-ios .o + C header

For Audulus iOS where the stack interpreter isn't fast enough. `lyte
file.lyte --no-recursion --entry init,process --aot out.o` emits a
Mach-O arm64 object plus a companion header so host C/C++ code can link
the compiled program directly.

Exports are prefixed (default: filename stem; --aot-prefix overrides)
and internal Lyte functions are demoted to Internal linkage so multiple
AOT objects coexist in one binary. Math builtins map to libm; IO
builtins become weak host-overridable hooks (noinline+optnone so the
defaults aren't inlined away). Cancel-check and call-depth-check are
elided — AOT requires --no-recursion.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: wtholliday

cli/src/main.rs

@@ -55,6 +55,16 @@ struct Args {
     /// Entry point function name(s), comma-separated. Defaults to "main".
     #[clap(long)]
     entry: Option<String>,
+
+    /// Ahead-of-time compile to an arm64-apple-ios Mach-O object file at the
+    /// given path. A companion `.h` is written next to it. Requires the
+    /// `llvm` feature and implies `--no-recursion`.
+    #[clap(long)]
+    aot: Option<String>,
+
+    /// Symbol prefix for AOT outputs. Defaults to the stem of the --aot path.
+    #[clap(long)]
+    aot_prefix: Option<String>,
 }
 
 fn run(args: Args) -> i32 {
@@ -168,6 +178,21 @@ fn run(args: Args) -> i32 {
 
     compiler.print_ir = args.ir;
 
+    // Handle AOT compile (writes a .o + .h and exits).
+    #[cfg(feature = "llvm")]
+    {
+        if let Some(out) = args.aot.as_deref() {
+            return run_aot(&mut compiler, out, args.aot_prefix.as_deref());
+        }
+    }
+    #[cfg(not(feature = "llvm"))]
+    {
+        if args.aot.is_some() {
+            eprintln!("--aot requires the `llvm` cargo feature");
+            return 1;
+        }
+    }
+
     // Select backend via --backend flag, falling back to LYTE_BACKEND env var.
     let backend = if args.backend.is_empty() {
         std::env::var("LYTE_BACKEND").unwrap_or_default()
@@ -392,6 +417,67 @@ fn run(args: Args) -> i32 {
     0
 }
 
+#[cfg(feature = "llvm")]
+fn run_aot(
+    compiler: &mut lyte::Compiler,
+    output: &str,
+    prefix_override: Option<&str>,
+) -> i32 {
+    if !compiler.no_recursion {
+        eprintln!("--aot requires --no-recursion");
+        return 1;
+    }
+    if !compiler.has_decls() {
+        eprintln!("--aot: no declarations to compile");
+        return 1;
+    }
+    if let Err(e) = compiler.specialize() {
+        eprintln!("{}", e);
+        return 1;
+    }
+    let path = std::path::PathBuf::from(output);
+    let prefix = match prefix_override {
+        Some(p) => p.to_string(),
+        None => path
+            .file_stem()
+            .and_then(|s| s.to_str())
+            .map(sanitize_aot_prefix)
+            .unwrap_or_else(|| "lyte".to_string()),
+    };
+    if prefix.is_empty() {
+        eprintln!("--aot: prefix is empty (use --aot-prefix to override)");
+        return 1;
+    }
+    match compiler.compile_aot(&path, &prefix) {
+        Ok(()) => 0,
+        Err(e) => {
+            eprintln!("{}", e);
+            1
+        }
+    }
+}
+
+#[cfg(feature = "llvm")]
+fn sanitize_aot_prefix(stem: &str) -> String {
+    let mut out: String = stem
+        .chars()
+        .map(|c| {
+            if c.is_ascii_alphanumeric() || c == '_' {
+                c
+            } else {
+                '_'
+            }
+        })
+        .collect();
+    // C identifiers can't start with a digit.
+    if let Some(first) = out.chars().next() {
+        if first.is_ascii_digit() {
+            out.insert(0, '_');
+        }
+    }
+    out
+}
+
 fn main() {
     let args = Args::parse();
 

cli/tests/cli.rs

@@ -46,3 +46,128 @@ fn golden_tests_asm() -> goldentests::TestResult<()> {
 fn golden_tests_stack() -> goldentests::TestResult<()> {
     run_golden_tests("stack")
 }
+
+#[test]
+#[cfg(feature = "llvm")]
+fn aot_emits_arm64_ios_object_and_header() {
+    use std::io::Write;
+
+    let tmp = std::env::temp_dir().join("lyte_aot_smoke");
+    let _ = std::fs::remove_dir_all(&tmp);
+    std::fs::create_dir_all(&tmp).unwrap();
+
+    let src = tmp.join("smoke.lyte");
+    let mut f = std::fs::File::create(&src).unwrap();
+    writeln!(
+        f,
+        "var freq: f32\n\
+         var sample_rate: f32\n\
+         \n\
+         init(rate: f32, f: f32) {{\n\
+             sample_rate = rate\n\
+             freq = f\n\
+         }}\n\
+         \n\
+         phase() -> f32 {{\n\
+             return freq / sample_rate\n\
+         }}"
+    )
+    .unwrap();
+    drop(f);
+
+    let out_o = tmp.join("smoke.o");
+    let status = std::process::Command::new(LYTE_BIN)
+        .arg(&src)
+        .arg("--no-recursion")
+        .arg("--entry")
+        .arg("init,phase")
+        .arg("--aot")
+        .arg(&out_o)
+        .status()
+        .expect("failed to invoke lyte");
+    assert!(status.success(), "--aot exited with {}", status);
+    assert!(out_o.exists(), "object file not written");
+
+    let out_h = tmp.join("smoke.h");
+    assert!(out_h.exists(), "header file not written");
+
+    // Check Mach-O 64-bit arm64 magic + cputype rather than shelling out to
+    // `file`, so the test runs anywhere.
+    let bytes = std::fs::read(&out_o).expect("read .o");
+    assert!(bytes.len() >= 8, ".o too short");
+    let magic = u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]);
+    assert_eq!(magic, 0xfeed_facf, "expected Mach-O 64-bit magic");
+    let cputype = u32::from_le_bytes([bytes[4], bytes[5], bytes[6], bytes[7]]);
+    assert_eq!(cputype, 0x0100_000c, "expected arm64 cputype (got {:#x})", cputype);
+
+    let header = std::fs::read_to_string(&out_h).expect("read .h");
+    assert!(header.contains("#define SMOKE_H"), "missing include guard");
+    assert!(header.contains("SMOKE_STATE_SIZE"), "missing state-size macro");
+    assert!(header.contains("smoke_init"), "missing init wrapper decl");
+    assert!(header.contains("smoke_phase"), "missing phase wrapper decl");
+    assert!(header.contains("SMOKE_OFFSET_FREQ"), "missing freq global offset");
+    assert!(header.contains("smoke_globals"), "missing metadata table");
+    assert!(header.contains("smoke_assert"), "missing assert hook decl");
+}
+
+#[test]
+#[cfg(feature = "llvm")]
+fn aot_two_objects_have_disjoint_public_symbols() {
+    // Two .lyte programs that both define internal helpers and entry points
+    // with the same names must produce link-disjoint .o files when given
+    // different prefixes.
+    use std::io::Write;
+
+    let tmp = std::env::temp_dir().join("lyte_aot_collision");
+    let _ = std::fs::remove_dir_all(&tmp);
+    std::fs::create_dir_all(&tmp).unwrap();
+
+    for prefix in &["nodea", "nodeb"] {
+        let src = tmp.join(format!("{}.lyte", prefix));
+        let mut f = std::fs::File::create(&src).unwrap();
+        writeln!(
+            f,
+            "helper(x: f32) -> f32 {{\n\
+                 return x * x\n\
+             }}\n\
+             \n\
+             run(input: f32) -> f32 {{\n\
+                 return helper(input)\n\
+             }}"
+        )
+        .unwrap();
+        drop(f);
+        let out_o = tmp.join(format!("{}.o", prefix));
+        let status = std::process::Command::new(LYTE_BIN)
+            .arg(&src)
+            .arg("--no-recursion")
+            .arg("--entry")
+            .arg("run")
+            .arg("--aot")
+            .arg(&out_o)
+            .status()
+            .expect("failed to invoke lyte");
+        assert!(status.success(), "--aot exited with {}", status);
+    }
+
+    // Read both .o files and grep their byte content for the public symbols.
+    // We don't parse Mach-O; we just confirm that the *other* program's
+    // wrapper name does NOT appear in this .o.
+    let a = std::fs::read(tmp.join("nodea.o")).unwrap();
+    let b = std::fs::read(tmp.join("nodeb.o")).unwrap();
+    assert!(contains_substr(&a, b"nodea_run"), "nodea.o missing its wrapper");
+    assert!(contains_substr(&b, b"nodeb_run"), "nodeb.o missing its wrapper");
+    assert!(!contains_substr(&a, b"nodeb_run"), "nodea.o leaks nodeb_run");
+    assert!(!contains_substr(&b, b"nodea_run"), "nodeb.o leaks nodea_run");
+    // Internal helper from either program should NOT appear as an external
+    // symbol with the bare name; either it's inlined away or set to private
+    // linkage. We can't tell without a Mach-O parser, but the public-name
+    // disjointness check above is the load-bearing one for "can they link".
+}
+
+#[cfg(feature = "llvm")]
+fn contains_substr(haystack: &[u8], needle: &[u8]) -> bool {
+    haystack
+        .windows(needle.len())
+        .any(|w| w == needle)
+}

src/compiler.rs

@@ -768,6 +768,37 @@ impl Compiler {
         }
     }
 
+    /// Ahead-of-time compile to an `arm64-apple-ios` Mach-O object file and
+    /// write a companion C header. Output paths are derived from
+    /// `output_path` (e.g. `path/biquad.o` → `path/biquad.h`).
+    ///
+    /// `prefix` is applied to every externally-visible symbol so multiple
+    /// AOT objects can be linked into the same binary without collisions.
+    #[cfg(feature = "llvm")]
+    pub fn compile_aot(
+        &self,
+        output_path: &std::path::Path,
+        prefix: &str,
+    ) -> Result<(), String> {
+        if self.decls.decls.is_empty() {
+            return Err("No declarations to compile".into());
+        }
+        if !self.no_recursion {
+            return Err(
+                "--aot requires --no-recursion (call-depth machinery is unavailable at link time)"
+                    .into(),
+            );
+        }
+        let entry_points = self.effective_entry_points();
+        crate::llvm_aot::compile_aot(
+            &self.decls,
+            &entry_points,
+            output_path,
+            prefix,
+            self.print_ir,
+        )
+    }
+
     /// Compile with LLVM and print IR, but do not execute.
     #[cfg(feature = "llvm")]
     pub fn print_llvm_ir(&mut self) {

src/lib.rs

@@ -49,6 +49,9 @@ mod llvm_jit;
 #[cfg(feature = "llvm")]
 pub use llvm_jit::*;
 
+#[cfg(feature = "llvm")]
+pub mod llvm_aot;
+
 pub mod mangle;
 
 mod hoist;