cosmo_build/lib.rs
1//! Build a Rust crate into a fat **Actually Portable Executable** from its
2//! `build.rs` -- one file that runs on x86-64 and arm64, linked against
3//! Cosmopolitan Libc.
4//!
5//! Cargo has no concept of a multi-architecture artifact, so one `cargo build`
6//! can never produce an APE. [`apeify`] runs the build once per architecture
7//! and fuses the two ELFs with `apelink`, which is what cosmocc does for C.
8//!
9//! # Adding it to a project
10//!
11//! ```toml
12//! [features]
13//! ape = ["dep:cosmo-build"] # or: default = ["ape"] to always build one
14//!
15//! [build-dependencies]
16//! cosmo-build = { version = "10", optional = true }
17//!
18//! # No runtime dependency: the matching shim is injected privately.
19//!
20//! [lints.rust]
21//! unexpected_cfgs = { level = "allow", check-cfg = ['cfg(cosmo)'] }
22//! ```
23//!
24//! ```no_run
25//! // build.rs
26//! fn main() {
27//! #[cfg(feature = "ape")]
28//! cosmo_build::apeify();
29//! }
30//! ```
31//!
32//! A library crate has no bins, so it names the program the APE is built from:
33//!
34//! ```toml
35//! [package.metadata.cosmo]
36//! example = "demo"
37//! ```
38//!
39//! Then `cargo build -F ape` leaves the APE in `target/cosmo/<profile>/<name>.com`, and a
40//! plain `cargo build` is an ordinary host build that never compiles this crate.
41//!
42//! # What it needs
43//!
44//! Nothing installed up front beyond `rustup`, and on Unix a shell. The first
45//! build installs the pinned nightly (with `rust-src`) and downloads cosmocc
46//! (~440MB, ~1.4GB unpacked) into a cache shared by every project, so a second
47//! project costs no disk. On Unix `/bin/sh` is required because cosmocc's own
48//! tools are APEs, which a Unix kernel cannot `exec`; Windows runs them as the
49//! PE files they also are. cosmocc's own drivers are shell scripts, so this
50//! crate brings its own (assets/shim.rs), compiled with the host's rustc on
51//! first use, and points cc-rs at it for any C or C++ in the dependency graph.
52//!
53//! # What gets downloaded
54//!
55//! Once, into a cache shared by every project; a warm build touches the network
56//! not at all.
57//!
58//! * crates.io: this crate and its download/unpack dependencies, plus `libc` and
59//! `rustix` for the privately built embedded shim, checksummed by Cargo. Those
60//! private dependencies do not enter the application's Cargo graph. An app
61//! using `rustix` should retain an explicit matching `cosmo-compat` dependency
62//! to unify its `use-libc` feature; private injection cannot change that graph.
63//! * static.rust-lang.org: the pinned nightly and `rust-src` via rustup, only
64//! if they are not already installed.
65//! * cosmo.zip: `cosmocc-4.0.2.zip`, 441,763,966 bytes, ~1.4GB unpacked. This
66//! is the only URL the crate itself opens. It is pinned to a versioned
67//! release rather than the moving `cosmocc.zip`, and its SHA-256 is checked
68//! before anything is unpacked -- from a mirror too. A mismatch deletes the
69//! download and fails the build.
70//!
71//! # Environment
72//!
73//! | | |
74//! |---|---|
75//! | `COSMO_HOME` | move the cache (default `$XDG_CACHE_HOME/cargo-cosmo`) |
76//! | `COSMO_APE=0` | never build an APE -- the setting for an editor |
77//! | `COSMO_APE=1` | build one even when the heuristics say otherwise |
78//! | `COSMO_RUSTFLAGS` | extra rustflags for the cosmo builds only |
79//! | `COSMO_CFLAGS`, `COSMO_CXXFLAGS` | extra flags for C or C++ in the cosmo builds, never for assembly |
80//! | `COSMO_KEEP_PROFILE=1` | do not override `codegen-units`/`lto` |
81//! | `COSMO_PROGRESS` | append the per-architecture builds' progress to this file instead of the terminal |
82//!
83//! # Caveats
84//!
85//! Cargo holds build-script output until the script exits, so the
86//! per-architecture builds print their progress straight to the terminal, or to
87//! the file `COSMO_PROGRESS` names. The nested build needs its own target directory (~190MB)
88//! because the outer cargo holds an exclusive lock on `target/`. And the APE
89//! runs on Linux today: rustc bakes in Linux's OS constants while cosmopolitan
90//! resolves them at load time, which the `cosmo-compat` shim translates at the
91//! libc boundary -- see the repository for how far that goes.
92
93use std::env;
94use std::path::{Path, PathBuf};
95
96mod cache;
97mod driver;
98mod inject;
99mod manifest;
100mod pairing;
101mod sha256;
102mod toolchain;
103
104/// True when cargo is only type-checking, so no artifact will be produced.
105///
106/// `cargo check`, `cargo clippy` and rust-analyzer's check-on-save all run
107/// build scripts, and an unconditional `cosmo-build` would hand each of them a
108/// two-architecture build-std build -- once per save, in an editor. Cargo
109/// exposes no flag for this, so it is inferred: clippy announces itself, and
110/// cargo puts the artifact directory (`target/<profile>`) first on the dynamic
111/// search path only for a build that will emit one; a check build starts at
112/// `.../deps`. Verified by diffing the build-script environment of `build`,
113/// `check`, `test` and `clippy` -- `LD_LIBRARY_PATH` is the only key that
114/// differs between build and check, so this is undocumented cargo behaviour and
115/// could change. It guards wasted work, never correctness: guess wrong and you
116/// get a spurious APE, or none from a `cargo check` that would not have linked
117/// anything anyway.
118///
119/// `cargo test` is byte-identical to `cargo build` here and cannot be
120/// distinguished; set `COSMO_APE=0` if that matters. On Windows `cargo check` is
121/// too: the search path goes in `PATH`, which starts at `deps` either way.
122pub fn is_metadata_only() -> bool {
123 if env::var_os("CLIPPY_ARGS").is_some() {
124 return true;
125 }
126 for key in ["LD_LIBRARY_PATH", "DYLD_FALLBACK_LIBRARY_PATH", "DYLD_LIBRARY_PATH"] {
127 if let Ok(path) = env::var(key) {
128 return path.split(':').next().unwrap_or("").ends_with("/deps");
129 }
130 }
131 false
132}
133
134/// Whether [`apeify`] will do anything: `COSMO_APE` wins if set, otherwise any
135/// build that actually links.
136pub fn wanted() -> bool {
137 match env::var("COSMO_APE").as_deref() {
138 Ok("0") | Ok("false") | Ok("no") => false,
139 Ok(_) => true,
140 Err(_) => !is_metadata_only(),
141 }
142}
143
144/// Build this crate into `target/cosmo/<profile>/<name>.com` unless this is a check-only
145/// pass or the build script is re-entering itself. Panics with the failure if
146/// the build breaks.
147///
148/// This is the one call a `build.rs` needs. Use [`build_ape`] to skip the
149/// policy and always build.
150pub fn apeify() {
151 let args = match manifest_args() {
152 Ok(a) => a,
153 Err(e) => panic!("cosmo-build: {e}"),
154 };
155 let borrowed: Vec<&str> = args.iter().map(String::as_str).collect();
156 apeify_with(&borrowed)
157}
158
159/// What `[package.metadata.cosmo]` says to build, as cargo arguments.
160///
161/// Empty when the table is absent, which is right for a crate with bins: the
162/// APE is built from whatever `cargo build` would have produced anyway.
163///
164/// ```toml
165/// [package.metadata.cosmo]
166/// example = "demo" # or ["demo", "bench"]
167/// bin = "tool" # or [...]
168/// features = ["gui", "x11"]
169/// args = ["--no-default-features"]
170/// ```
171pub fn manifest_args() -> Result<Vec<String>, String> {
172 let dir = env::var_os("CARGO_MANIFEST_DIR").ok_or("CARGO_MANIFEST_DIR is not set")?;
173 manifest::args(Path::new(&dir))
174}
175
176/// [`apeify`] with the arguments given here instead of the manifest's.
177///
178/// The call site wins outright: `[package.metadata.cosmo]` is not consulted, so
179/// there is one place to look rather than two. Anything `cargo build` accepts
180/// works -- `--example`, `--bin`, `--features`, `--no-default-features`. Prefer
181/// the manifest table unless the choice has to be computed.
182///
183/// ```no_run
184/// // build.rs of a library whose demo lives in examples/demo.rs
185/// fn main() {
186/// #[cfg(feature = "ape")]
187/// cosmo_build::apeify_with(&["--example", "demo"]);
188/// }
189/// ```
190pub fn apeify_with(args: &[&str]) {
191 // Cargo caches build-script runs, and any rerun-if-* directive REPLACES the
192 // default "re-run when a package file changed". Declaring a path that never
193 // exists is the only way to say "always run": without it a deleted APE is
194 // never rebuilt and cargo still reports Finished.
195 println!("cargo::rerun-if-changed=.cosmo-always-rerun");
196 println!("cargo::rerun-if-env-changed=COSMO_APE");
197 println!("cargo::rustc-check-cfg=cfg(cosmo)");
198
199 // The nested build runs this script again; that pass must fall straight
200 // through or the builds nest forever.
201 if env::var_os("COSMO_APE_INNER").is_some() || !wanted() {
202 return;
203 }
204 if let Err(e) = try_build_ape(args) {
205 panic!("cosmo-build: {e}");
206 }
207}
208
209/// Build the APE whatever cargo is doing, ignoring the [`wanted`] policy but
210/// still declining to recurse. Panics on failure.
211pub fn build_ape() {
212 build_ape_with(&[])
213}
214
215/// [`build_ape`] with extra arguments handed to each `cargo build`.
216pub fn build_ape_with(args: &[&str]) {
217 if env::var_os("COSMO_APE_INNER").is_some() {
218 return;
219 }
220 if let Err(e) = try_build_ape(args) {
221 panic!("cosmo-build: {e}");
222 }
223}
224
225/// The whole build, with the failure returned rather than raised.
226///
227/// Worth calling directly from a `build.rs` that wants to degrade instead of
228/// break -- warn and carry on with the host build, say.
229pub fn try_build_ape(args: &[&str]) -> Result<Vec<PathBuf>, String> {
230 let manifest = PathBuf::from(
231 env::var_os("CARGO_MANIFEST_DIR").ok_or("CARGO_MANIFEST_DIR is not set")?,
232 );
233 let release = env::var("PROFILE").as_deref() == Ok("release");
234
235 pairing::check(&manifest)?;
236
237 let cache = cache::Cache::locate()?;
238 toolchain::ensure_rust()?;
239 toolchain::ensure_cosmocc(&cache)?;
240 driver::build(&cache, &manifest, release, args)
241}
242
243#[cfg(test)]
244mod tests {
245 /// The linker driver wraps every symbol in assets/wrap.txt, and the
246 /// translators it names live in cosmo-compat. A symbol wrapped here with no
247 /// translator there is a link error in every consuming project, so the two
248 /// lists must be published in lockstep. Only runs from a repo checkout; the
249 /// sibling crate is not in the published package.
250 #[test]
251 fn wrap_list_matches_cosmo_compat() {
252 let Ok(theirs) = std::fs::read_to_string("../cosmo-compat/wrap.txt") else {
253 return;
254 };
255 let symbols = |text: &str| -> Vec<String> {
256 let mut v: Vec<String> = text
257 .lines()
258 .map(|l| l.trim().to_string())
259 .filter(|l| !l.is_empty() && !l.starts_with('#'))
260 .collect();
261 v.sort();
262 v
263 };
264 assert_eq!(
265 symbols(crate::cache::WRAP_LIST),
266 symbols(&theirs),
267 "assets/wrap.txt and cosmo-compat's wrap.txt disagree; regenerate crates/cosmo-build/assets"
268 );
269 }
270}