+
+cargo-dist extends Cargo to support all the extra things you want to do when building the final shippable binaries for an application, so we can turn this:
+git commit -am "Chore: 0.1.0 release"
+git tag "v0.1.0"
+git push
+git push --tags
+
+into this:
+
+Locally, cargo-dist can do the following:
+
+- Picking good build flags for "shippable binaries"
+- Making zips and installers for the resulting binaries
+- Generating machine-readable manifests so other tools can understand the results
+
+Being able to build a zip on your own machine is nice and all, but in practice you probably want to have infrastructure for building and hosting the binaries for all the platforms you care about. To help streamline this, cargo-dist has builtin support for bringing up your infra (currently only Github CI and Github Releases, but we intended to support other platforms in subsequent releases)!
+Just run cargo dist init and it will generate its own CI scripts which:
+
+- Waits for you to push a git tag for a new version (v1.0.0, my-app-v1.0.0, my-app/v1.0.0, ...)
+- Selects what apps in your workspace to announce new releases for based on that tag
+- Creates a draft Github Release to announce the apps in and host the downloads
+- Adds the relevant release notes from your RELEASES or CHANGELOG file
+- Spins up machines to build the selected apps for your supported platforms
+- Uploads the various zips/installers to the Github Release
+- On success, publishes the Github Releases
+
+The scripts are intentionally minimal, and each machine's job roughly amounts to "install cargo-dist", "run it exactly once", "upload the artifacts it reported". It will always be easier to do builds in CI, but we want to shrink that gap as much as possible.
+We want you to be able to copy that one cargo-dist invocation CI did, run it on your machine, and get the same results without any fuss (not to bit-level precision, but to the kinds of precision normal people expect from cargo builds). No setting up docker, no weird linux-only shell scripts that assume a bunch of tools were setup in earlier CI steps.
+The main obstacle to this is "cross-compilation is hard", but other folks are making that easier every day, and eventually we'll help you with that too.
+
+
+Surprise! The tool for prebuilt shippable binaries has way too many ways to install it!
+Whichever way you choose to install it, it should be invocable as cargo dist .... If you insist on invoking the binary directly as cargo-dist you must still add the extra dist arg and invoke it as cargo-dist dist ... (a quirk of the way cargo invokes subcommands).
+
+macOS and Linux (not NixOS, Alpine, or Asahi):
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/latest/download/cargo-dist-installer.sh | sh
+
+Windows PowerShell:
+irm https://github.com/axodotdev/cargo-dist/releases/latest/download/cargo-dist-installer.ps1 | iex
+
+
+cargo install cargo-dist --locked
+
+
+cargo binstall cargo-dist
+
+
+Arch Linux users can install cargo-dist from the extra repository using pacman:
+pacman -S cargo-dist
+
+
+See The Latest Release!
+
+
+
+TLDR: cargo-dist is a souped up version of cargo build which handles building tarballs/zips and installers. It also knows how to generate Github CI for orchestrating itself and uploading its output to a new Github Release. You can use cargo-dist if you don't care about that CI stuff, but this guide assumes that you do.
+This quickstart is a bit too quick because there's some important nuances to "announcing and building releases" that depend on the way you like to structure and version your workspace. We will blatantly ignore those nuances and show you the Happiest Happy Path (a workspace with one crate that defines a binary). Checkout the guide for more details on what you should actually do.
+
+
+Setting up just requires you to install cargo-dist and then run cargo dist init in your Cargo workspace. This command interactively walks you through configuration options, and can be run again whenever you want to change your settings. Since this is the way-too-quickstart, we pass --yes to auto-accept all defaults!
+# install tools (build from source is the most portable option)
+cargo install cargo-dist
+
+# setup cargo-dist in your project (--yes to accept defaults)
+cargo dist init --yes
+git add .
+git commit -am "wow shiny new cargo-dist CI!"
+
+The one-time setup will add a decent default configuration to your root Cargo.toml and generate CI for orchestrating itself in .github/workflows/release.yml. If the CI file isn't created, this probably means you don't have repository = "https://github.com/..." consistently set in your Cargo.toml(s).
+
+When testing out cargo-dist locally, the two biggest things you might be interested in are:
+
+- build for the current platform (
cargo dist build)
+- check what CI will build (
cargo dist plan)
+
+
+cargo dist build
+
+
+The build command will by default try to build things for the computer you're running it on. So if you run it on linux you might get a tar.xz containing your binary and an installer shell script, but if you run it on windows you might get a zip and an installer powershell script.
+cargo-dist will then spit out paths to the files it created, so you can inspect their contents and try running them (note that installer scripts probably won't be locally runnable, because they will try to fetch their binaries from Github).
+See artifact modes for more advanced details on selecting what things cargo-dist should build.
+
+cargo dist plan
+
+
+The plan command should be running the exact same logic that cargo-dist's generated CI will run, but without actually building anything. This lets you quickly check what cutting a new release will produce. It will also try to catch any inconsistencies that could make the CI error out.
+
+cargo-dist largely doesn't care about the details of how you prepare your release, and intentionally doesn't provide tools to streamline it (see the next section for some recommendations). All it cares about is you getting your main branch into the state you want, and then pushing a properly formatted git tag like "v0.1.0". Here's a super bare-bones release process:
+# <manually update the version of your crate, run tests, etc>
+
+# commit and push to main (can be done with a PR)
+git commit -am "chore: Release version 0.1.0"
+git push
+
+# publish to crates.io (optional)
+cargo publish
+
+# actually push the tag up (this triggers cargo-dist's CI)
+git tag v0.1.0
+git push --tags
+
+The important parts are that you update the crates you want to release/announce to the desired version and push a git tag with that version.
+At this point you're done! The generated CI script should pick up the ball and create a Github Release with all your builds over the next few minutes!
+
+You may have noticed "cut a release" still has a lot of tedious work. That's because we recommend using cargo-release to streamline the last step, which in simple workspaces will do exactly the same thing as above (but more robustly):
+# install tools
+cargo install cargo-release
+
+# cut a release
+cargo release 0.1.0
+
+(I left off the --execute flag from cargo-release so you won't accidentally break anything if you really did just copy paste that 😇)
+For more details on using cargo-release with cargo-dist, see the guide for that.
+
+The cargo-dist Guide is the "beginner" documentation that walks you through simple usage and then introduces more complex situations as you go. More advanced documentation can be found in "concepts".
+If you have a Cargo Workspace with a single Cargo package that cargo install works for, and just want zips containing prebuilt binaries for the major desktop platforms, that should Just Work as described in the Way-Too-Quickstart. Things get more complicated if you want to:
+
+- have more packages in your Cargo Workspace (libraries, multiple binaries, ...)
+- have additional steps in your build (configure the system, add files, ...)
+- build various kinds of installers (curl-sh scripts, npm packages, msi, ...)
+
+Gonna be blunt and say that cargo-dist is still in early days and we still need to implement a lot of stuff to better support all the things people want to do with Shippable Builds. If what you want to do doesn't seem properly supported and we don't have an issue for it, absolutely file one so we can hash it out!
+The guide will start by explaining the simple case, and then explain the more complicated cases.
+
+
+Let's start with the kind of simple Cargo Workspace you would get from cargo new my-app (or cargo init my-app): a single package that defines a binary target. This is exactly the situation the Way-Too-Quickstart should work perfectly for. Here we're going to take it a bit slower.
+Our goal will be to setup a Github CI workflow that announces a new release of our application with a Github Release. The workflow will also build our application for the 3 major desktop platforms, wrap the binaries in zips/tarballs, and upload them to the Github Release. The Github Release's text will also include the relevant release notes from our RELEASES.md file.
+The workflow will be triggered whenever you push a Git Tag specifying the application's new version, like "v1.0.0". Don't worry, you won't need to write those workflows yourself, cargo-dist will generate them for you!
+
+TO BE EXTREMELY PEDANTIC: The workflow will trigger whenever Github sees that the git tag and the commit it refers to are part of the repo and the timestamp(?) of both(?) is after the commit that introduced the workflow's yml file. That last part is an absolute headache, and may require you to delete the tag both locally and on github if you created it before the workflow. Basically, setup cargo-dist before you start cutting releases!
+
+
+To setup cargo-dist on our project (after we've installed it), we "need" to run cargo dist init, which will provide us with a series of interactive prompts and explanations to configure our project. The recommended option can always be selected by hitting ENTER, and you can automate that by just passing --yes.
+You can rerun init as many times as you want, as it also functions as an "update" command for your config. This is especially convenient for updating your project to the version of cargo-dist you're running, as it will prompt you to do that whenever the versions don't match (refusing to proceed if declined).
+cargo dist init
+
+init on its own just edits your Cargo.toml to include the recommended defaults. If you have enabled CI support, it will also run cargo dist generate after setting things up. This ensures your config and your CI scripts are in sync, but will unfortunately clobber any hand-edits you made to the scripts.
+Let's look at those defaults that were added (yes those comments are generated too, you will never stop me from adding more docs!!!):
+# The profile that 'cargo dist' will build with
+[profile.dist]
+inherits = "release"
+lto = "thin"
+
+# Config for 'cargo dist'
+[workspace.metadata.dist]
+# The preferred cargo-dist version to use in CI (Cargo.toml SemVer syntax)
+cargo-dist-version = "0.0.6"
+# CI backends to support
+ci = ["github"]
+# The installers to generate for each app
+installers = []
+# Target platforms to build apps for (Rust target-triple syntax)
+targets = ["x86_64-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-pc-windows-msvc", "aarch64-apple-darwin"]
+
+
+If your config doesn't have ci = ["github"] by default, then you probably don't have repository = "https://github.com/..." consistently set in your Cargo.toml(s). The rest of this guide will assume you did. cargo-dist will work fine without it, you just won't get Github CI integration or installers.
+
+
+First let's talk about [profile.dist]. This is a custom Cargo Profile that cargo-dist will use to build your app. If you want to, you can use it yourself by passing --profile=dist to cargo (i.e. cargo run --profile=dist). We define a separate profile from the normal "release" one so that you can be comfortable giving your Shippable Builds more aggressive settings without making local development too tedious.
+In this case the default profile cargo-dist recommends is essentially the same as --release (hence inherits = "release"), but with thin LTO enabled (lto = "thin"). This will make the build take longer, but produce more optimized builds.
+cargo-dist uses the existence of [profile.dist] in your Cargo.toml to detect if your project has been properly initialized, and will generally refuse to run other commands otherwise. Sorry but you can't delete the profile!
+
+Next let's talk about [workspace.metadata.dist]. Cargo allows other tools to include their own project-wide settings in this kind of metadata table. See config for the full set of options, but here we'll look at the defaults.
+cargo-dist-version = "0.0.6" is cargo-dist recording its own version in your config for the sake of reproducibility and documentation. When you run generate the resulting CI scripts will use that version of cargo-dist.
+rust-toolchain-version = "1.67.1" is the Rust toolchain that is considered "ideal" for building your application, recorded for the sake of reproducibility and documentation. This is in contrast to the builtin Cargo rust-version which is used to specify the minimum supported Rust version. When you run generate the resulting CI scripts will install that version of the Rust toolchain with rustup. There's nothing special about the chosen value, it's just a hardcoded "recent stable version".
+ci = ["github"] lets subsequent runs of generate know what CI scripts to generate. Its presence also enables certain Github-specific features like generating the body for a Github Release and telling installers to fetch binaries from a Github Release. It will be enabled by default if you have repository = "https://github.com/..." consistently set in your Cargo.toml(s). ("github" is currently the only supported CI backend.)
+installer = [] is just saying that we haven't enabled any installers. Installers are intentionally excluded here to keep this example focused.
+targets = ... is listing the platforms to build your application for. In this case, because we didn't specify the targets with --target, init has selected the "recommended desktop suite": "x64 linux", "x64 macos", "x64 windows", and "arm64 macos (Apple silicon)". In v0.0.6 these are the only properly supported choices, because we wanted to get the core of cargo-dist solid first. Future versions should hopefully introduce proper support for important targets like "musl linux".
+
+Because we set ci = ["github"], init invoked generate for us. Creating the Github CI workflow we wanted at .github/workflows/release.yml. Rather than including the full text here, I'll just link cargo-dist's own release.yml, because cargo-dist is self-hosting and has an extremely boring build/config that is basically equivalent to the one we're looking at in this example.
+The first thing you might notice is that there's a lot of comments describing the script. As always: you will never stop me from writing more docs and shoving them in your face. Actually ok you can stop me because I need to write a lot of docs here and those comments are already decent docs. Feel free to peruse them to get a feel for it.
+One thing I want to emphasize is that each job of the workflow essentially boils down to "install cargo-dist, run cargo-dist exactly once, then upload the files it tells you to". Ideally this means you can run that one cargo-dist command and get the same things that CI produced!
+Anyway, the CI totally does all the things we said it should! Yay!
+
+Now that we've run cargo dist init, all we need to do is commit the results and push them up:
+git add .
+git commit -am "wow cool new cargo-dist CI!"
+git push
+
+Actually wait we should... probably test that we set things up properly? The devil's always in the details when it comes to CI, but we can do some initial checking of things with the plan command:
+cargo dist plan
+
+plan is the same as build but it doesn't actually run the build and defaults to reporting info for all platforms. This makes it ideal for asking cargo-dist about the full Announcement a CI run would produce.
+If everything went right, you should see something like the following:
+
.
+This output has two parts: "analyzing workspace" and "announcing"
+"analyzing workspace" describes what cargo-dist found in your workspace. In this case there's a package called "my-app" with a binary target of the same name.
+"announcing v0.1.0" tells us the tag that should be pushed to announce a release of the current workspace ("v0.1.0"). Underneath it we see that the announcement will include "my-app 0.1.0" as expected. Underneath that we see 4 artifacts will be produced and uploaded:
+
+- The Intel macOS build: my-app-v0.1.0-x86_64-apple-darwin.tar.xz
+- The M1 macOS build: my-app-v0.1.0-aarch64-apple-darwin.tar.xz
+- The Windows build: my-app-v0.1.0-x86_64-pc-windows-msvc.zip
+- The Linux build: my-app-v0.1.0-x86_64-unknown-linux-gnu.tar.xz
+
+It also helpfully lists the contents of each zip. In this case I didn't properly setup my project at all, so it only contains a prebuilt binary. If I actually add files like README.md, LICENSE, and RELEASES.md, cargo-dist will helpfully pick those up and include them (disable this with the auto-includes=false config):
+
+If you add --output-format=json you'll get a full machine-readable output instead, and have locally recreated the first step of the generate CI!
+
+With all our one-time setup done, we're ready to cut a release! This can be streamlined a lot with cargo-release which will do essentially everything we're about to go through with a single command (see the guide on that), but it's helpful to understand the actual steps in case cargo-release doesn't fit your usecase or if you need to debug issues.
+The first step is to do all the things you would do to prep a release: update docs, update release notes, bump version numbers in Cargo.tomls, run tests, and so on.
+At this point we're confident and want to release things for real. Once again, we can check what cargo-dist thinks should happen with the plan command:
+cargo dist plan
+
+Similarly you can check that cargo publish will work with the --dry-run flag:
+cargo publish --dry-run
+
+If both of those seem happy, you're ready to release! All we need to do is push up a commit that has the Git Tag that plan suggested. As we've seen in previous sections, it's recommending "v0.1.0" for our example app, so let's use that:
+# Publish to a Github Release with cargo-dist
+git commit -am "Chore: Release 0.1.0"
+git tag "v0.1.0"
+git push
+git push --tags
+
+# Publish to crates.io
+cargo publish
+
+and that's... it! If everything's working, your CI should spin up a "Release" workflow that cargo-dist generated for you, and after a few minutes the "Releases" section of your repo should have all the results populated with something like this:
+
+Oops! There's some extra features in that screenshot that I haven't explained yet! This includes the "Release Notes" feature and a few installers. Since we're talking about Releasing, let's talk about Release Notes.
+
+If your project has a top-level RELEASES/CHANGELOG file like "RELEASES.md", then cargo-dist will automatically try to use it as part of your Announcement (Github Release). We use the parse-changelog library to try to find a heading for the version you're releasing, and if we do, we add it to the Github Release's text. We also use the heading as the title for the Github Release (rather than just the git tag).
+Roughly speaking, the library is looking for something like:
+# <ignorable prefix> <version> <ignorable suffix>
+
+For instance in # Version 1.0.0 (2022-03-01), the only really important part is the "1.0.0", which should exactly match the Cargo version of your package. If you want to see how your RELEASES/CHANGELOG file is interpreted you can install parse-changelog as a CLI and run it on the file to see what it thinks. In the future we'll have some better debugging tools for this.
+If you're publishing a Version with some prerelease bits like "1.0.0-prerelease.1", then we'll first look for that exact match in your RELEASES/CHANGELOG. If we can't find it we'll strip the prerelease/build suffix (in this case going back to "1.0.0") and check for that. If that finds a match we'll edit the heading to include the prerelease suffix when we include it in the Announcement. This lets you have a stable heading like # Version 1.0.0 (under development), and prereleases will get headings like # Version 1.0.0-prerelease.1 (under development).
+If none of the previous rules apply, "1.0.0-prerelease.1" will also match a special "Unreleased" heading (i.e. "# Unreleased"), which will get rewritten to "# Version 1.0.0-prerelease.1". This lets you maintain a changelog for a pending release without having to commit to what version it will be.
+
+
+Now that we've looked at a simple example with cargo new, let's start looking at ways to make a Cargo Workspace more complicated, and how cargo-dist will deal with them.
+But first, let's define some precise terminology:
+Rust projects typically exist as a single Workspace, which is a collection of one or more Packages that are all developed in the same repository (crates.io dependencies are not considered part of the workspace). A workspace always has a root Cargo.toml where certain workspace-global settings are defined.
+If the root Cargo.toml doesn't define a Package then we say it's a Virtual Workspace. A Virtual Workspace puts all the packages on the same level, treating them as equals. If you don't use a Virtual Workspace you are essentially saying the entire project exists to produce that one root Package. Both approaches make sense in different contexts. I personally prefer virtual workspaces because it makes cargo (and other tools) default to operating on all packages at once, which is usually what I want (e.g. I want cargo test to test the entire workspace, I want cargo fmt to format the whole workspace, and so on).
+A Package is the thing defined by a Cargo.toml (except for the root Cargo.toml of a Virtual Workspace, which defines no package). Many people reasonably assume "Package" and "Crate" are synonyms -- after all you host your Packages on a website called "crates.io"! As it turns out, this is not the case: a Package can in fact define multiple Crates at the same time.
+A Crate is the actual unit of compilation that rustc thinks about, like a single library or binary. For the purposes of cargo-dist, you don't really need a perfect understanding of what is or isn't a "crate". The important takeaway is that a single Package can contain multiple things that are conflated with a single unified name and version. As we'll see, this can be useful.
+
+So here's where the difference between a "Package" and a "Crate" is most relevant: Cargo lets a single Package define multiple binaries. See those docs for all the details. This can be convenient if you want to produce a single logical application that provides a suite of CLIs. For instance, you might want to make a standalone "my-tool" CLI that can be invoked as cargo my-tool as well. The easiest way to do this is to define a second "cargo-my-tool" binary as part of the "my-tool" Package. Once you do, cargo install my-tool will install both!
+cargo-dist tries to respect this semantic. If you define multiple binaries in a Package, we will treat the Package as one "Application" and bundle both binaries in all zips and installers for that App. There is no way to override this behaviour -- if you don't want two binaries to be considered part of the same App, you should use separate Packages.
+
+Alright here's where things get a bit more complicated and you need to make a decision on how exactly you plan to develop and release the packages that make up your project. Up until now we've been assuming you have a single package in your workspace, but now we're going to deal with more.
+How cargo-dist interprets multiple packages is actually fairly simple:
+
+- Each Package that defines binaries is considered an "App" with completely independent zips/installers
+- Each Package that doesn't define binaries is wholly irrelevant and ignored
+
+If a Package defines binaries but you want cargo-dist to ignore it just like it does with library-only packages (i.e. because the binaries are for local testing), you can do that with either:
+
+Now here's the really important question you need to answer: how do you want to announce new versions of your packages?
+
+
+See the guide on using cargo-dist with cargo-release for more detailed documentation of how to tag your commits in various workspace configurations!
+
+When you push a Git Tag to your repository, cargo-dist's CI will try to create a single Announcement (A Github Release) for that tag. When you only have one Package that's a completely unambiguous operation. When you have multiple Packages we now need some way to disambiguate what you actually meant.
+1 Git Tag = 1 cargo-dist Announcement = 1 Github Release
+cargo-dist supports two forms of Announcement which you can select with the format of your Git Tag:
+
+- Unified Announcement: VERSION selects all packages with the given version (v1.0.0, 0.1.0-prerelease.1, releases/1.2.3, ...)
+- Singular Announcement: PACKAGE-VERSION or PACKAGE/VERSION selects only the given package (my-app-v1.0.0, my-app/1.0.0, release/my-app/v1.2.3-alpha, ...)
+
+
+People love their different tag formats, so we do our best to parse lots
+of different kinds! Prefixing the version with v is optional. Anything
+that comes before a / is ignored unless it's exactly a package name
+(so really/cool/5.0.0/releases/v1.0.0 is just read as "1.0.0"). Note
+that something like "1.0" is not a valid Cargo SemVer Version.
+
+These two modes support the following workflows:
+
+- Releasing a workspace with only one App (either mode works but Unified is Best)
+- Releasing a workspace where all Apps are versioned in lockstep (Unified)
+- Releasing an individual App in a workspace with its own independent versioning (Singular)
+- Releasing several Apps in a workspace at once, but all independently (Push multiple Singular tags at once)
+
+
+NOTE: Although you could use extremely careful versioning in conjunction with Unified Announcements to release a weird subset of the packages in your workspace, you really shouldn't because the Github Releases will be incoherent (v0.1.0 has these random packages, v0.2.0 has these other random packages... huh?), and you're liable to create painful tag collisions.
+
+The need for a coherent Announcement Tag is so important that cargo-dist commands like "build" and "manifest" will error out if one isn't provided and it can't be guessed. If that happens you may need to pass an explicit --tag=... flag to disambiguate. Being this strict helps catch problems before you push to CI.
+
+Normally cargo-dist will error out if the Announcement Tag selects no Apps, because it exists to build and distribute Apps and you just asked it to do nothing (which is probably a mistake). This would however create annoying CI errors if you just wanted to tag releases for your libraries.
+For 0.0.3 I opted for this kind of weird half-functionality:
+cargo-dist will produce a very minimal build-less Announcement (and therefore Github Release) if you explicitly request a Singular Announcement that matches a library-only package. This feature is kind of half-baked, please let us know what you want to happen in this situation!
+We'll probably have to add a config for specifying whether you want libraries to get Announcements or not when you push a singular tag for them.
+
+See the dedicated guide to using cargo-release with cargo-dist, which covers all sorts of nasty workspaces (it's also just a more useful in-depth look at ).
+
+
+
+NOTE: It will be helpful to read the section on cargo-dist Announcement Tags, because that is the interface boundary between cargo-release and cargo-dist. TL;DR: cargo-dist interprets a git tag of "v1.0.0" as "Announce/Release the whole workspace" (Unified Announcement) and "my-app-v1.0.0" or "my-app/v1.0.0" as "Announce/Release that one package" (Singular Announcement).
+
+
+NOTE: this guide assumes you're running cargo-release v0.22.0 or greater, as that version made several significant changes to default behaviours (for the better!).
+
+cargo-dist intentionally doesn't handle these steps of cutting a release for you:
+
+- updating the versions of your packages
+- writing your release notes
+- committing the results
+- tagging your commits
+- pushing to your repo
+- publishing to crates.io
+
+There's a lot of different workflows for these things and we're happy to leave that to you. All cargo-dist cares about is that a tagged commit eventually ends up in your repo (and that the format of that commit reflects the versions/names in your Cargo.tomls).
+That said, you might find cargo-release useful because it can handle all of the above things for you in a single command like cargo release 1.0.0. This section is dedicated to explaining how to use cargo-release with cargo-dist in various situations.
+
+
+NOTE: cargo-release will never do anything side-effectful unless you also pass it --execute. Unless otherwise specified, we are discussing the behaviour when that flag is passed, but will be omitting it for safety/brevity.
+
+In a simple project with one package, without any configuration set for cargo-release, the command cargo release 1.0.0 is roughly sugar for:
+<does some basic checks for uncommitted files and upstream being ahead>
+<edits your Cargo.toml to have version 1.0.0>
+git commit -am "chore: Release my-app version 1.0.0"
+git tag v1.0.0
+cargo publish
+git push --atomic <remote-branch> refs/tags/v1.0.0
+
+(The git push --atomic is basically a more robust version of git push && git push --tags)
+Hey neat that's basically everything I listed at the start of this section! And the tag format is exactly what cargo-dist expects for a simple project!! What a coincidence!!! 😸
+If you don't want some of these behaviours, you can disable them permanently with [workspace.metadata.release] in your Cargo.toml, or disable temporarily with CLI flags. See the cargo-release reference for all the details but here's some important ones to only get a subset of the behaviours:
+
+- Don't want to publish? Set
publish = false in the config or pass --no-publish
+- Don't want to push? Set
push = false in the config or pass --no-push
+- Don't want to tag? Set
tag = false in the config or pass --no-tag
+
+See this section for specific details on using cargo-release with github pull requests (PRs).
+Note also that you can use [package.metadata.release] to set configs on individual packages and not the whole workspace.
+
+With a more complex project/workspace, cargo-release won't work as well out of the box with cargo-dist. To understand why, we need to understand the rules it applies consistently that can be strange if unexpected.
+When you run cargo release it should follow the same rules cargo does for selecting the subset of the workspace to operate on. That is, if you were to run cargo test, the packages that actually get tested are the same ones that cargo release will attempt to release! I'll try to briefly summarize (imperfectly, workspaces can get really Complicated):
+
+- When run in the subdirectory of a package, execution is scoped to that package
+- When run in the root of a virtual workspace (where the root Cargo.toml isn't an actual package), execution applies to all packages
+- When run in the root of a non-virtual workspace (where the root Cargo.toml is probably the "main" package that all other packages exist to implement), execution only applies to the root package.
+- When run with
--workspace, execution applies to all packages (good for making a non-virtual workspace behave more like a virtual one).
+- Specific packages can be selected with
-p/--package
+- I haven't checked if cargo-release respects default-members but that's a thing too!
+
+By default, cargo-release will create a separate git tag for every package it's releasing. The default format of these tags depends on the shape of your workspace:
+
+- If there is a root package (the workspace is non-virtual), releases of the root package will be tagged as
v{VERSION} ("v1.0.0").
+- All other packages will be tagged
{PACKAGE_NAME}-v{VERSION} ("my-app-v1.0.0")
+
+As we'll see below, these combined behaviours have the following interactions with cargo-dist:
+
+- ✅ one package workspace: tags it like "v1.0.0"
+- ✅ virtual workspace, independent versions: tags each package like "my-app-v1.0.0"
+- ✅ virtual workspace, independent versions: tags each package like "my-app/v1.0.0" (needs additional configuration in cargo-release, see below)
+- ❌ virtual workspace, unified versions: we want a single tag like "v1.0.0"
+- ❌ non-virtual workspace: it will mix the tag formats, which might be ok in one situation
+
+Now let's dig into each of these situations in more detail.
+
+TLDR: cargo-release Just Works.
+cargo release 1.0.0
+
+
+As stated previously, cargo-release works great with cargo-dist if you have a simple project consisting of a single package (the kind of project cargo new my-app or cargo init my-app will create).
+See the previous sections for what this will do and how to configure the behaviour if, e.g. you want to hold off on publishing to crates.io or pushing.
+The more general version of this situation -- where you have one root package and all the other workspace members are libraries that exist to implement it -- has two possible solutions depending on how you want to version/release the libraries:
+
+
+TLDR: cargo-release just needs you to specify which package to release.
+cargo release -p my-package 1.0.0
+
+
+If you have a virtual workspace (one where the root Cargo.toml isn't an actual package) and want everything in the workspace to be versioned/released independently, then cargo-dist will default to operating on all your packages at once, and you should do the same thing you would do if you were running cargo publish: either use -p to select the relevant packages or cd into the subdir of that package before running the command.
+Each tag will induce cargo-dist to produce an independent Announcement (Github Release) for that package.
+If the package is a library the Github Release won't have any builds/artifacts uploaded. See here for details.
+Note that we currently don't support finding/emitting Release Notes for Singular Releases (simply haven't had time to design and implement it yet).
+
+For cargo-release to work with tag prefixes that use a slash, you must configure it to use a different prefix for tags in Cargo.toml.
+For a virtual workspace, put the following in your root Cargo.toml:
+[workspace.metadata.release]
+tag-prefix = "{{crate_name}}/"
+
+Please refer to the cargo-release reference for further information on how you can configure cargo-release.
+
+TLDR: cargo-release just needs you to specify that versioning/tagging should be unified.
+# Add this config to your root Cargo.toml (virtual manifest)
+[workspace.metadata.release]
+shared-version = true
+tag-name = "v{{version}}"
+
+cargo release 1.0.0
+
+
+If you have a virtual workspace (one where the root Cargo.toml isn't an actual package) and want everything in the workspace to be versioned/released in lockstep with a single Unified Announcement (One Big Github Release), then you're going to need to configure cargo-release as above.
+After that it works perfectly, and cargo-release will even automagically handle publishing your packages to crates.io in the right sequence and waiting for the publishes to propagate before running the next one (no more "oops sorry the package you just published isn't actually propagated to the registry yet so the package that depends on it can't be published").
+(See the next section on non-virtual workspaces with unified versions for some grittier details on what's going on here.)
+
+TLDR: this is much the same as the virtual workspace case but you need to pass --workspace on the CLI.
+# Add this config to your root Cargo.toml (virtual manifest)
+[workspace.metadata.release]
+shared-version = true
+tag-name = "v{{version}}"
+
+cargo release 1.0.0 --workspace
+
+
+If you have a non-virtual workspace (one where the root Cargo.toml is a package) and want everything in the workspace to be versioned/released in lockstep with a single Unified Announcement (One Big Github Release), then it's almost the same as the virtual case (see the previous section).
+The one caveat is that cargo-dist is consistent to a fault here, and even though we've explicitly told it things should be versioned/tagged in lockstep, running it in the root of your project still only releases the root package, and that's not what you want!
+We need to tell it that we really meant it and pass --workspace!
+What's happening here is that cargo-release is conceptually defined to run on each package individually, with just the "git push" step being unified. The tagging settings we're providing work because it's basically repeatedly going "oh hey I was already going to make that tag, no need to make it again". It doesn't have a proper notion of the entire workspace being released in perfect lockstep, so if you ask it to release only some of the packages it will happily oblige.
+In the virtual workspace this Just Works because commands in the root directory are implicitly --workspace.
+
+TLDR: this is a more complicated mess because but you probably want to make the root package have the Singular Announcement format, and then you just need to be explicit about each package you want to release on the CLI:
+# Add this config to your root Cargo.toml (main package)
+[package.metadata.release]
+tag-name = "{{crate_name}}-v{{version}}"
+
+cargo release -p my-package 1.0.0
+
+
+If you have a non-virtual workspace (one where the root Cargo.toml is a package) and want everything in the workspace to be versioned/released independently, then the simplest approach is to make everything behave like it does in the Virtual Workspace With Independent Versions.
+However if you find yourself in this position it's likely that your workspace actually looks like:
+
+- root package is The One Application this project exists to develop
+- all other packages are libraries that support it
+
+In this precise configuration you may be able to avoid configuration by adopting a hybrid "Partially Independent Versions" approach as described in the next section.
+
+TLDR: technically this Just Works but you need to be specific about what packages you're publishing and may have annoying issues in the future.
+cargo release -p my-package 1.0.0
+
+
+So if your workspace looks like this:
+
+- root package is The One Application this project exists to develop
+- all other packages are libraries that support it
+
+Whenever you cargo release the root package, it will get tagged without a prefix ("v1.0.0") and cargo-dist will create a Unified Announcement. Even though there are other packages in the workspace, cargo-dist will take this in stride because as far as it's concerned this looks exactly the same as a workspace with one package. Which is to say, it's no different from a simple project as far as cargo-dist is concerned.
+Whenever you cargo release a library, it will get tagged with a prefix ("my-lib-v1.0.0") and cargo-dist will create a minimal Singular Announcement. See here for details. In future versions we might change this default (or at least make it configurable).
+I have some vague concerns that this will be wonky if you ever introduce a second application to the workspace, but honestly that's probably going to be true regardless of if you were using cargo-dist, so maybe it's fine? Really I just don't trust non-virtual workspaces...
+
+cargo-dist really isn't designed for this but technically you can use the Singular Library Trick if you want. If you want cargo-dist to properly support this, please let us know!
+
+cargo-release defaults to dry-run semantics, only doing side-effectful operations if you pass it --execute. It will also do its best to detect problems early and error out if things seem wrong. This absolutely rules!
+There are two things to keep in mind:
+
+- cargo-release's dry-run is imperfect and has some differences from the real run
+- cargo-release isn't aware of cargo-dist, so it can't check if what it's about to do will blow up in CI or not
+
+Let's start with the dry-run differences. I don't know them all but the biggest one that I hit is that it doesn't fully emulate bumping the versions in your Cargo.tomls. Notably when it checks if publish will work, it's building the current version of the packages. If your build is aware of its own version this can cause/miss problems (and you'll see funky stuff like "Upgrading my-app from 1.0.0 to 2.0.0" ... "Packaging my-app 1.0.0").
+As for being aware of cargo-dist... I want to design some features for this, but I'm not quite sure what it should look like yet.
+I think in the short-term, the best I can offer you is "make a temporary git branch and tell cargo-release to --execute but not push/tag/publish, then ask cargo-dist what it thinks extremely manually". A rough sketch:
+# make a temp branch where we can mess stuff up
+git checkout -b tmp-release
+
+# ask cargo-release what it thinks should happen
+# (substitute the actual cargo-release command you'd use here)
+cargo release 1.0.0
+
+That should end with a line that looks like "Pushing main, v1.0.0 to origin". The first item is the branch it's pushing to, all the following items are all the tags it wants to push. Now that we know the tags, we can ask cargo-release to update the package versions and then ask cargo-dist what it thinks of those tags:
+# just bump versions
+cargo release 1.0.0 --execute --no-push --no-tag --no-publish
+
+# ask cargo-dist what should be produced for the given tag
+cargo dist plan --tag=<tag-you-want-to-check>
+
+If that runs successfully and prints out the artifacts you expect, that's pretty good sign running cargo-release For Real will work! (You can also try cargo dist build if you're worried about the actual build failing.)
+
+
+In this section we will be using $BRANCH and $VERSION as placeholders for the branch you make your PR on and the version you want to release.
+
+Many teams have policies that prevent pushing to main, and require you to open pull requests instead. This conflicts with the default behaviour of cargo-release, but it works fine with some extra flags to encourage it to defer the steps until later. Specifically, use the following to "partially" run cargo-release:
+cargo release --no-publish --no-tag --allow-branch=$BRANCH $VERSION
+
+The release process then has the following steps:
+
+- step 0: create a new branch for the PR
+- step 1: < finalize things like changelogs and commit >
+- step 2: partially run
cargo release ... to update your Cargo.tomls and push your branch
+- step 3: < open a pr, review, merge >
+- step 4: fully run
cargo release on main to complete the process (publish and tag)
+
+Crucially, neither invocation of cargo release will modify your main branch directly. Step 4 will only push a git tag for the commit that is already on main.
+Here's what this looks in practice:
+# step 0: make a branch
+git checkout -b $BRANCH
+
+
+# step 1: update things like the changelog
+# < edit some files or whatever here >
+git commit -am "prep release"
+
+
+# step 2: have cargo-release handle tedious mechanical stuff
+# this will:
+# * do some safety checks like "git index is clean"
+# * update version numbers in your crates (and handle inter-dependencies)
+# * git commit -am "chore: release $NAME $VERSION" (one commit for the whole workspace)
+# * git push (remember we're on a branch)
+cargo release --no-publish --no-tag --allow-branch=$BRANCH $VERSION
+
+
+# step 3: open a PR and review/merge to main
+# NOTE: the above steps will result in two commits
+# we recommend using github's "merge and squash" feature to clean up
+# ...
+
+
+# step 4: remove the shackles from cargo release and RUN ON MAIN
+# this will:
+# * tag the commit
+# * push the tag
+# * publish all crates to crates.io (handles waiting for dep publishes to propagate)
+# * trigger cargo-dist when it sees the tag (if applicable)
+# THIS WON'T CREATE NEW COMMITS
+#
+# running "cargo dist plan" is totally optional, but this is is the best time to check
+# that your cargo-dist release CI will produce the desired result when you push the tag
+git checkout main
+git pull
+cargo dist plan
+cargo release
+
+
+Out of the box, cargo-dist's CI configuration is designed to cover the majority of usecases. We provide some tools to customize how it works for your project.
+
+
+since 0.3.0
+
+By default, cargo-dist will run the plan step on every pull request but won't perform a full release build. If these builds are turned on, the resulting pull request artifacts won't be uploaded to a release but will be available as a download from within the CI job. To enable this, select the "upload" option from the "check your release process in pull requests" question in cargo-dist-init or set the pr-run-mode key to "upload" in Cargo.toml's cargo-dist config. For example:
+pr-run-mode = "upload"
+
+
+
+since 0.3.0
+
+cargo-dist's CI can be configured to call additional jobs on top of the ones it has builtin. Currently, we support adding extra jobs to the publish step; in the future, we'll allow extending all of the lifecycle steps of the CI workflow. To add one, you need to follow two steps:
+
+- Define the new job as a reusable workflow using the standard method defined by your CI system. For GitHub actions, see the documentation on reusable workflows.
+- Add the name of your new workflow file to the
publish-jobs array in your Cargo.toml's cargo-dist config, prefixed with a ./. For example, if your job name is .github/workflows/my-publish.yml, you would write it like this:
+
+publish-jobs = ["./my-publish"]
+
+Here's an example reusable workflow written using GitHub Actions. It won't do any real publishing, just echo text to the CI output. First, create a file named .github/workflows/publish-greeter.yml with these contents:
+name: Greeter
+
+on:
+ # Defining workflow_call means that this workflow can be called from
+ # your main workflow job
+ workflow_call:
+ # cargo-dist exposes the plan from the plan step, as a JSON string,
+ # to your job if it needs it
+ inputs:
+ plan:
+ required: true
+ type: string
+
+jobs:
+ greeter:
+ runs-on: ubuntu-latest
+ # This is optional; it exposes the plan to your job as an environment variable
+ env:
+ PLAN: ${{ inputs.plan }}
+ steps:
+ - name: Step 1
+ run: |
+ echo "Hello!"
+ echo "Plan is: ${PLAN}"
+
+Then, add the following to your publish-jobs array:
+publish-jobs = ["./publish-greeter"]
+
+Running cargo-dist init for your tool will update your GitHub Actions configuration to make use of the new reusable workflow during the publish step.
+
+The following sections are more focused on precise details.
+
+
+Here's the section where I use a bunch of Capitalized Words to indicate they are a Special Concept in cargo-dist as I try to explain how it works. These are the "advanced" docs of cargo-dist; see the guide for the "beginner" docs.
+An invocation of cargo-dist has 4 major inputs:
+
+- The structure of your project's Cargo Workspace (via cargo-metadata)
+- The config in your Cargo.toml
[workspace.metadata.dist] (and [package.metadata.dist])
+- The "announcement tag" (e.g.
--tag=v1.0.0)
+- The "artifact mode" (e.g.
--artifacts=all)
+
+The first two define the full "Universe" of your project -- the platforms/binaries/installers that cargo-dist wants to build. The second two tell cargo-dist what subset of the Universe to actually bother with.
+It's important to the structure of cargo-dist that every invocation is aware of the full Universe and how it's being subsetted, because for instance if you want a shell script installer that does platform detection and fetches binaries, it needs to know about all the binaries/platforms it has to select from, even if this particular run of cargo-dist won't build them all!
+First let's look at how cargo-dist computes the Universe.
+
+Each Cargo package in your workspace that has binary targets is considered an App by cargo-dist. cargo-dist exists to build Apps, so making sure you and it agree on is important! (We prefer "App" over "package" because we want the freedom to one day decouple the two concepts -- for now they are strictly equivalent.)
+Most invocations of cargo-dist will start by printing out a brief summary of the Apps that cargo-dist has found:
+
+The summary includes a list of every package in your workspace. If that package defines binaries, they will be listed underneath the package. If the package's listing is greyed out, that means cargo-dist has decided it's either Not An App or that it's not part of the current Announcement (see the Announcement section), along with a parenthetical reason for its rejection, such as: "no binaries", "publish = false", "dist = false", or "didn't match tag".
+In the above example the available Apps are "evil-workspace", "many-bin", and "third-bin". "many-bin" defines two binaries, while the other two Apps only define one.
+To match cargo-install's behaviour, if a package defines multiple binaries then they will be considered part of the same App and zips/installers for it will contain/install all of them. We figure if you went out of your way to have multiple binaries under one package (as opposed to separate packages for each), you did that for a reason! If you don't want that, make separate packages. There is currently no way to group multiple packages into a single App, although there probably will be one day.
+If you don't want a package-with-binaries to be considered an App that cargo-dist should care about, you can use Cargo's own builtin publish = false. You can also use dist = false or dist = true in cargo-dist's own config, which when defined will take priority over publish.
+Things like cdylibs are not picked up by cargo-dist, even though they're similar to binaries. If anyone has a usecase for this we're happy to consider it (although there's some messy issues around Cargo clobbering itself when you define two many things under one package).
+
+Ok so you've defined your App, but what should we actually build for it? Let's look at what cargo dist init --ci=github --installer=shell --installer=powershell --yes dumps into your root Cargo.toml:
+# Config for 'cargo dist'
+[workspace.metadata.dist]
+# The preferred cargo-dist version to use in CI (Cargo.toml SemVer syntax)
+cargo-dist-version = "0.0.3"
+# CI backends to support
+ci = ["github"]
+# The installers to generate for each app
+installers = ["shell", "powershell"]
+# Target platforms to build apps for (Rust target-triple syntax)
+targets = ["x86_64-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-pc-windows-msvc", "aarch64-apple-darwin"]
+
+# The profile that 'cargo dist' will build with
+[profile.dist]
+inherits = "release"
+lto = "thin"
+
+The parts we're really interested in here are "installers", "targets", and [profile.dist].
+First the easy part: profile.dist is the profile cargo-dist will build everything with. We define a separate profile from release so that it can be tuned more aggressively for builds that are longer or more resource-intensive without making it tedious to develop locally.
+The other 3 fields are defining the various Artifacts that should be produced for each App in the workspace (because this is [workspace.metadata] and not [package.metadata]).
+For each entry in targets you will get a build of your App for that platform in the form of an executable-zip.
+For each entry in installers you get that kind of installer for your App. There are two classes of installer: "global" and "local". This will be explained further in the section on artifact modes, but the tl;dr is that "global" installers are one-per-App while "local" installers are one-per-platform-per-app, similar to a Github CI Matrix.
+"shell" and "powershell" are both global installers. There aren't currently any implemented local installers, but those would be things like a windows "msi" or macos "dmg", where you ostensibly want individual installers for each architecture.
+
+cargo-dist's self-generated CI is triggered by pushing git tags with specific formats like "v1.0.0", "my-app-v1.0.0" or "my-app/v1.0.0". Each tag will trigger its own independent run of that CI workflow. That tag defines the subset of the workspace (what packages) we want to produce a single unified Announcement for (i.e. a single Github Release). Every invocation of cargo-dist in that CI run will be passed that git tag with the --tag flag to ensure consensus on what to Announce (and therefore build and upload).
+1 Git Tag = 1 cargo-dist Announcement = 1 Github Release
+Even when not running in CI, this concept of a coherent Announcement Tag is important enough that we will always try to guess one even if none is provided. The "build", "manifest", and "plan" commands will refuse to run if a coherent Announcement Tag can't be determined to help you catch problems before you start pushing to CI. If this happens you will get a printout telling you some options:
+
+Here we have the same workspace we saw in the "defining your apps" section, but we get a complaint from cargo dist manifest:
+
+There are too many unrelated apps in your workspace to coherently Announce!
+Please either specify --tag, or give them all the same version
+
+This introduces the one big rule for Announcements: all the Apps being Announced together have to agree on their Version. We need something to tie the announcement together and "3 random Apps with different Versions" has nothing to use! You should really just have 3 separate Announcements for those Apps. If you disagree, please let us know!
+The error goes on to recommend the two formats for the Announcement Tag:
+
+- Unified Announcement: VERSION selects all packages with the given version (v1.0.0, 0.1.0-prerelease.1, releases/1.2.3, ...)
+- Singular Announcement: PACKAGE-VERSION or PACKAGE/VERSION selects only the given package (my-app-v1.0.0, my-app/1.0.0, release/my-app/v1.2.3-alpha, ...)
+
+These two modes support the following workflows:
+
+- Releasing a workspace with only one App (either mode works but Unified is Cleaner)
+- Releasing a workspace where all Apps are versioned in lockstep (Unified)
+- Releasing an individual App in a workspace with its own independent versioning (Singular)
+- Releasing several Apps in a workspace at once, but all independently (Push multiple Singular tags at once)
+
+In this case the error notes two valid Unified Announcements:
+
+--tag=v0.5.0 will Announce: evil-workspace, third-bin
+--tag=v0.7.6 will Announce: many-bin
+
+This tells us that evil-workspace and third-bin actually already agree on their Version. If we do want a Unified Announcement, we probably want to bring many-bin into agreement, or mark it as publish=false or dist=false.
+Although you could use extremely careful versioning in conjunction with Unified Announcements to release a weird subset of the packages in your workspace, you really shouldn't because the Github Releases will be incoherent (v0.1.0 has these random packages, v0.2.0 has these other random packages... huh?), and you're liable to create painful tag collisions.
+Normally cargo-dist will error out if the Announcement Tag selects no Apps, because it exists to build and distribute Apps and you just asked it to do nothing (which is probably a mistake). This would however create annoying CI errors if you just wanted to tag Individual Releases for your libraries. To make this more pleasant, cargo-dist will produce a very minimal build-less Announcement (and therefore Github Release) if you explicitly request a Singular Announcement that matches a library-only package. This feature is kind of half-baked, please let us know what you want to happen in this situation!
+
+Now that we have a coherent Announcement and therefore have selected what apps we want to Release, we need to select what artifacts we want to build (or get a manifest for). Enumerating the exact artifacts for each invocation of cargo-dist would be tedious and error-prone, so we provide the --artifacts=... flag to specify the Artifact Mode, which is a certain subset of the Universe of all Artifacts:
+
+- "local": artifacts that are per-target platform (executable-zips, symbols, msi installers...)
+- "global": artifacts that are one-per-app (shell installer, npm package...)
+- "all": both global and local (so the whole Universe)
+- "host": the default mode that kind of breaks the rules to let you test things out locally
+
+Let's ignore "host" mode for a bit and focus on the other three. Each one of these is intended to be used for specific tasks.
+
+The "all" Artifact Mode is largely intended for the manifest command, to get a listing of everything that would be produced if you were to push the given tag to CI. Here we check what v0.5.0 would produce for our favourite example workspace:
+cargo dist manifest --tag=v0.5.0 --artifacts=all --no-local-paths
+
+
+If we add --output-format=json we will get the dist-manifest.json that CI uploads to your Github Release:
+cargo dist manifest --tag=v0.5.0 --artifacts=all --no-local-paths --output-format=json
+
+This is the only way that CI uses the flag, but you could also use "all" with build (the default cargo-dist command) if you want to get all the artifacts built at once, although you should probably filter the --targets as discussed in the section on "local".
+cargo dist manifest --artifacts=all --no-local-paths is so useful/common that we provide an alias for it: cargo dist plan. The above can be simplified to:
+cargo dist plan --tag=v0.5.0
+
+cargo dist plan --tag=v0.5.0 -ojson
+
+
+The "global" Artifact Mode allows you to unambiguously create a task that will build all the Artifacts for your Apps that aren't platform-specific and therefore only need to be made once per App:
+cargo dist build --tag=v0.5.0 --artifacts=global --no-local-paths
+
+
+Here we see that it only results in the "shell" and "powershell" installers getting built. The code to generate these should be totally cross-platform, so any runner is suitable for the task. The CI creates one "global" task that uses linux because that's the fast/cheap one.
+
+The "local" Artifact Mode allows you to unambiguously create a task that will build all the Artifacts for your Apps that are platform-specific and therefore should have a copy made for every target platform.
+If you just use this flag bare, cargo-dist will respect the request and try to build for all platforms at once... and this will probably fail, because cross-compilation is hard. Each "local" run should generally use --target to filter down the set of all supported targets to the ones you can confidently build on the current machine (rustc -vV will tell you the "host" target platform if you're not sure).
+In my case it's "x86_64-pc-windows-msvc", so let's try that:
+cargo dist build --tag=v0.5.0 --artifacts=local --target=x86_64-pc-windows-msvc --no-local-paths
+
+
+Note that you can pass --target multiple times to select more than one. Note also that --target is not allowed to select targets that aren't specified by the config your Cargo.toml. This ensures that global installers are consistently aware of all the platform-specific artifacts they can fetch. ("host" mode breaks this rule.) ((Also in theory --installer should work the same for selecting specific installers but it's not well tested because there isn't any reason to ever use that outside of cargo dist init.))
+CI will spin up one "local" task for each of the major desktop platforms, grouping the targets that are easy to build on those platforms together. In the future we might want to spawn one task per target, or at least make that an option you can pick. That said, some Artifacts like macOS universal binaries may find it useful to have multiple targets built on the same machine!
+
+Host mode is the default "do something useful on my machine" mode. It's intended for testing and demoing cargo-dist on your project, and is never used in CI due to its intentionally fuzzy semantics.
+It's currently roughly equivalent to --artifacts=all --target=HOST_TARGET, but HOST_TARGET is allowed to fall outside the set of targets defined in your Cargo.toml, because it's not terribly useful to tell someone trying out cargo-dist on ARM64 Linux that their platform isn't defined in the config.
+In principle when we have better support for cross-compilation we might also try to build "nice" crosses like "intel apple => arm64 apple". Do not rely on the behaviour of this mode, always use one of the 3 other modes in your infra/scripts!
+If you do pass --target in host mode then we won't do fuzzy target selection and will just build the targets you ask for like normal.
+
+Ok so here's what goes through cargo-dist's brains when you run it:
+
+- Read in the workspace/config/cli-flags
+- Determine the Announcement Tag (select the Apps) ("v1.0.0")
+- Determine what Targets we're building for
+- Call the specific Version of each App a "Release" ("my-app-v1.0.0")
+- For each Release-Target pair, create a "ReleaseVariant" ("my-app-v1.0.0-x86_64-apple-darwin")
+- Add executable-zip Artifacts to each Release (broadcasted to each Variant, filtered by Artifact Mode)
+- Add all the enabled Installers to each Release (local ones broadcasted to each Variant, filtered by Artifact Mode)
+- Compute the Build Steps necessary to produce each Artifact ("run cargo, copy this file, ...")
+- Generate top-level Announcement info like the body for a Github Release
+- run the Build Steps (ignored by
manifest/plan)
+- print a manifest of the computed Announcement/Releases/Artifacts
+
+CI will parse the resulting (--output-format=json) manifest of each build invocation to know what artifacts were produced and need to be uploaded to the Github Release.
+CI will just invoke cargo-dist in the following sequence:
+
+- create-release:
cargo dist manifest --artifacts=all --output-format=json --no-local-paths
+- upload-artifacts (local):
cargo dist build --artifacts=local --target=... --output-format=json
+- upload-artifacts (global):
cargo dist build --artifacts=global --output-format=json
+- publish-release: none, just marks the Github Release as a non-draft
+
+(All the upload-artifacts tasks are in parallel, and there are multiple "local" tasks to cover the target platforms.)
+
+
+cargo-dist accepts configuration from the following sources, in order of increasing preference (that is, CLI flags generally replace things specified in your Cargo.toml):
+
+- Relevant Cargo.toml fields like "repository" and "readme"
+[workspace.metadata.dist][package.metadata.dist]- CLI flags
+
+As discussed in concepts, all of your config should be persistently stored in the first 3 locations so that every run of cargo-dist agrees on what "build everything" should look like. CLI flags should primarily be used to select subsets of that "everything" for an individual run of cargo-dist to care about.
+
+The builtin Cargo.toml fields define a lot of things that cargo-dist cares about. Here's the ones that matter:
+
+The name of your package will become the name cargo-dist uses to refer to your package. There is currently no notion of a "prettier display name" (if you have a use for that, let us know!).
+
+The version of your package is used pervasively, and cargo-dist will generally error out if you ask it to build "my-app-1.0.0" when the actual "my-app" package is set to version "1.1.0".
+
+If you set publish = false in your Cargo.toml we will treat this as a hint that cargo-dist should ignore all the affected packages completely. You can override this with dist's own dist = true config.
+
+If you set publish-prereleases = true, cargo-dist will publish prerelease versions to package managers such as Homebrew. By default, cargo-dist will only publish stable versions.
+
+cargo-dist has an internal notion of an "artifact download URL" that is required for things like installers that detect the current platform and fetch binaries. If your CI backend is "github" then we will base the "artifact download URL" on the "repository" key. To be safe, we will only do this if your workspace agrees on this value. It's fine if only some packages bother setting "repository", as long as the ones that do use the exact same string. If they don't we will fail to compute an "artifact download URL", emit a warning, and ignore your request for installers that require it. (This might want to be a hard error in the future.)
+
+cargo-dist defaults to trying to include certain "important" static files in your executable-zips. A README is one of them.
+If you specify a path to a README file, cargo-dist will use that for all the packages it affects. If you don't, then cargo-dist will search for a README* file in the package's root directory and the workspace's root directory (preferring the package).
+
+cargo-dist defaults to trying to include certain "important" static files in your executable-zips. A LICENSE is one of them.
+If you specify a path to a license file, cargo-dist will use that for all packages it affects. Otherwise, cargo-dist will search for LICENSE* or UNLICENSE* files in the package's root directory and the workspace's root directory (preferring the package). If multiple are defined in the same directory, we will grab them all (this is necessary for the extremely common dual MIT/Apache license, which often results in two LICENSE-* files).
+Note that the Cargo license-file flag only accepts one path, so it can't handle the dual-license-file case. This cargo feature largely exists as an escape hatch for weird licenses which can't be described by the SPDX format of the "license" field.
+
+Cargo allows other tools to include their own project-wide settings in metadata tables. The one cargo-dist uses is [workspace.metadata.dist], which must appear in your root Cargo.toml (whether or not it's virtual). You can override them on a per-package basis with [package.metadata.dist], which accepts all the same fields (except for those which must be specified once globally, see the docs for each individual option).
+
+
+since 0.0.3
+
+Example: cargo-dist-version = "0.0.3"
+This can only be set globally
+This is added automatically by cargo dist init, and is a recording of its own version for the sake of reproducibility and documentation. When you run generate the resulting CI scripts will use that version of cargo-dist to build your applications.
+The syntax must be a valid Cargo-style SemVer Version (not a VersionReq!).
+If you delete the key, generate will just use the version of cargo-dist that's currently running.
+
+
+since 0.0.3 (deprecated in 0.1.0)
+
+Example: rust-toolchain-version = "1.67.1"
+
+Deprecation reason: rust-toolchain.toml is a more standard/universal mechanism for pinning toolchain versions for reproducibility. Teams without dedicated release engineers will likely benefit from unpinning their toolchain and letting the underlying CI vendor silently update them to "some recent stable toolchain", as they will get updates/improvements and are unlikely to have regressions.
+
+This can only be set globally
+This is added automatically by cargo dist init, recorded for the sake of reproducibility and documentation. It represents the "ideal" Rust toolchain to build your project with. This is in contrast to the builtin Cargo rust-version which is used to specify the minimum supported Rust version. When you run generate the resulting CI scripts will install that version of the Rust toolchain with rustup. There's nothing special about the chosen value, it's just a hardcoded "recent stable version".
+The syntax must be a valid rustup toolchain like "1.60.0" or "stable" (should not specify the platform, we want to install this toolchain on all platforms).
+If you delete the key, generate won't explicitly setup a toolchain, so whatever's on the machine will be used (with things like rust-toolchain.toml behaving as normal). Before being deprecated the default was to rustup update stable, but this is no longer the case.
+
+
+since 0.0.3
+
+Example: ci = ["github"]
+This can only be set globally
+This is a list of CI backends you want to support, allowing subsequent runs of generate to know what CI scripts to generate. Its presence also enables certain CI-specific features. For instance if "github" is included we'll try to generate the body for a Github Release and tell installers to fetch binaries from a Github Release. Once we introduce more CI backends we'll need to more completely rationalize what that means. In all likelihood each set of CI scripts will need to explicitly select just its own CI by passing --ci=... for every invocation.
+"github" is currently the only supported CI backend.
+cargo dist init can set this if you pass --ci=...
+
+
+since 0.3.0
+
+Example: allow-dirty = ["ci"]
+This is a list of generate tasks for cargo-dist to ignore when checking if generated configuration is up to date. It's useful for users who customize their own configuration beyond cargo-dist's generated defaults and want to avoid cargo-dist overwriting it.
+
+
+since 0.0.3
+
+Example: targets = ["x86_64-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-pc-windows-msvc"]
+This is a list of target platforms you want your application(s) to be built for. In principle this can be overridden on a per-package basis but that is not well tested.
+In v0.0.5 the only properly supported choices are:
+
+- x64 macOS: "x86_64-apple-darwin"
+- x64 Windows: "x86_64-pc-windows-msvc"
+- x64 Linux: "x86_64-unknown-linux-gnu"
+- arm64 macOS (Apple silicon): "aarch64-apple-darwin" (supported added in v0.0.4)
+
+Future versions should hopefully introduce proper support for important targets like "musl linux".
+By default all runs of cargo-dist will be trying to handle all platforms specified here at once. If you specify --target=... on the CLI this will focus the run to only those platforms. As discussed in concepts, this cannot be used to specify platforms that are not listed in metadata.dist, to ensure different runs agree on the maximum set of platforms.
+
+
+since 0.0.3
+
+Example: installers = ["shell", "powershell"]
+This is a list of installers you want to be made for your application(s). In principle this can be overridden on a per-package basis but that is not well tested. See the full docs on installers for the full list of values.
+See "repository" for some discussion on the "Artifact Download URL".
+
+
+since 0.2.0
+
+Example: tap = "axodotdev/homebrew-formulae"
+This is the name of a GitHub repository which cargo-dist should publish the Homebrew installer to. It must already exist, and the token which creates releases must have write access.
+See the installers documentation for more information on Homebrew support.
+
+
+since 0.0.3
+
+Example: include = ["my-cool-file.txt", "../other-cool-file.txt", "./some/dir/"]
+This is a list of additional files or directories to copy into the root of all executable-zips that this setting affects. The paths are relative to the directory of the Cargo.toml that you placed this setting in. Globs are not supported.
+
+
+since 0.0.3
+
+Example: auto-includes = false
+Allows you to specify whether cargo-dist should auto-include README, (UN)LICENSE, and CHANGELOG/RELEASES files in executable-zips. Defaults to true.
+
+
+since 0.0.5
+
+Example: windows-archive = ".tar.gz"
+Allows you to specify the file format to use for executable-zips that target windows. The default is
+".zip". Supported values:
+
+- ".zip"
+- ".tar.gz"
+- ".tar.xz"
+- ".tar.zstd"
+
+See also unix-archive below.
+
+
+since 0.0.5
+
+Example: unix-archive = ".tar.gz"
+Allows you to specify the file format to use for executable-zips that target not-windows. The default is
+".tar.xz". See "windows-archive" above for a complete list of supported values.
+
+
+since 0.0.3
+
+Example: dist = false
+Specifies whether cargo-dist should ignore this package. It primarily exists as an alternative for publish=false or an override for publish=false.
+
+
+since 0.0.6
+
+Example npm-scope = "@axodotdev"
+Specifies that npm installers should be published under the given scope. The leading @ is mandatory. If you newly enable the npm installer in cargo dist init's interactive UI, then it will give you an opportunity to add the scope.
+If no scope is specified the package will be global.
+
+
+since 0.1.0
+
+Example: checksum = "sha512"
+Specifies how to checksum executable-zips. Supported values:
+
+- "sha256" (default) - generate a .sha256 file for each archive
+- "sha512" - generate a .sha512 file for each archive
+- "false" - do not generate any checksums
+
+The hashes should match the result that sha256sum and sha512sum generate. The current format is just a file containing the hash of that file and nothing else.
+Future work is planned to support more robust signed checksums.
+
+
+since 0.1.0
+
+Example: precise-builds = true
+This can only be set globally
+Build only the required packages, and individually.
+See "inferring precise-builds" for the default behaviour.
+By default when we need to build anything in your workspace, we try to build your entire workspace with --workspace. This setting tells cargo-dist to instead build each app individually.
+On balance, the Rust experts we've consulted with find building with --workspace to be a safer/better default, as it provides some of the benefits of a more manual workspace-hack, without the user needing to be aware that this is a thing.
+TL;DR: cargo prefers building one copy of each dependency in a build, so if two apps in your workspace depend on e.g. serde with different features, building with --workspace, will build serde once with the features unioned together. However if you build each package individually it will more precisely build two copies of serde with different feature sets.
+The downside of using --workspace is that if your workspace has lots of example/test crates, or if you release only parts of your workspace at a time, we build a lot of gunk that's not needed, and potentially bloat up your app with unnecessary features.
+If that downside is big enough for you, this setting is a good idea.
+
+Although cargo-dist prefers --workspace builds (precise-builds = false) for the reasons stated above, it will attempt to check if that's possible, and use --package builds if necessary (precise-builds = true).
+If you explicitly set precise-builds = false and we determine --package builds are required, cargo-dist will produce an error. precise-builds = true will never produce an error.
+Precise-builds are considered required when you use any of features, all-features, or default-features and not all of the packages in your workspace have the same values set.
+So for instance if you have several packages in your workspace and only one sets:
+[package.metadata.dist]
+all-features = true
+
+Then we will require precise-builds, and will pass --all-features to only the cargo build for that package. This setting, on the other hand:
+[workspace.metadata.dist]
+all-features = true
+
+Will just make us pass --all-features to cargo build --workspace.
+
+
+since 0.1.0
+
+Example: merge-tasks = true
+This can only be set globally
+Whether we should try to merge otherwise-parallelizable tasks onto the same machine, sacrificing latency and fault-isolation for more the sake of minor effeciency gains.
+For example, if you build for x64 macos and arm64 macos, by default we will generate ci which builds those independently on separate logical machines. With this enabled we will build both of those platforms together on the same machine, making it take twice as long as any other build and making it impossible for only one of them to succeed.
+The default is false. Before 0.1.0 it was always true and couldn't be changed, making releases annoyingly slow (and technically less fault-isolated). This config was added to allow you to restore the old behaviour, if you really want.
+
+
+since 0.1.0
+
+Example: fail-fast = true
+This can only be set globally
+Whether failing tasks should make us give up on all other tasks. (defaults to false)
+When building a release you might discover that an obscure platform's build is broken. When this happens you have two options: give up on the release entirely (fail-fast = true), or keep trying to build all the other platforms anyway (fail-fast = false).
+cargo-dist was designed around the "keep trying" approach, as we create a draft Release
+and upload results to it over time, undrafting the release only if all tasks succeeded.
+The idea is that even if a platform fails to build, you can decide that's acceptable
+and manually undraft the release with some missing platforms.
+(Note that the dist-manifest.json is produced before anything else, and so it will assume
+that all tasks succeeded when listing out supported platforms/artifacts. This may make
+you sad if you do this kind of undrafting and also trust the dist-manifest to be correct.)
+Prior to 0.1.0 we didn't set the correct flags in our CI scripts to do this, but now we do.
+This flag was introduced to allow you to restore the old behaviour if you prefer.
+
+
+since 0.2.0
+
+Example: create-release = false
+This can only be set globally
+Whether we should create the Github Release for you in your Release CI.
+If true (default), cargo-dist will create a new Github Release and generate
+a title/body for it based on your changelog.
+If false, cargo-dist will assume a draft Github Release for the current git tag
+already exists with the title/body you want, and just upload artifacts to it.
+At the end of a successful publish it will undraft the Github Release.
+
+
+since 0.1.0
+
+Example: install-path = "~/.my-app/"
+The strategy that script installers (shell, powershell) should use for selecting a path to install things at, with 3 possible syntaxes:
+
+-
+
CARGO_HOME: (default) installs as if cargo install did it (tries $CARGO_HOME/bin/, but if $CARGO_HOME isn't set uses $HOME/.cargo/bin/). Note that we do not (yet) properly update some of the extra metadata files Cargo maintains, so Cargo may be confused if you ask it to manage the binary.
+
+-
+
~/some/subdir/: installs to the given subdir of the user's $HOME
+
+-
+
$SOME_VAR/some/subdir: installs to the given subdir of the dir defined by $SOME_VAR
+
+
+
+NOTE: $HOME/some/subdir is technically valid syntax but it won't behave the way you want on Windows, because $HOME isn't a proper environment variable. Let us handle those details for you and just use ~/subdir/.
+
+All of these error out if none of the required env-vars are set to a non-empty value.
+We do not currently sanitize/escape the path components (it's not really a security concern when the user is about to download+run an opaque binary anyway). In the future validation/escaping of this input will become more strict. We do appear to correctly handle spaces in paths on both windows and unix (i.e. ~/My cargo-dist Documents/bin/ works), but we won't be surprised if things misbehave on Interesting Inputs.
+Future Improvements:
+
+(Please file an issue if you have other requirements!)
+
+
+since 0.2.0
+
+Example: features = ["serde-support", "fancy-output"]
+Specifies feature-flags that should be passed to a package when building it. This lets you enable features that should be on "in production" but for whatever reason shouldn't be on by default.
+For instance for packages that are a library and a CLI binary, some developers prefer to make the library the default and the CLI opt-in. In such a case you would want to add features = ["cli"] to your [package.metadata.dist].
+If you use this you probably want to set it on [package.metadata.dist] and
+not [workspace.metadata.dist]. See "inferring precise-builds" for details.
+
+
+since 0.2.0
+
+Example: default-features = false
+Specifies that default features for a package should be enabled when building it (when set to false, this tells us to pass --no-default-features to Cargo).
+Defaults true.
+If you use this you probably want to set it on [package.metadata.dist] and not [workspace.metadata.dist]. See "inferring precise-builds" for details.
+
+
+since 0.2.0
+
+Example: all-features = true
+Specifies that all features for a package should be enabled when building it (when set to true this tells us to pass --all-features to Cargo).
+Defaults false.
+If you use this you probably want to set it on [package.metadata.dist] and
+not [workspace.metadata.dist]. See "inferring precise-builds" for details.
+
+Several metadata.dist configs have globally available CLI equivalents. These can be used to select a subset of metadata.dist list for that run. If you don't pass any, it will be as-if you passed all the values in metadata.dist. You can pass these flags multiple times to provide a list. This includes:
+
+--target--installer--ci
+See Artifact Modes for how you might use this kind of subsetting.
+Caveat: the default "host" Artifact Mode does something fuzzier with --target to allow you to build binaries that are usable on the current platform. Again see Artifact Modes.
+
+
+cargo-dist's primary role is to produce "Artifacts", either to use locally or to upload as part of a release announcement. Here's a listing of the supported kinds!
+
+executable-zips are the primary output of cargo-dist: a zip (or tarball) containing prebuilt executables/binaries for an app, along with additional static files like READMEs, LICENSES, and CHANGELOGs.
+When you tell us to build an App for a platform we will make an executable-zip for it. Global installers will fetch and unpack executable zips from wherever you uploaded them (currently Github Releases).
+You can modify what files get included with the include and auto-includes configs.
+Currently we always make .zip on windows and .tar.xz elsewhere. This will be made configurable.
+Some notes on how we build your executables:
+
+
+This feature is currently disabled pending a rework, but basically we want to save your debuginfo in the form of pdbs, dSYMs, etc. This should automatically happen as a side-effect of requiring executable-zips with the appropriate build settings to generate them.
+
+Most other kinds of artifact are referred to as "installers", because they generally exist as ways of downloading and installing the binaries that were made for the executable-zips.
+See the full docs on installers for details.
+
+
+The core functionality of cargo-dist is to build your binaries and produce tarballs/zips containing them. Basically every other kind of file it produces is considered an "installer" that helps download/install those binaries.
+
+Currently all supported installers are "global"/"universal" installers that detect the current platform and download and unpack the appropriate tarball/zip. This currently requires CI support to be enabled so we can ensure the files are hosted somewhere and know where to fetch them from.
+In the future we will allow you to specify the download URL manually, and will enable more self-contained "vendored" installers like Windows .msi and macOS .dmg/.app, as well as various package-managers.
+
+
+Currently supported installers include:
+
+- "shell": a shell script that fetches and installs executables
+- "powershell": a powershell script that fetches and installs executables
+- "npm": an npm project that fetches and runs executables (e.g. via npx)
+- "homebrew": a Homebrew formula that fetches and installs executables
+
+These keys can be specified via installer in your cargo-dist config. The cargo dist init command provides an interactive UI for enabling/disabling them.
+
+
+since 0.0.3
+
+This provides a shell script (installer.sh) which detects the current platform, fetches the best possible executable-zip from your artifact download URL, copies the binary into your install-path, and attempts to add that path to the user's PATH (see the next section for details).
+This kind of installer is ideal for bootstrapping setup on a fairly bare-bones system.
+An "installer hint" will be provided that shows how to install via curl | sh, like so:
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.0.5/cargo-dist-v0.0.5-installer.sh | sh
+
+Limitations/Caveats:
+
+In an ideal world all of these caveats improve (except for maybe relying on tar/unzip/curl/wget, that's kinda fundamental).
+
+Here is a more fleshed out description of how the shell installer attempts to add the install-path to the user's PATH, and the limitations of that process.
+The most fundamental limitation is that installers fundamentally cannot edit the PATH of the currently running shell (it's a parent process). Only an explicit source some_file (or the more portable . some_file) can do that. As such, it benefits an installer to try to install to a directory that will already be on PATH (such as CARGO_HOME). Otherwise all we can do is prompt the user to run source themselves after the installer has run (or restart their shell to freshly source rcfiles).
+The process we use to add install-path to the user's PATH is roughly the same process that rustup uses (hopefully making us harmonious with running rustup before/after one of our installer scripts). In the following description we will use $install-path as a placeholder for the path computed at install-time where the binaries get installed. Its actual value will likely look something like $HOME/.myapp or $HOME/.cargo/bin.
+
+- we generate a shell script and write it to
$install-path/env (let's call this $env-path)
+
+- the script checks if
$install-path is in PATH already, and prepends it if not
+- prepending is used to ideally override system-installed binaries, as that is assumed to be desired when explicitly installing with not-your-system-package-manager
+- the
env script will only be added if it doesn't already exist
+- if
install-path = "CARGO_HOME", then $env-path will actually be in the parent directory, mirroring the behaviour of rustup
+
+
+- we add
. $env-path to $HOME/.profile
+
+
+- if
$HOME/.profile was edited, we prompt the user to source "$env-path" or restart their shell
+
+- although this is less portable than
. "$env-path", it's very easy to misread/miscopy the portable version (not as much of a concern for an rcfile, but an issue for humans)
+- hopefully folks on platforms where this matters are aware of this issue (or they can restart their shell)
+
+
+
+
+
+since 0.0.3
+
+This provides a powershell script (installer.ps1) which detects the current platform, fetches the best possible executable-zip from your artifact download URL, copies the binary into your install-path, and attempts to add that path to the user's PATH (see the next section for details).
+This kind of installer is ideal for bootstrapping setup on a fairly bare-bones system.
+An "installer hint" will be provided that shows how to install via irm | iex (the windows equivalent of curl | sh), like so:
+irm https://github.com/axodotdev/cargo-dist/releases/download/v0.0.5/cargo-dist-v0.0.5-installer.ps1 | iex
+
+Limitations/Caveats:
+
+On the scale of Windows (where many people are still running Windows 7) commands like "Expand-Archive" and "tar" are in fact relatively new innovations. Any system that predates 2016 (PowerShell 5.0) certainly has no hope of working. I believe that someone running Windows 10 is basically guaranteed to work, and anything before that gets sketchier.
+In an ideal world most of these caveats improve (except for maybe the requirement of PowerShell >= 5.0 which is not pleasant to push past).
+
+Here is a more fleshed out description of how the powershell installer attempts to add the install-path to the user's PATH, and the limitations of that process.
+The most fundamental limitation is that installers fundamentally cannot edit the PATH of the currently running shell (it's a parent process). Powershell does not have an equivalent of source, so to the best of our knowledge restarting the shell is the only option (which if using Windows Terminal seems to mean opening a whole new window, tabs aren't good enough). As such, it benefits an installer to try to install to a directory that will already be on PATH (such as CARGO_HOME). (rustup also sends a broadcast WM_SETTINGCHANGE message, but we couldn't find any evidence that this does anything useful.)
+The process we use to add install-path to the user's PATH is roughly the same process that rustup uses (hopefully making us harmonious with running rustup before/after one of our installer scripts). In the following description we will use $install-path as a placeholder for the path computed at install-time where the binaries get installed. Its actual value will likely look something like C:\Users\axo\.myapp or C:\Users\.cargo\bin.
+
+- we load from the registry
HKCU:\Environment's "Path" Item
+- we check if
$install-path is contained within it already
+- if not, we prepend it and write the value back
+
+- prepending is used to ideally override system-installed binaries, as that is assumed to be desired when explicitly installing with not-your-system-package-manager
+
+
+- if we edited the registry, we prompt the user to restart their shell
+
+
+
+since 0.0.6
+
+This provides a tarball containing an npm package (npm-package.tar.gz) which when installed into an npm project: detects the current platform, fetches the best possible executable-zip from your artifact download URL, and copies the binary into your node_modules. This can be used to install the binaries like any other npm package, or to run them with npx.
+This kind of installer is ideal for making a native Rust tool available to JS devs.
+An "installer hint" will be provided that shows how to install via npm like so:
+npm install @axodotdev/cargodisttest@0.2.0
+
+cargo-dist does not publish the package for you, you need to do that manually once the tarball is built. Conveniently, npm supports publishing from a url-to-a-tarball directly, and since 0.0.7 we make our tarballs look like "proper" npm package tarballs, so you can just do this:
+npm publish URL_TO_TARBALL
+
+You can find the URL to the tarball at the bottom of the Github Release, inside the collapsible "assets" dropdown (*-npm-package.tar.gz). The format of the url is:
+<repo>/releases/download/<tag>/<app-name>-npm-package.tar.gz
+
+Example:
+https://github.com/axodotdev/oranda/releases/download/v0.0.3/oranda-npm-package.tar.gz
+If you're cutting a stable release (not-prerelease), you can use the "latest" URL format:
+https://github.com/axodotdev/oranda/releases/latest/download/oranda-npm-package.tar.gz
+In the future we may introduce more streamlined CI-based publishing workflows.
+You can set the @scope the package is published under with the npm-scope cargo-dist config.
+We will otherwise do our best to faithfully translate any standard Cargo.toml values you set to an equivalent in the npm package.json format (name, version, authors, description, homepage, repository, keywords, categories...).
+The package will also include an npm-shrinkwrap.json file for the npm packages the installer uses, this is the same as package-lock.json but "really for reals I want this to be respected even if it's installed into another project". Note that cargo install similarly disrespects Cargo.lock unless you pass --locked.
+Limitations/Caveats:
+
+As a result of the .tar.gz limitation, cargo dist init will prompt you to change windows-archive and unix-archive to ".tar.gz" if you enable the npm installer, erroring if you decline.
+
+
+since 0.2.0
+
+This provides a Homebrew formula which allows users to brew install your package. Since it installs to a location on the user's PATH, it provides a simple and convenient installation method for users who already have Homebrew available. When published to a tap (package repository), this gives your users an easy way to both install your package and to keep it up to date using brew update and brew upgrade. It fetches the same prebuilt macOS binaries as the shell installer.
+cargo-dist can, optionally, publish your formula to a tap repository for you on every release. To enable this, add a tap field to your Cargo.toml pointing to a GitHub repository that you control and add homebrew to the publish-jobs field. The repository name must start with homebrew-. For example:
+tap = "axodotdev/homebrew-formulae"
+publish-jobs = ["homebrew"]
+
+In order to write to a tap GitHub repository, cargo-dist needs a personal access token with the repo scope exposed as HOMEBREW_TAP_TOKEN. For more information on GitHub Actions secrets, consult this documentation.
+Limitations/Caveats:
+
+- Does not support creating a formula which builds from source
+- Does not support Linuxbrew (Homebrew on Linux)
+- Does not support Cask for more convenient GUI app installation
+
+
+All installers which rely on detecting the current platform and fetching "your" executable-zips (archives) to install prebuilt binaries need to know where to fetch from. They do this by combining a base URL with the precomputed name of the archive. That base URL is the Artifact Download URL.
+The Artifact Download URL effectively mandates that all archives for a Release must be stored in the same directory (or pretend to be with redirects), and must have the exact name that cargo-dist selected for them.
+The Artifact Download URL is currently on defined if:
+
+"Agree" here means that:
+
+- At least one crate defines the key
+- Every other crate that bothers to set the key has the same value (modulo trailing "/")
+
+If this is the case, then it will be:
+{{repository}}/releases/download/{{tag}}
+
+For instance the Artifact Download URL for cargo-dist 0.0.5 is:
+https://github.com/axodotdev/cargo-dist/releases/download/v0.0.5/
+
+In the future this will be made more configurable.
+
+cargo-dist theoretically allows you to build executable-zips with any of the following formats:
+
+- .tar.gz
+- .tar.xz
+- .tar.zstd
+- .zip
+
+(See windows-archive and unix-archive for details and defaults)
+But that doesn't necessarily mean a random user can unpack those formats, and that especially doesn't mean an installer that's trying to bootstrap the installation by fetching one of those archives can. This section serves to document some known limitations of various systems' builtin unpacking utilities.
+
+-
+
On unix-y platforms tar tends to be available with .tar.gz and .tar.xz well-supported, but not .tar.zstd. unzip is also pretty standard for handling .zip files.
+
+-
+
Modern Windows (~Windows 10) has a copy of bsd tar, but it only supports .tar.gz out of the box (and zip I think, but we use the similarly-new Expand-Archive command for that). The windows file explorer also seemingly has no idea how to open a .tar.gz, unlike a .zip which just pops open with a double click, so worse UX for anyone manually falling back to the raw archives. Both of these are relatively new commands that older Windows systems might lack (introduced in ~2016/2017).
+
+-
+
The npm binary-install and tar packages only support .tar.gz (because nodejs provides a builtin gzip decoder and they just rely on that). There are seemingly packages for other formats but we have yet to cobble together a comprehensive implementation that combines them all.
+
+-
+
The Rust ecosystem similarly requires individual packages for all these formats, but they all have pretty simple/uniform APIs so we were able to cobble together basic support without too much effort.
+
+
+
+cargo-dist projects can also theoretically be installed with the following, through no active effort of our own:
+
+In the future we might support displaying these kinds of install methods.
+Note that cargo-install is just building from the uploaded source with the --release profile, and so if you're relying on cargo-dist or unpublished files for some key behaviours, this may cause problems. It also disrespects your lockfile unless you pass --locked. You can more closely approximate cargo-dist's build with:
+cargo install --profile=dist --locked
+
+Although that's still missing things like Windows crt-static workarounds.
+
+
+
+This manual can be regenerated with cargo dist help-markdown
+
+Shippable packaging for Rust.
+See 'init', 'build' and 'plan' for the 3 most important subcommands.
+
+cargo dist [OPTIONS]
+
+cargo dist
+
+
+- build: Build artifacts
+- init: Setup or update cargo-dist
+- generate: Generate one or more pieces of configuration
+- manifest: Generate the final build manifest without running any builds
+- plan: Get a plan of what to build (and check project status)
+- help: Print this message or the help of the given subcommand(s)
+
+
+
+
+How verbose logging should be (log level)
+[default: warn]
+[possible values: off, error, warn, info, debug, trace]
+
+The format of the output
+[default: human]
+[possible values: human, json]
+
+Strip local paths from output (e.g. in the dist manifest json)
+This is useful for generating a clean "full" manifest as follows:
+cargo dist manifest --artifacts=all --output-format=json --no-local-paths
+
+Target triples we want to build
+If left unspecified we will use the values in workspace.metadata.dist, except for cargo dist init which will select some "good defaults" for you.
+
+Installers we want to build
+If left unspecified we will use the values in workspace.metadata.dist. cargo dist init will persist the values you pass to that location.
+Possible values:
+
+- shell: Generates a shell script that fetches/installs the right build
+- powershell: Generates a powershell script that fetches/installs the right build
+- npm: Generates an npm project that fetches the right build to your node_modules
+- homebrew: Generates a Homebrew formula
+- msi: Generates an msi for each windows platform
+
+
+CI we want to support
+If left unspecified we will use the value in workspace.metadata.dist. cargo dist init will persist the values you pass to that location.
+Possible values:
+
+- github: Generate github CI that uploads to github releases
+
+
+The (git) tag to use for the Announcement that each invocation of cargo-dist is performing.
+This tag serves two purposes: defining which apps we are Announcing new Releases for (and therefore building binaries and installers for); and picking an id to use for certain URLs. For instance the git tag associated with a Github Release is part of the URL to fetch artifacts from that release, which needs to be known by some installers!
+Unified Announcement: VERSION selects all packages with the given version (v1.0.0, 0.1.0-prerelease.1, releases/1.2.3, ...)
+Singular Announcement: PACKAGE-VERSION or PACKAGE/VERSION selects only the given package (my-app-v1.0.0, my-app/1.0.0, release/my-app/v1.2.3-alpha, ...)
+If you use the singular version then we will only Announce/Release that package's apps (and return an error if that is not in fact the package's current version). This is appropriate for workspaces that have more than one app.
+If you use the unified version then we will assume you're Announcing/Releasing all packages in the workspace that have that version. This is appropriate for workspaces that only have one app, or for monorepos that version all their apps in lockstep.
+If you do not specify this tag we will attempt to infer it by trying to Announce/Release every app in the workspace, succeeding only if they all have the same version. The tag selected will be "v{VERSION}".
+In the future we may try to make this look at the current git tags or something?
+
+Allow generated files like CI scripts to be out of date
+
+
+Build artifacts
+
+cargo dist build [OPTIONS]
+
+
+
+Which subset of the Artifacts to build
+Artifacts can be broken up into two major classes: "local" ones, which are made for each target system (executable-zips, symbols, msi installers...); and "global" ones, which are made once per app (curl-sh installers, npm package, metadata...).
+Having this distinction lets us run cargo-dist independently on multiple machines without collisions between the outputs.
+If let unspecified, we will pick a fuzzier "host" mode that builds "as much as possible" for the local system. This mode is appropriate for local testing/debugging/demoing. If no --target flags are passed on the CLI then "host" mode will try to intelligently guess which targets to build for, which may include building targets that aren't defined in your metadata.dist config (since that config may exclude the current machine!).
+The specifics of "host" mode are intentionally unspecified to enable us to provider better out-of-the-box UX for local usage. In CI environments you should always specify "global" or "local" to get consistent behaviour!
+[default: host]
+Possible values:
+
+- local: Build target-specific artifacts like executable-zips and msi installers
+- global: Build unique artifacts like curl-sh installers and npm packages
+- host: Fuzzily build "as much as possible" for the host system
+- all: Build all the artifacts; useful for
cargo dist manifest
+
+
+Print help (see a summary with '-h')
+
+This subcommand accepts all the global options
+
+
+Setup or update cargo-dist
+This will interactively guide you through the process of selecting configuration options and will also automatically run 'cargo dist generate' afterwards as necessary. It will also handle updating your project to a new version of cargo-dist if you're running one.
+
+cargo dist init [OPTIONS]
+
+
+
+Automatically accept all recommended/default values
+This is equivalent to just mashing ENTER over and over during the interactive prompts.
+
+Don't automatically invoke 'cargo dist generate' at the end
+
+A path to a json file containing values to set in workspace.metadata.dist and package.metadata.dist, for building tools that edit these configs.
+This is the same toml => json format that cargo metadata produces when reporting workspace.metadata.dist. There is some additional hierarchy for specifying which values go to which packages, but this is currently intentionally undocumented to give us some flexibility to change it.
+
+Print help (see a summary with '-h')
+
+This subcommand accepts all the global options
+
+
+Generate one or more pieces of configuration
+
+cargo dist generate [OPTIONS] [MODE]...
+
+
+[MODE]...
+Which type of configuration to generate
+Possible values:
+
+- ci: Generate CI scripts for orchestrating cargo-dist
+- msi: Generate .wxs tempaltes for msi installers
+
+
+
+Check if the generated output differs from on-disk config without writing it
+
+Print help (see a summary with '-h')
+
+This subcommand accepts all the global options
+
+
+Generate the final build manifest without running any builds.
+This command is designed to match the exact behaviour of 'cargo dist build' when passed the same flags, which is nice for consistency but annoying for anyone who doesn't understand cargo-dist's design really well.
+Notably it will default to only talking about artifacts for the host system, and will produce paths to the build dir that may not exist (since the build wasn't run).
+'cargo dist plan' is an alias for this command that picks nicer defaults by forcing a couple flags to have specific values. You probably want that.
+
+cargo dist manifest [OPTIONS]
+
+
+
+Which subset of the Artifacts to build
+Artifacts can be broken up into two major classes: "local" ones, which are made for each target system (executable-zips, symbols, msi installers...); and "global" ones, which are made once per app (curl-sh installers, npm package, metadata...).
+Having this distinction lets us run cargo-dist independently on multiple machines without collisions between the outputs.
+If let unspecified, we will pick a fuzzier "host" mode that builds "as much as possible" for the local system. This mode is appropriate for local testing/debugging/demoing. If no --target flags are passed on the CLI then "host" mode will try to intelligently guess which targets to build for, which may include building targets that aren't defined in your metadata.dist config (since that config may exclude the current machine!).
+The specifics of "host" mode are intentionally unspecified to enable us to provider better out-of-the-box UX for local usage. In CI environments you should always specify "global" or "local" to get consistent behaviour!
+[default: host]
+Possible values:
+
+- local: Build target-specific artifacts like executable-zips and msi installers
+- global: Build unique artifacts like curl-sh installers and npm packages
+- host: Fuzzily build "as much as possible" for the host system
+- all: Build all the artifacts; useful for
cargo dist manifest
+
+
+Print help (see a summary with '-h')
+
+This subcommand accepts all the global options
+
+
+Get a plan of what to build (and check project status)
+If you want to know what running your cargo-dist CI will produce, this is the command for you! This is the exact command that CI will run to make its build plan and generate dist-manifest.json (although it adds --output-format=json so that it's machine-readable).
+This is an alias for the lower-level 'manifest' command with the appropriate flags forced for asking for "everything"
+cargo dist manifest --artifacts=all --no-local-paths
+
+cargo dist plan [OPTIONS]
+
+
+
+Print help (see a summary with '-h')
+
+This subcommand accepts all the global options
+
+
+Print this message or the help of the given subcommand(s)
+
+cargo dist help [COMMAND]
+
+
+
+- build: Build artifacts
+- init: Setup or update cargo-dist
+- generate: Generate one or more pieces of configuration
+- manifest: Generate the final build manifest without running any builds
+- plan: Get a plan of what to build (and check project status)
+- help: Print this message or the help of the given subcommand(s)
+
+stderr:
+
+Many cargo-dist commands when run with --output-format=json will output to stdout a format we call "dist-manifest.json". This contains:
+
+- Top-level facts about the Announcement (tag, announcement title, etc)
+- Info about the Apps being Released as part of the Announcement ("releases")
+- Info about the Artifacts included in the Announcement ("announcements")
+
+As a matter of forward-compat and back-compat, basically every field in the format should be treated as optional (which the schema reflects).
+The latest schema can be found at:
+https://github.com/axodotdev/cargo-dist/releases/latest/download/dist-manifest-schema.json
+
+ 
