@axodotdev/dist
Advanced tools
dist (formerly known as cargo-dist)
dist distributes your binaries
The TL;DR is that with dist set up, 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.
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, 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.
As a build tool, 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.
As a distribution tool, dist gets to flex its biggest superpower: it generates its own CI scripts. For instance, enabling GitHub CI with dist init will generate release.yml, which implements the full pipeline of plan, build, host, publish, announce:
We've got all the docs you need over at the dist book!
dist's tests rely on 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:
cargo install cargo-insta
Once installed, you can review and accept the changes with:
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
emittest will actually commit the results back to disk tocargo-dist-schema/cargo-dist-schema.jsonas 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$schemafield.
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.
TL;DR:
Note that we've wired up 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 dist as a follow up:
dist init --yesNote that as a consequence of the way we self-host, 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!
Version 0.30.0 (2025-09-07)
This release contains several improvements to ZIP archives, the installers and additional build workflow customization options.
Previous versions of dist produced uncompressed ZIP archives which meant that they were much larger than necessary. ZIP archives are now compressed.
In previous versions, ZIP archives were only suitable for Windows binaries because they didn't preserve executable permissions. ZIP archives now correctly preserve extended Unix permissions.
The npm installer previously used the unzip commandline utility to unpack ZIP archives on Windows. This isn't available in all installations, so some users would experience errors at install time. We've improved this by switching to the builtin PowerShell Expand-Archive cmdlet.
dist's installers are configurable using a variety of different environment variables, but in previous versions only some of these would be branded with your app's name. We now provide branded versions of all of the other environment variables as well. The previous unbranded environment variables will continue to work. The new variables are:
${APP_NAME}_DOWNLOAD_URL${APP_NAME}_PRINT_QUIET${APP_NAME}_PRINT_VERBOSEThis feature previously appeared in version 0.28.7 of Astral's fork.
The shell installers will now refuse to fetch archives using a copy of curl installed via the Snap package manager for Ubuntu. Snap-installed copies of curl have limitations on their ability to write downloaded files to disk which makes them unsuitable for dist's installers. If a Snap-installed curl is detected, the installer will try to fall back to using another download tool; if no other tool is present, a message will be shown to the user and the installation will abort.
This feature previously appeared in version 0.28.5 of Astral's fork.
The PowerShell installer now respects the HTTPS_PROXY and ANY_PROXY environment variables and uses them to configure a proxy when fetching artifacts. These were already supported by the shell installer.
--options flagWhen using the experimental macOS codesigning feature, users can now specify a value to be passed to the --options flag using the CODESIGN_OPTIONS environment variable.
In previous versions of dist, we used cross-compilation to build arm64 Linux binaries from an x86_64 host. GitHub now provides free native arm64 runners, so we've switched to using these by default. Users can still use cross-compilation if they prefer by specifying the x86_64 runners using the custom runners feature in the dist config.
It's now possible to customize exactly which artifacts are attested, and which phase of the build process to perform the attestations in. Currently, customizing which artifacts to attest requires the attestation to happen during the host phase; this restriction may be lifted in the future.
To specify which artifacts to attest, you can use a list of globs; any artifacts matching any of those globs will receive an attestation. For example:
github-attestations-phase = "host"
github-attestations-filters = ["*.json", "*.sh", "*.ps1", "*.zip", "*.tar.gz"]
FAQs
Shippable application packaging for Rust
The npm package @axodotdev/dist receives a total of 10 weekly downloads. As such, @axodotdev/dist popularity was classified as not popular.
We found that @axodotdev/dist demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Former RubyGems maintainers have launched The Gem Cooperative, a new community-run project aimed at rebuilding open governance in the Ruby ecosystem.
Security News
An opt-in lazy import keyword aims to speed up Python startups, especially CLIs, without the ecosystem-wide risks that sank PEP 690.
Security News
Socket CEO Feross Aboukhadijeh discusses the recent npm supply chain attacks on PodRocket, covering novel attack vectors and how developers can protect themselves.