cosmo-build 10.0.0

Build a Rust crate into a fat Actually Portable Executable from its build.rs — one file that runs on x86-64 and arm64
Documentation

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.

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

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

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

[package.metadata.cosmo]
example  = "demo"              # or ["demo", "bench"]
bin      = "tool"              # or [...]
features = ["gui", "x11"]
args     = ["--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_PROGRESS names 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 check and cargo clippy are detected and skipped, except cargo check on Windows; cargo test is indistinguishable from cargo build in a build script's environment and will build an APE. Set COSMO_APE=0 where 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-compat shim 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.