Skip to main content

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}