Skip to main content

Crate cosmo_build

Crate cosmo_build 

Source
Expand description

Build a Rust crate into a fat Actually Portable Executable from its build.rs – one file that runs on x86-64 and arm64, linked against Cosmopolitan Libc.

Cargo has no concept of a multi-architecture artifact, so one cargo build can never produce an APE. apeify runs the build once per architecture and fuses the two ELFs with apelink, which is what cosmocc does for C.

§Adding it to a project

[features]
ape = ["dep:cosmo-build"]      # or: default = ["ape"] to always build one

[build-dependencies]
cosmo-build = { version = "10", optional = true }

# No runtime dependency: the matching shim is injected privately.

[lints.rust]
unexpected_cfgs = { level = "allow", check-cfg = ['cfg(cosmo)'] }
// build.rs
fn main() {
   #[cfg(feature = "ape")]
   cosmo_build::apeify();
}

A library crate has no bins, so it names the program the APE is built from:

[package.metadata.cosmo]
example = "demo"

Then cargo build -F ape leaves the APE in target/cosmo/<profile>/<name>.com, and a plain cargo build is an ordinary host build that never compiles this crate.

§What it needs

Nothing installed up front beyond rustup, and on Unix a shell. The first build installs the pinned nightly (with rust-src) and downloads cosmocc (~440MB, ~1.4GB unpacked) into a cache shared by every project, so a second project costs no disk. On Unix /bin/sh is required because cosmocc’s own tools are APEs, which a Unix kernel cannot exec; Windows runs them as the PE files they also are. cosmocc’s own drivers are shell scripts, so this crate brings its own (assets/shim.rs), compiled with the host’s rustc on first use, and points cc-rs at it for any C or C++ in the dependency graph.

§What gets downloaded

Once, into a cache shared by every project; a warm build touches the network not at all.

  • crates.io: this crate and its download/unpack dependencies, plus libc and rustix for the privately built embedded shim, checksummed by Cargo. Those private dependencies do not enter the application’s Cargo graph. An app using rustix should retain an explicit matching cosmo-compat dependency to unify its use-libc feature; private injection cannot change that graph.
  • static.rust-lang.org: the pinned nightly and rust-src via rustup, only if they are not already installed.
  • cosmo.zip: cosmocc-4.0.2.zip, 441,763,966 bytes, ~1.4GB unpacked. This is the only URL the crate itself opens. It is pinned to a versioned release rather than the moving cosmocc.zip, and its SHA-256 is checked before anything is unpacked – from a mirror too. A mismatch deletes the download and fails the build.

§Environment

COSMO_HOMEmove the cache (default $XDG_CACHE_HOME/cargo-cosmo)
COSMO_APE=0never build an APE – the setting for an editor
COSMO_APE=1build one even when the heuristics say otherwise
COSMO_RUSTFLAGSextra rustflags for the cosmo builds only
COSMO_CFLAGS, COSMO_CXXFLAGSextra flags for C or C++ in the cosmo builds, never for assembly
COSMO_KEEP_PROFILE=1do not override codegen-units/lto
COSMO_PROGRESSappend the per-architecture builds’ progress to this file instead of the terminal

§Caveats

Cargo holds build-script output until the script exits, so the per-architecture builds print their progress straight to the terminal, or to the file COSMO_PROGRESS names. The nested build needs its own target directory (~190MB) because the outer cargo holds an exclusive lock on target/. And the APE runs on Linux today: rustc bakes in Linux’s OS constants while cosmopolitan resolves them at load time, which the cosmo-compat shim translates at the libc boundary – see the repository for how far that goes.

Functions§

apeify
Build this crate into target/cosmo/<profile>/<name>.com unless this is a check-only pass or the build script is re-entering itself. Panics with the failure if the build breaks.
apeify_with
apeify with the arguments given here instead of the manifest’s.
build_ape
Build the APE whatever cargo is doing, ignoring the wanted policy but still declining to recurse. Panics on failure.
build_ape_with
build_ape with extra arguments handed to each cargo build.
is_metadata_only
True when cargo is only type-checking, so no artifact will be produced.
manifest_args
What [package.metadata.cosmo] says to build, as cargo arguments.
try_build_ape
The whole build, with the failure returned rather than raised.
wanted
Whether apeify will do anything: COSMO_APE wins if set, otherwise any build that actually links.