cargo-dist CLI Manual

Usage
Commands
Options
GLOBAL OPTIONS
cargo dist build
cargo dist init
cargo dist generate
cargo dist linkage
cargo dist manifest
cargo dist plan
cargo dist host
cargo dist selfupdate
cargo dist help
- Usage
- Commands

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.

Commands

build: Build artifacts
init: Setup or update cargo-dist
generate: Generate one or more pieces of configuration
linkage: Report on the dynamic libraries used by the built artifacts
manifest: Generate the final build manifest without running any builds
plan: Get a plan of what to build (and check project status)
host: Host artifacts
selfupdate: Performs a self-update, if a new version is available, and then 'init'
help: Print this message or the help of the given subcommand(s)

GLOBAL OPTIONS

`-v, --verbose <VERBOSE>`

How verbose logging should be (log level)

[default: warn]
[possible values: off, error, warn, info, debug, trace]

`-o, --output-format <OUTPUT_FORMAT>`

The format of the output

[default: human]
[possible values: human, json]

`--no-local-paths`

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

`-t, --target <TARGET>`

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.

`-i, --installer <INSTALLER>`

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

`-c, --ci <CI>`

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

`--tag <TAG>`

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-dirty`

Allow generated files like CI scripts to be out of date

cargo dist build

Build artifacts

Usage

cargo dist build [OPTIONS]

Options

`-a, --artifacts <ARTIFACTS>`

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 (archives, 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 archives 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
lies: Fake all the artifacts; useful for testing/mocking/staging

`-p, --print <PRINT>`

What extra information to print, if anything. Currently supported:

linkage: prints information on dynamic libraries used by build artifacts

`-h, --help`

Print help (see a summary with '-h')

GLOBAL OPTIONS

This subcommand accepts all the global options

cargo dist init

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.

Usage

cargo dist init [OPTIONS]

Options

`-y, --yes`

Automatically accept all recommended/default values

This is equivalent to just mashing ENTER over and over during the interactive prompts.

`--skip-generate`

Skip running 'cargo dist generate' at the end

`--with-json-config <WITH_JSON_CONFIG>`

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.

`--hosting <HOSTING>`

releases hosting backends we want to support

If left unspecified we will use the value in workspace.metadata.dist. (If no such value exists we will use the one "native" to your CI provider) cargo dist init will persist the values you pass to that location.

Possible values:

github: Host on Github Releases
axodotdev: Host on Axo Releases ("Abyss")

`-h, --help`

Print help (see a summary with '-h')

GLOBAL OPTIONS

This subcommand accepts all the global options

cargo dist generate

Generate one or more pieces of configuration

Usage

cargo dist generate [OPTIONS]

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`

Check if the generated output differs from on-disk config without writing it

`-h, --help`

Print help (see a summary with '-h')

GLOBAL OPTIONS

This subcommand accepts all the global options

cargo dist linkage

Report on the dynamic libraries used by the built artifacts

Usage

cargo dist linkage [OPTIONS]

Options

`--print-output`

Print human-readable output

`--print-json`

Print output as JSON

`--from-json <FROM_JSON>`

Read linkage data from JSON rather than parsing from binaries

`-h, --help`

Print help (see a summary with '-h')

GLOBAL OPTIONS

This subcommand accepts all the global options

cargo dist manifest

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.

Usage

cargo dist manifest [OPTIONS]

Options

`-a, --artifacts <ARTIFACTS>`

Which subset of the Artifacts to build

Having this distinction lets us run cargo-dist independently on multiple machines without collisions between the outputs.

[default: host]

Possible values:

local: Build target-specific artifacts like archives 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
lies: Fake all the artifacts; useful for testing/mocking/staging

`-p, --print <PRINT>`

What extra information to print, if anything. Currently supported:

linkage: prints information on dynamic libraries used by build artifacts

`-h, --help`

Print help (see a summary with '-h')

GLOBAL OPTIONS

This subcommand accepts all the global options

cargo dist plan

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

Usage

cargo dist plan [OPTIONS]

cargo dist host [OPTIONS]

Options

`--steps <STEPS>`

The hosting steps to perform

Possible values:

check: Check that hosting is properly setup without doing other effects
create: Create a location to host artifacts
upload: Upload artifacts
release: Release artifacts
announce: Announce artifacts

cargo dist selfupdate [OPTIONS]

github: Host on Github Releases
axodotdev: Host on Axo Releases ("Abyss")

cargo dist help [COMMAND]

Commands

build: Build artifacts
init: Setup or update cargo-dist
generate: Generate one or more pieces of configuration
linkage: Report on the dynamic libraries used by the built artifacts
manifest: Generate the final build manifest without running any builds
plan: Get a plan of what to build (and check project status)
host: Host artifacts
selfupdate: Performs a self-update, if a new version is available, and then 'init'
help: Print this message or the help of the given subcommand(s)

stderr: