1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
//! 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
//!
//! ```toml
//! [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)'] }
//! ```
//!
//! ```no_run
//! // 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:
//!
//! ```toml
//! [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_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.
use env;
use ;
/// True when cargo is only type-checking, so no artifact will be produced.
///
/// `cargo check`, `cargo clippy` and rust-analyzer's check-on-save all run
/// build scripts, and an unconditional `cosmo-build` would hand each of them a
/// two-architecture build-std build -- once per save, in an editor. Cargo
/// exposes no flag for this, so it is inferred: clippy announces itself, and
/// cargo puts the artifact directory (`target/<profile>`) first on the dynamic
/// search path only for a build that will emit one; a check build starts at
/// `.../deps`. Verified by diffing the build-script environment of `build`,
/// `check`, `test` and `clippy` -- `LD_LIBRARY_PATH` is the only key that
/// differs between build and check, so this is undocumented cargo behaviour and
/// could change. It guards wasted work, never correctness: guess wrong and you
/// get a spurious APE, or none from a `cargo check` that would not have linked
/// anything anyway.
///
/// `cargo test` is byte-identical to `cargo build` here and cannot be
/// distinguished; set `COSMO_APE=0` if that matters. On Windows `cargo check` is
/// too: the search path goes in `PATH`, which starts at `deps` either way.
/// Whether [`apeify`] will do anything: `COSMO_APE` wins if set, otherwise any
/// build that actually links.
/// 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.
///
/// This is the one call a `build.rs` needs. Use [`build_ape`] to skip the
/// policy and always build.
/// What `[package.metadata.cosmo]` says to build, as cargo arguments.
///
/// Empty when the table is absent, which is right for a crate with bins: the
/// APE is built from whatever `cargo build` would have produced anyway.
///
/// ```toml
/// [package.metadata.cosmo]
/// example = "demo" # or ["demo", "bench"]
/// bin = "tool" # or [...]
/// features = ["gui", "x11"]
/// args = ["--no-default-features"]
/// ```
/// [`apeify`] with the arguments given here instead of the manifest's.
///
/// The call site wins outright: `[package.metadata.cosmo]` is not consulted, so
/// there is one place to look rather than two. Anything `cargo build` accepts
/// works -- `--example`, `--bin`, `--features`, `--no-default-features`. Prefer
/// the manifest table unless the choice has to be computed.
///
/// ```no_run
/// // build.rs of a library whose demo lives in examples/demo.rs
/// fn main() {
/// #[cfg(feature = "ape")]
/// cosmo_build::apeify_with(&["--example", "demo"]);
/// }
/// ```
/// Build the APE whatever cargo is doing, ignoring the [`wanted`] policy but
/// still declining to recurse. Panics on failure.
/// [`build_ape`] with extra arguments handed to each `cargo build`.
/// The whole build, with the failure returned rather than raised.
///
/// Worth calling directly from a `build.rs` that wants to degrade instead of
/// break -- warn and carry on with the host build, say.