aot_lang/
lib.rs

1//! # aot_lang
2//!
3//! Ahead-of-time compile the [`ir-lang`](ir_lang) intermediate representation into a
4//! single linked image.
5//!
6//! aot-lang is the batch counterpart to a just-in-time compiler: instead of running
7//! a function the moment it is generated, it lowers one or more functions to object
8//! code and lays them out together into an [`Image`] — a self-contained artifact
9//! with its code, a symbol table, and an entry point, ready to be inspected,
10//! serialized, or loaded. It is the end of the pipeline a front-end follows: parse,
11//! type-check, lower to IR, and then compile the whole program ahead of time.
12//!
13//! ## The pipeline
14//!
15//! A compile is two stages, one per dependency it wires:
16//!
17//! 1. **Lower.** Each [`ir_lang::Function`] is compiled to a
18//!    [`codegen_lang::Program`] of register bytecode — the object code — after being
19//!    checked with `Function::validate`, so only well-formed SSA is ever lowered.
20//! 2. **Encode and link.** Each program is encoded into the bytes of a `.text`
21//!    section with a symbol at its start, and [`linker-lang`](linker_lang) places
22//!    the objects at addresses, resolves the entry point, and produces the [`Image`].
23//!
24//! The object-code byte format is little-endian on every target, so an image
25//! compiled on one host is byte-identical on another.
26//!
27//! ## Surface
28//!
29//! The surface is small. [`compile`] is the shortcut for a single function; it
30//! returns an image with that function as the entry point. [`Compiler`] is the
31//! builder for several functions in one image, and for choosing the base address
32//! and entry point. [`AotError`] is the failure of either stage. The result type,
33//! [`Image`], and its [`OutputSection`]s are re-exported from `linker-lang`.
34//!
35//! ## Example
36//!
37//! Compile two functions into one image laid out at a load address:
38//!
39//! ```
40//! use aot_lang::Compiler;
41//! use ir_lang::{Builder, BinOp, Type};
42//!
43//! // fn add(a: int, b: int) -> int { a + b }
44//! let mut add = Builder::new("add", &[Type::Int, Type::Int], Type::Int);
45//! let a = add.block_params(add.entry())[0];
46//! let b = add.block_params(add.entry())[1];
47//! let sum = add.bin(BinOp::Add, a, b);
48//! add.ret(Some(sum));
49//!
50//! // fn answer() -> int { 42 }
51//! let mut answer = Builder::new("answer", &[], Type::Int);
52//! let c = answer.iconst(42);
53//! answer.ret(Some(c));
54//!
55//! let mut compiler = Compiler::new();
56//! compiler.base_address(0x40_0000).entry("add");
57//! compiler.add(&add.finish()).unwrap();
58//! compiler.add(&answer.finish()).unwrap();
59//! let image = compiler.link().unwrap();
60//!
61//! assert_eq!(image.entry(), Some(0x40_0000));
62//! assert_eq!(image.symbol("add"), Some(0x40_0000));
63//! assert!(image.symbol("answer").is_some());
64//! ```
65//!
66//! ## No-std
67//!
68//! The crate needs only `alloc`; it performs no I/O and touches no operating-system
69//! facility. Build with `default-features = false` to drop the standard library. The
70//! `serde` feature derives serialization for [`AotError`] and forwards to the
71//! dependencies so a linked image round-trips.
72//!
73//! ## Stability
74//!
75//! The public surface is being designed across the `0.x` series and frozen at
76//! `1.0`. See [`docs/API.md`](https://github.com/jamesgober/aot-lang/blob/main/docs/API.md)
77//! and [`dev/ROADMAP.md`](https://github.com/jamesgober/aot-lang/blob/main/dev/ROADMAP.md).
78
79#![cfg_attr(not(feature = "std"), no_std)]
80#![cfg_attr(docsrs, feature(doc_cfg))]
81#![deny(missing_docs)]
82#![deny(unused_must_use)]
83#![forbid(unsafe_code)]
84#![deny(
85    clippy::unwrap_used,
86    clippy::expect_used,
87    clippy::panic,
88    clippy::todo,
89    clippy::unimplemented,
90    clippy::unreachable,
91    clippy::dbg_macro,
92    clippy::print_stdout,
93    clippy::print_stderr
94)]
95
96extern crate alloc;
97
98mod compiler;
99mod encode;
100mod error;
101
102pub use compiler::{Compiler, compile};
103pub use error::AotError;
104
105/// The linked image produced by a compile, re-exported from
106/// [`linker-lang`](linker_lang). It carries the laid-out code sections, the resolved
107/// symbol table, and the entry point.
108pub use linker_lang::Image;
109/// One laid-out section of an [`Image`], re-exported from
110/// [`linker-lang`](linker_lang). A compiled image has a single `.text` section
111/// holding every function's object code.
112pub use linker_lang::OutputSection;
aot_lang/lib.rs

aot_lang/
lib.rs
