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
libcandrustixfor the privately built embedded shim, checksummed by Cargo. Those private dependencies do not enter the application’s Cargo graph. An app usingrustixshould retain an explicit matchingcosmo-compatdependency to unify itsuse-libcfeature; private injection cannot change that graph. - static.rust-lang.org: the pinned nightly and
rust-srcvia 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 movingcosmocc.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_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_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. 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>.comunless this is a check-only pass or the build script is re-entering itself. Panics with the failure if the build breaks. - apeify_
with apeifywith the arguments given here instead of the manifest’s.- build_
ape - Build the APE whatever cargo is doing, ignoring the
wantedpolicy but still declining to recurse. Panics on failure. - build_
ape_ with build_apewith extra arguments handed to eachcargo 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
apeifywill do anything:COSMO_APEwins if set, otherwise any build that actually links.