dist CLI Manual

dist CLI manual

dist CLI manual

This manual can be regenerated with dist help-markdown

Professional packaging and distribution for ambitious developers.

See 'init', 'build' and 'plan' for the 3 most important subcommands.

Commands

build: Build artifacts
init: Setup or update dist
migrate: Migrate to the latest configuration variant
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:

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 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. 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. 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 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?

`--force-tag`

Force package versions to match the tag

`--allow-dirty`

Allow generated files like CI scripts to be out of date

dist build

Build artifacts

Usage

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

dist init

Setup or update dist

This will interactively guide you through the process of selecting configuration options and will also automatically run 'dist generate' afterwards as necessary. It will also handle updating your project to a new version of dist if you're running one.

Usage

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 '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) 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

dist migrate

Migrate to the latest configuration variant

Usage

dist migrate [OPTIONS]

Options

`-h, --help`

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

GLOBAL OPTIONS

This subcommand accepts all the global options

dist generate

Generate one or more pieces of configuration

Usage

dist generate [OPTIONS]

Options

`--mode <MODE>`

Which type of configuration to generate

Possible values:

ci: Generate CI scripts for orchestrating dist
msi: Generate .wxs templates 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

dist linkage

Report on the dynamic libraries used by the built artifacts

Usage

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

dist manifest

Generate the final build manifest without running any builds.

This command is designed to match the exact behaviour of 'dist build' when passed the same flags, which is nice for consistency but annoying for anyone who doesn't understand 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).

'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

dist manifest [OPTIONS]

Options

`-a, --artifacts <ARTIFACTS>`

Which subset of the Artifacts to build

Having this distinction lets us run 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 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

dist plan

Get a plan of what to build (and check project status)

If you want to know what running your 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"

dist manifest --artifacts=all --no-local-paths

Usage

dist plan [OPTIONS]

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

dist selfupdate [OPTIONS]

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

dist help [COMMAND]

Commands

build: Build artifacts
init: Setup or update dist
migrate: Migrate to the latest configuration variant
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: