Quickstart
Five minutes from nothing to a cached Rust build. You need Linux (a macOS client build exists, but is early), a Rust toolchain from rustup, and access to the private tempoxyz/shippy repository.
Install the client
Pick one. Both put a shippy binary on your PATH.
# The repository is private: use a GitHub token that can read it.
# In a subshell, so the token isn't left in your shell for later builds.
( export GITHUB_TOKEN=$(gh auth token) # or paste a token
printf 'Authorization: Bearer %s\n' "$GITHUB_TOKEN" \
| curl -fsSL -H @- https://raw.githubusercontent.com/tempoxyz/shippy/main/deploy/install.sh | sh )git clone https://github.com/tempoxyz/shippy && cd shippy
cargo install --path crates/shippyThe install script downloads the release for your machine, checks it against the release's SHA256SUMS, and puts shippy in ~/.local/bin (for another directory, end the pipe with sh -s -- --dir <dir>). curl needs the token too, since raw.githubusercontent.com answers 404 for a private file without it. It reads the header from stdin, so the token stays out of the process list.
Build with it
Go to any cargo project and use shippy where you would use cargo:
shippy build
shippy test -p my-crateshippy <anything> runs cargo <anything> with shippy's compiler wrapper in place. Nothing in your project changes.
See what the cache did
shippy statsThe first build fills your local store at ~/.cache/shippy, so it is a little slower than plain cargo. Now switch branches and back, or run cargo clean and build again: the crates come back from the store instead of being compiled.
Connect to a shared box (optional)
If your team runs a box, ask its operator for a token file, then once per user:
shippy setup --remote http://box:7447 --token-file token.txt
shippy doctorshippy setup writes ~/.config/shippy/config.toml and the token beside it, readable by you alone, and asks the box whether it takes the token. shippy doctor checks the toolchain, the store, the box and the token, and names the fix for anything wrong.
From now on, every shippy build downloads what others have already built and uploads what you build.
What just happened
For every crate, cargo calls shippy's wrapper instead of rustc. The wrapper works out a key from everything the crate reads. If the store has a result under that key, it puts the files where cargo expects them. If not, it runs the real rustc and keeps the output. How it works explains the keys.
Useful switches
| Variable | What it does |
|---|---|
SHIPPY_DISABLE=1 | Run plain rustc, as if shippy were not there. |
SHIPPY_EXEC=auto | Have the box compile what the cache misses, beside this machine (remote execution). |
SHIPPY_FIXED=1 | Build with the checkout mounted at a fixed path, so checkouts anywhere share everything (paths). Needs bubblewrap. SHIPPY_FIXED=0 builds with every directory where it is, cargo's home too. |
SHIPPY_LINKED=0 | Leave executables to the linker instead of caching them. |
SHIPPY_PREFETCH=0 | Don't download a whole build's results before cargo starts. |
Every setting is in client settings.
Next
- Share a cache: start your own box.
- Tune a project: find the fastest linker and debug settings for your edit loop.
- FAQ: what to do when something looks wrong.