FAQ

Do I have to change my project?

No. shippy build runs cargo build with a compiler wrapper. A shippy.toml at the workspace root is optional and only adds settings to cargo commands.

Does it work on macOS or Windows?

The box needs Linux: its sandbox is bubblewrap. Releases also carry a client for macOS on Apple silicon, built as an optional target, while the README still calls shippy Linux only, so treat macOS as early. There is no Windows build.

Can a cached result ever be wrong?

A result is found by a key that covers everything the compilation can read, and the wrapper refuses to cache when in doubt. Every blob is checked against its digest when it arrives. A result from an untrusted machine is never served to anyone else until the box's sandbox has reproduced it. See trust.

What if the box is down?

Your build goes on. An unreachable box costs one failed connect, after which the wrappers leave it alone for 30 seconds. Uploads stay queued; shippy push sends them later.

What if shippy itself has a bug?

The wrapper falls back to plain rustc on any error of its own and never fails a build that rustc would pass. To rule shippy out entirely, run with SHIPPY_DISABLE=1.

Why is my first build slower than cargo?

shippy hashes and stores every result so the next build can skip them. On tempo, that is 135.3 s against 127.8 s. Every build after that is where it pays.

Why didn't my edit get faster?

After a real edit, every crate the edit reaches has to compile; that is rustc, not the cache. What helps there is tuned settings: a faster linker and less debug info. The cache shows when you undo an edit, switch branches back, or build a fresh checkout.

Why do CI and developers not share workspace crates?

Cargo compiles workspace crates without -C incremental wherever the CI variable is set, and that flag is part of a crate's key. Build in CI with CARGO_INCREMENTAL=1 to share.

Two checkouts at different paths don't share. Why?

Usually because cargo hashes the absolute path of a path dependency outside the cargo workspace, or a build script writes an absolute path. Turn on the fixed place (SHIPPY_FIXED=1), which needs bubblewrap and unprivileged user namespaces.

Another user compiles dependencies I already built. Why?

A dependency that holds its own directory (env!("CARGO_MANIFEST_DIR")) is tied to the path of cargo's home, and so is everything compiled against it. For a procedural macro, a build has cargo's home at one fixed place for every user where the machine lets shippy make a namespace: shippy doctor says whether yours does, and why not. Plain cargo or an editor that used the same target directory compiled such a macro for your own cargo home, which ends the sharing there. A library that holds its directory is part of your program, and is compiled for each cargo home.

My build scripts run every time. Why?

Build-script runs of downloaded packages are cached unless SHIPPY_SCRIPTS=0 turns that off. Your own packages' scripts are cached only with SHIPPY_SCRIPTS=1. A script that stamps the build time produces new output every run: set SOURCE_DATE_EPOCH. See build scripts.

How much disk does it use?

By default, half of the store's own size plus the free space of its disk, never more than 50 GB. Set SHIPPY_MAX_SIZE, or max_size under [cache] in your user file. See eviction.

Something looks wrong. Where do I start?

1. shippy doctor checks the toolchain, the store, the box and the token, and names each fix.
2. shippy stats shows what the cache did in the last run.
3. SHIPPY_DISABLE=1 shippy build runs plain rustc, to rule shippy out.
4. For a box, see troubleshooting.