cosmo-build
cargo build -F ape → one file that runs on x86-64 and arm64.
Builds a Rust crate into a fat Actually Portable Executable from its
build.rs, linked against Cosmopolitan Libc.
Cargo has no concept of a multi-architecture artifact, so one cargo build can
never produce an APE: this runs the build once per architecture and fuses the
two ELFs with apelink, which is what cosmocc does for C.
[]
= ["dep:cosmo-build"] # or: default = ["ape"] to always build one
[]
= { = "10", = true }
[]
= { = "allow", = ['cfg(cosmo)'] }
// build.rs
$ cargo build -F ape
$ ./target/cosmo/release/myprog.com
With the feature off, this crate is never fetched, compiled or run.
Version 10 embeds and privately links the matching normalization shim: there is
no runtime Cargo dependency and no extern crate line to add. An explicit
cosmo-compat = "10" dependency remains supported; other majors are rejected.
The private shim build uses libc and rustix without adding them to the
application's Cargo graph. Applications using rustix should keep the explicit
compat dependency so its use-libc feature unifies with their own dependencies;
private injection cannot switch another Cargo graph's raw-syscall backend.
A library crate
An APE is a program, and a library has none, so it names the one the APE is
built from. The build script cannot learn this from the command line -- cargo
hands an identical environment to cargo build and cargo build --example demo -- so it is declared next to the crate's other target declarations, where
cargo ignores it:
[]
= "demo" # or ["demo", "bench"]
= "tool" # or [...]
= ["gui", "x11"]
= ["--no-default-features"]
build.rs stays cosmo_build::apeify(). Where the choice has to be computed
rather than declared, apeify_with(&["--example", "demo"]) takes the same
arguments directly and the manifest table is not consulted.
What it needs
rustup, and on Unix /bin/sh. Nothing else, and nothing installed up front —
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. Linux, macOS and Windows hosts all work. /bin/sh is
unavoidable on Unix: cosmocc's own tools are APEs and the kernel cannot exec
one directly. Windows runs them as the PE files they also are.
cosmocc's compiler and linker drivers are shell scripts, so this crate ships its
own as Rust (assets/shim.rs), compiles it with the host's rustc on first use,
and points cc-rs at it (CC_<arch>-unknown-cosmo and friends) for any C or C++
in the dependency graph.
What gets downloaded
Three things, once, then never again -- the cache is shared by every project on the machine and nothing is fetched on a warm build.
| from | what | size | verified by |
|---|---|---|---|
| crates.io | cosmo-build and its download/unpack dependencies (ureq, zip and their trees); the runtime shim is embedded |
~5MB | cargo's registry checksums |
| static.rust-lang.org | the pinned nightly plus rust-src, via rustup, only if not already installed |
~1.6GB on disk | rustup's signed manifests |
| cosmo.zip | cosmocc-4.0.2.zip |
441,763,966 bytes (~1.4GB unpacked) | SHA-256 pinned in the crate |
https://cosmo.zip/pub/cosmocc/cosmocc-4.0.2.zip is the only URL this crate
itself will open, and it is pinned to a versioned release rather than the
moving cosmocc.zip, so a build in a year fetches the compiler these results
were measured against. Its SHA-256 is checked before anything is unpacked --
including from a mirror, since a mirror is only a different route to the same
bytes. A mismatch deletes the download and fails the build.
COSMO_COSMOCC_URL points the fetch at a mirror or an internal cache;
COSMO_COSMOCC_SHA256 is how you run a different cosmocc deliberately.
Environment
COSMO_HOME |
move the cache (default $XDG_CACHE_HOME/cargo-cosmo) |
COSMO_APE=0 |
never build an APE — the setting for an editor |
COSMO_APE=1 |
build one even when the heuristics say otherwise |
COSMO_COSMOCC_URL |
fetch cosmocc from a mirror |
COSMO_COSMOCC_SHA256 |
expect a different cosmocc |
COSMO_RUSTFLAGS |
extra rustflags for the cosmo builds only |
COSMO_CFLAGS, COSMO_CXXFLAGS |
extra flags for C or C++ in the cosmo builds, never for assembly |
COSMO_KEEP_PROFILE=1 |
do not override codegen-units/lto |
COSMO_PROGRESS |
append 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_PROGRESSnames when output is piped and a wrapper shows it. - The nested build needs its own target directory (~190MB) because the outer
cargo holds an exclusive lock on
target/. cargo checkandcargo clippyare detected and skipped, exceptcargo checkon Windows;cargo testis indistinguishable fromcargo buildin a build script's environment and will build an APE. SetCOSMO_APE=0where that matters.- The APE is a genuine fat binary but runs on Linux today — rustc bakes in
Linux's OS constants while cosmopolitan resolves them at load time. The
embedded
cosmo-compatshim translates libc entry points at the boundary. Version 10 networking/futex changes were executed on Linux x86-64 only; arm64 builds but was not executed, and Windows/macOS/BSD paths remain unrun for this release. Historical macOS/arm64 std results predate these changes. See the repository.
MIT licensed.