1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
//! luna-aot — ahead-of-time compiler from Lua source to a
//! self-contained native binary.
//!
//! # v1.3 ship scope (THIS SESSION — scaffold + bytecode-embed only)
//!
//! What runs end-to-end **today**:
//!
//! 1. CLI [`cli::run`] / library [`embed::embed_bytecode`] take a `.lua`
//! source file.
//! 2. luna-core's frontend parses + compiles it to bytecode (a
//! [`luna_core::runtime::Proto`] tree).
//! 3. The bytecode is dumped via [`luna_core::vm::dump`] (luna's own
//! body format — `"\x1bLua" + version-byte` header + the
//! `"\x00LunaV1\x00"` sentinel + luna body).
//! 4. The dump bytes are written into a `.luna.bytecode` section of an
//! ELF / Mach-O / PE object file via [`object::write::Object`],
//! bracketed by two **public** symbols
//! `__luna_bytecode_start` and `__luna_bytecode_end` that the
//! runtime stub (or a custom host binary) `extern "C"`s.
//! 5. The CLI invokes system `cc` to link the bytecode object + a
//! minimal C entry point into a final executable. The default
//! scaffold entry just prints the embedded bytecode length to
//! `stderr` and exits — proving the section is reachable end-to-end.
//!
//! What is **deferred to follow-up sessions** within the v1.3 mega
//! sprint (per `.dev/rfcs/v1.3-audit-luna-aot.md` Stage 3-6):
//!
//! - **Wiring the [`runtime_stub`] Rust module into the linked binary**
//! so the embedded bytecode is `undump`-ed into a [`luna_core::vm::Vm`]
//! and executed at process start (interp-only). This needs either
//! (a) `luna-core` exposed as a `staticlib` for the target triple,
//! or (b) a tempdir-cargo shell-out that builds a tiny crate that
//! `include_bytes!`s the dump and depends on `luna-core`. The
//! runtime-stub source compiles cleanly today; it just isn't wired
//! to the link step yet.
//! - **Cranelift trace codegen via `cranelift-object::ObjectModule`**
//! (the bulk of the ~70-day audit estimate — the lowerer refactor
//! that genericises the JIT backend over `cranelift_module::Module`).
//! - **Cross-compile** via `--target <triple>`. The flag is present in
//! the CLI today but only the host triple is wired end-to-end.
//! - **Smoke tests** that run the produced binary and compare stdout
//! with `luna`.
//!
//! # Why a separate crate
//!
//! See the audit's "Why a separate crate vs `--features aot`" section.
//! Summary: this crate pulls `object` + `clap` and (in a follow-up
//! session) all of cranelift; embedders who only want the runtime
//! JIT keep using `luna-jit`, and embedders who only want pure interp
//! keep using `luna-core` — both stay free of `luna-aot`'s build-time
//! dep tree.
//!
//! **`luna-core` 0-third-party-dep contract is unaffected.** This
//! crate depends on `luna-core` but `luna-core` does not depend on
//! anything here. The CI gate
//! (`cargo tree -p luna-core --prefix none | grep -cE " v[0-9]"`)
//! continues to report `1`.
/// Symbol name marking the start of the embedded bytecode section.
/// External (C-ABI) symbol; the runtime stub declares it as
/// `extern "C" { static __luna_bytecode_start: u8; }`.
pub const BYTECODE_START_SYMBOL: &str = "__luna_bytecode_start";
/// Symbol name marking the end of the embedded bytecode section.
/// External (C-ABI) symbol; the runtime stub declares it as
/// `extern "C" { static __luna_bytecode_end: u8; }` and computes the
/// length as `(&end as *const u8).offset_from(&start as *const u8)`.
pub const BYTECODE_END_SYMBOL: &str = "__luna_bytecode_end";
/// Object-file section name for the embedded bytecode.
/// ELF/Mach-O conventions: a leading dot is the standard for non-loader-
/// special sections; we pick `.luna.bytecode` so `objdump -s -j
/// .luna.bytecode <out>` displays the dump bytes for inspection.
pub const BYTECODE_SECTION_NAME: &str = ".luna.bytecode";
// `runtime_stub` declares `extern "C" { static __luna_bytecode_start: u8 }`
// + `__luna_bytecode_end`. These symbols are linker-provided by the
// bytecode `.o` that `embed::embed_bytecode` writes; they exist only in
// the AOT-produced binary's link set, not in the luna-aot crate's own
// builds (rlib / test / doctest).
//
// Most linkers (ld / lld / Mach-O) tolerate unresolved `extern`
// references unless something actually calls them. MSVC's `link.exe`
// is stricter — even unused references trigger LNK2019. So the module
// is gated off when building the luna-aot crate itself under MSVC;
// the user-side Cargo bootstrap recipe (see `runtime_stub::aot_main`
// rustdoc § Wiring) re-enables it by setting
// `RUSTFLAGS=--cfg luna_aot_runtime_stub` when compiling against the
// real bytecode object link set. Tier-1 deploys via the AOT pipeline's
// own `cc` invocation (`embed::compile_and_link`) use the C entry +
// `luna_aot_run` from `luna-runtime-helpers`, not this Rust stub.