search

axodotdev / cargo-dist

📦 shippable application packaging
https://axodotdev.github.io/cargo-dist/
Apache License 2.0
1.32k stars 55 forks source link
cargo installers packaging release-automation rust

readme

# `cargo-dist`

crates.io docs Rust CI

cargo-dist distributes your binaries

The TL;DR is that with cargo-dist setup, just doing this:

git commit -am "release: 0.2.0"
git tag "v0.2.0"
git push
git push --tags

Will make this Github Release:

Or if you're using oranda, you'll get this website.

Plan, Build, Host, Publish, Announce

Cutting releases of your apps and distributing binaries for them has a lot of steps, and cargo-dist is quickly growing to try to cover them all!

To accomplish this, cargo-dist functionality can be broken up into two parts:

The build functionality can be used on its own if you just want some tarballs and installers, but everything really comes together when you use the distribution functionality too.

Building

As a build tool, cargo-dist can do the following:

That's a short list because "we make installers" is doing a lot of heavy lifting. Each installer could be (and sometimes is!) an entire standalone tool with its own documentation and ecosystem.

Distributing

As a distribution tool, cargo-dist gets to flex its biggest superpower: it generates its own CI scripts. For instance, enabling GitHub CI with cargo dist init will generate release.yml, which implements the full pipeline of plan, build, host, publish, announce:

Read The Book!

We've got all the docs you need over at the cargo-dist book!

# Contributing ## Updating Snapshots cargo-dist's tests rely on [cargo-insta](https://crates.io/crates/cargo-insta) for snapshot testing various outputs. This allows us to both catch regressions and also more easily review UI/output changes. If a snapshot test fails, you will need to use the `cargo insta` CLI tool to update them: ```sh cargo install cargo-insta ``` Once installed, you can review and accept the changes with: ```sh cargo insta review ``` If you know you like the changes, just use `cargo insta accept` to auto-apply all changes. (If you introduced brand-new snapshot tests you will also have to `git add` them!) > NOTE: when it succeeds, cargo-dist-schema's `emit` test will actually commit the results back to disk to `cargo-dist-schema/cargo-dist-schema.json` as a side-effect. This is a janky hack to make sure we have that stored and up to date at all times (the test also uses an insta snapshot but insta snapshots include an extra gunk header so it's not something we'd want to link end users). The file isn't even used for anything yet, I just want it to Exist because it seems useful and important. In the future we might properly host it and have our outputs link it via a `$schema` field. ## Cutting Releases cargo-dist is self-hosting, so you just need to push a git-tag with the right format to "do" a release. Of course there's lots of other tedious tasks that come with updating a release, and we use cargo-release to handle all those mechanical details of updating versions/headings/tags. See [these sections of the docs for the release workflow we use](https://opensource.axo.dev/cargo-dist/book/workspaces/cargo-release-guide.html#using-cargo-release-with-pull-requests). TL;DR: * Update CHANGELOG.md's "Unreleased" section to include all the release notes you want * run cargo-release as described in the docs * ..you're done! Note that we've wired up cargo-dist and cargo-release to understand the "Unreleased" heading so you should never edit that name, the tools will update it as needed. If that releases succeeds, we recommend updating the bootstrap version of cargo-dist as a follow up: * install the version of cargo-dist you just released on your system * run `cargo dist init --yes` * commit "chore: update bootstrap dist to ..." Note that as a consequence of the way we self-host, cargo-dist's published artifacts will always be built/generated by a previous version of itself. This can be problematic if you make breaking changes to cargo-dist-schema's format... so don't! Many things in the schema are intentionally optional to enable forward and backward compatibility, so this should hopefully work well!