### Install via npm

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/installers/npm.md

Example command for users to install a package published via cargo-dist.

```sh
npm install @axodotdev/cargodisttest@0.2.0
```

--------------------------------

### Install cargo-dist via PowerShell

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/installers/powershell.md

Use this command to download and execute the cargo-dist installer script. It fetches the latest installer and runs it directly.

```sh
powershell -c "irm https://github.com/axodotdev/cargo-dist/releases/download/v0.0.5/cargo-dist-v0.0.5-installer.ps1 | iex"
```

--------------------------------

### Install via cargo-binstall

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/install.md

Use cargo-binstall to fetch the pre-built binary.

```sh
cargo binstall cargo-dist
```

--------------------------------

### Install via Pacman

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/install.md

Use Pacman to install the package on Arch Linux.

```sh
pacman -S cargo-dist
```

--------------------------------

### Enable Homebrew Installer in Cargo.toml

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/installers/homebrew.md

Add the homebrew installer and tap configuration to the workspace metadata.

```toml
[workspace.metadata.dist]
# "..." indicates other installers you may have selected
installers = ["...", "homebrew", "..."]
tap = "axodotdev/homebrew-tap"
publish-jobs = ["homebrew"]
```

--------------------------------

### Install via curl | sh

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/installers/shell.md

This command downloads and executes the installer script from a GitHub release. Ensure you trust the source before running.

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

--------------------------------

### Install via Nix

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/install.md

Use Nix to install the package on NixOS or macOS.

```sh
nix-env -i cargo-dist
```

--------------------------------

### Install via Homebrew

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/install.md

Use Homebrew to install the package on macOS or Linux.

```sh
brew install axodotdev/tap/cargo-dist
```

--------------------------------

### Configure install-libraries

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Specifies which compiled library types to include in the installer. Requires the package-libraries setting to be enabled.

```toml
[dist]
install-libraries = ["cdylib", "cstaticlib"]
```

--------------------------------

### Example axolotlsay-update session

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/installers/updater.md

A demonstration of the output users see when running the standalone updater command.

```text
$ axolotlsay-update
Checking for updates...
downloading axolotlsay 0.2.114 aarch64-apple-darwin
installing to /Users/mistydemeo/.cargo/bin
  axolotlsay
  axolotlsay-update
everything's installed!
New release installed!
```

--------------------------------

### Define Custom Build Setup Steps

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/ci/customizing.md

Create a YAML file containing the workflow steps to be injected into the build process.

```yaml
- name: Install Lua
  uses: xpol/setup-lua@v1
  with:
    lua-version: "5.3"
- name: Check lua installation
  run: lua -e "print('hello world!')"
```

--------------------------------

### Configure install-path

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Defines the installation directory strategy for shell and powershell installers, supporting single paths or a cascade of fallback options.

```toml
[dist]
install-path = "~/.my-app/"
```

```toml
[dist]
install-path = ["$MY_APP_HOME/bin", "~/.my-app/bin"]
```

```toml
install-path = ["$MY_APP_HOME/bin", "~/.my-app/bin"]
```

--------------------------------

### Install via PowerShell on Windows

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/install.md

Use this command to install on Windows systems via PowerShell.

```powershell
powershell -c "irm https://github.com/axodotdev/cargo-dist/releases/latest/download/cargo-dist-installer.ps1 | iex"
```

--------------------------------

### Define Installers

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Specifies the list of installers to generate for the packages.

```toml
[dist]
installers = [
  "shell",
  "powershell",
  "npm",
  "homebrew",
  "msi"
]
```

--------------------------------

### Build Project for Current Platform

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/quickstart/everyone-else.md

Executes the build process for the host operating system and generates installers.

```sh
dist build
```

--------------------------------

### Example GitHub Latest Release Hotlink

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/artifact-url.md

An example demonstrating the GitHub 'latest' release hotlinking schema, showing how to link to a file without specifying a version number.

```text
https://github.com/axodotdev/cargo-dist/releases/latest/download/dist-manifest-schema.json
```

--------------------------------

### Configure hosting providers

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Specifies the order of hosting providers for installers. The first entry is prioritized.

```toml
[dist]
hosting = ["simple", "github"]
```

--------------------------------

### Configure Custom Build Setup

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/ci/customizing.md

Inject custom workflow steps into the build-local-artifacts job by referencing a YAML file in Cargo.toml.

```toml
[dist]
# ...
github-build-setup = "../build-setup.yml"
```

--------------------------------

### Install cargo-insta for Snapshot Testing

Source: https://github.com/axodotdev/cargo-dist/blob/main/README.md

Installs the cargo-insta tool, which is used for snapshot testing in cargo-dist. This is necessary for updating or reviewing snapshot test outputs.

```sh
cargo install cargo-insta
```

--------------------------------

### Enable Install Updater

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Set `install-updater` to `true` to include a standalone updater program with shell and powershell installers. This program helps users automatically check for and install newer versions.

```toml
[dist]
install-updater = true

```

--------------------------------

### Install via shell script on macOS and Linux

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/install.md

Use this script for macOS and Linux systems, excluding NixOS.

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/latest/download/cargo-dist-installer.sh | sh
```

--------------------------------

### Configure npm installer in Cargo.toml

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/installers/npm.md

Required workspace metadata configuration to enable the npm installer and specify the scope.

```toml
[workspace.metadata.dist]
# "..." indicates other installers you may have selected
installers = ["...", "npm", "..."]
# if you did not provide a scope, this won't be present
npm-scope = "@axodotdev"
publish-jobs = ["npm"]
```

--------------------------------

### Install with locked dependencies

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/installers/other.md

Use this command to ensure the build respects the lockfile, approximating the build process more closely.

```sh
cargo install --locked
```

--------------------------------

### Source Host Parsing Example

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/artifact-url.md

Demonstrates how cargo-dist parses the `[package].repository` URL from Cargo.toml to extract owner, project, and a normalized repository URL.

```text
* Cargo.toml "repository": https://github.com/axodotdev/axolotlsay.git
* owner: axodotdev
* project: axolotlsay
* repo_url: https://github.com/axodotdev/axolotlsay/
```

--------------------------------

### Specify GitHub Build Setup YAML Path

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Provide a path to a YAML file containing custom steps to be executed before `dist build` in your GitHub CI.

```toml
[dist]
github-build-setup = "path/to/build-setup.yml"
```

--------------------------------

### Build from source via Cargo

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/install.md

Use this command to build and install from source using the Rust toolchain.

```sh
cargo install cargo-dist --locked
```

--------------------------------

### Configure install-success-msg

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Sets the custom success message displayed by shell and powershell installers upon completion.

```toml
[dist]
install-success-msg = "axolotlsay is ready to rumble! >o_o<"
```

--------------------------------

### Configure Binary Aliases

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Maps binary names to aliases created by installers. Aliases are installer-specific and not included in archives.

```toml
[dist.bin-aliases]
mybin = ["somealias"]
myotherbin = ["someotheralias", "anotheralias"]
```

--------------------------------

### Example GitHub Artifact URL Derivation

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/artifact-url.md

Illustrates how specific Cargo.toml and git tag information translate into a concrete artifact URL and a full download URL for a binary.

```text
* Cargo.toml "repository": `https://github.com/axodotdev/axolotlsay/`
* git tag: `v0.1.0`
* artifact url: `https://github.com/axodotdev/axolotlsay/releases/download/v0.1.0/`
* download: `https://github.com/axodotdev/axolotlsay/releases/download/v0.1.0/axolotlsay-x86_64-unknown-linux-gnu.tar.gz`
```

--------------------------------

### Override Binaries per Platform

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Allows overriding the list of binaries to install based on the target platform.

```toml
[dist.binaries]
x86_64-pc-windows-msvc = ["a", "b"]
```

--------------------------------

### Configure System Dependencies

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Specify dependencies to be installed from system package managers like Homebrew, Apt, or Chocolatey before the build process.

```toml
[dist.dependencies.homebrew]
cmake = '*'
libcue = { stage = ["build", "run"] }

[dist.dependencies.apt]
cmake = '*'
libcue-dev = { version = "2.2.1-2" }

[dist.dependencies.chocolatey]
lftp = '*'
cmake = { version = '3.27.6', targets = ["aarch64-pc-windows-msvc"] }
```

--------------------------------

### Specify custom files to include in archives

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Use the `include` setting to list additional files or directories to copy into the root of all archives and installers. Paths are relative to the config file, and globs are not supported.

```toml
[dist]
include = [
   "my-cool-file.txt",
   "../other-cool-file.txt",
   "./some/dir/"
]

```

--------------------------------

### Configure Homebrew Tap

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Specify the GitHub repository name for `tap` where dist should publish the Homebrew installer. The repository must exist, and the publishing token needs write access.

```toml
[dist]
tap = "axodotdev/homebrew-tap"

```

--------------------------------

### Set Package Documentation URL

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Specify a URL to the documentation of your package. This can be inherited from native package formats and may be used in installer metadata.

```toml
[package]
documentation = "https://docs.rs/axolotlsay"
```

--------------------------------

### Set Package Homepage URL

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Provide a URL to the homepage of your package. This can be inherited from native package formats and may be used in installer metadata.

```toml
[package]
homepage = "https://axodotdev.github.io/axolotlsay"
```

--------------------------------

### Install Bun as Dev Dependency

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/quickstart/javascript.md

Add Bun as a development dependency to your npm project to ensure the correct version is available for building executables.

```sh
npm i bun --save-dev
```

--------------------------------

### Configure `global-artifacts-jobs` for CI

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Set custom jobs to run during the 'build global artifacts' phase, responsible for generating installers. This configuration belongs in your `dist-workspace.toml` or `dist.toml`.

```toml
[dist]
global-artifacts-jobs = ["./my-job"]
```

--------------------------------

### Release Notes Changelog Format

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/workspaces/simple-guide.md

This is an example of the expected format for a CHANGELOG file that `dist` can parse to generate GitHub Release notes. It looks for a heading matching the release version.

```text
## 0.1.0

```

--------------------------------

### Initialize dist Configuration

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/quickstart/everyone-else.md

Run this command to generate the initial configuration and CI workflows. The --yes flag accepts all defaults.

```sh
# setup dist in your project (--yes to accept defaults)
dist init --yes
git add .
git commit -am 'chore: wow shiny new dist CI!'
```

--------------------------------

### Configure package C static libraries

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

List the names of C-style static libraries to build and distribute.

```toml
[package]
cstaticlibs = ["mystaticlib", "some-helper"]
```

--------------------------------

### Configure package binaries

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

List the names of binaries to build and distribute, excluding extensions.

```toml
[package]
binaries = ["my-app", "my-other-app"]
```

--------------------------------

### PowerShell Debugging Options

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/installers/usage.md

Utilize the `-Verbose` flag in PowerShell to increase the verbosity of installer output.

```powershell
-Verbose
```

--------------------------------

### Configure package C dynamic libraries

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

List the names of C-style dynamic libraries to build and distribute.

```toml
[package]
cdylibs = ["mydylib", "some-other-helper"]
```

--------------------------------

### Initialize cargo-dist Project

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/quickstart/rust.md

Run this command to set up cargo-dist in your project, accepting all default configurations. It's recommended to rerun this command whenever you need to change settings or update dist.

```sh
dist init --yes
git add .
git commit -am 'chore: wow shiny new dist CI!'
```

--------------------------------

### Shell Debugging Options

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/installers/usage.md

Use `$INSTALLER_PRINT_VERBOSE` or `-v, --verbose` for verbose output, and `$INSTALLER_PRINT_QUIET` or `-q, --quiet` for quiet output in Shell environments.

```shell
$INSTALLER_PRINT_VERBOSE, -v, --verbose
```

```shell
$INSTALLER_PRINT_QUIET, -q, --quiet
```

--------------------------------

### Update package.json with Bun Dev Dependency

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/quickstart/javascript.md

Ensure your package.json includes Bun in the 'devDependencies' section after installation.

```json
  "devDependencies": {
    "bun": "^1.x.x"
  }
```

--------------------------------

### Configure package license files

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Provide a list of relative paths to license files.

```toml
[package]
license-files = ["../LICENSE-MIT", "../LICENSE-APACHE"]
```

--------------------------------

### Generated Build Job Modifications

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/ci/customizing.md

Example of how custom steps are integrated into the build-local-artifacts job after the checkout step.

```yaml
# ...
jobs:
# ...
  build-local-artifacts:
    # ...
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
      - name: Install Lua
        uses: xpol/setup-lua@v1
          with:
            lua-version: "5.3"
      - name: Check lua installation
        run: lua -e "print('hello world!')"
# ...
```

--------------------------------

### Minimal package.json Configuration

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/quickstart/javascript.md

A sample package.json demonstrating the required fields ('name', 'version', 'repository', 'bin', 'scripts', 'devDependencies') for a JavaScript project distributed with cargo-dist.

```json
{
  "name": "axolotlsay-bun",
  "version": "0.4.0",
  "repository": "github:axodotdev/axolotlsay-hybrid",
  "bin": {
    "axolotlsay-bun": "index.js"
  },
  "scripts": {
    "predist": "npm install",
    "dist": "node dist.js"
  },
  "devDependencies": {
    "bun": "^1.x.x"
  }
}
```

--------------------------------

### Plan CI Builds

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/quickstart/everyone-else.md

Run `dist plan` to see what artifacts will be built for all platforms without actually building them. This helps catch potential CI errors early.

```sh
dist plan
```

--------------------------------

### Configure npm Scope

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Use `npm-scope` to specify the scope under which npm installers should be published. The leading `@` is mandatory. If not specified, the package will be global.

```toml
[dist]
npm-scope = "@axodotdev"

```

--------------------------------

### Preview Release Steps

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/workspaces/cargo-release-guide.md

Before a full release, use this command to preview the actions cargo-release would take without executing them. This helps in identifying potential issues.

```sh
# 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
```

--------------------------------

### Generate Machine-Readable Output with dist plan --output-format=json

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/workspaces/simple-guide.md

Obtain a machine-readable JSON output of the release plan by using the `--output-format=json` flag with `dist plan`. This is useful for recreating the first step of the CI generation locally.

```shell
dist plan --output-format=json
```

--------------------------------

### Configure `post-announce-jobs` for CI

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Specify custom jobs to run after the 'announce' phase, ensuring they execute after all other release steps. Configure this in your `dist-workspace.toml` or `dist.toml`.

```toml
[dist]
post-announce-jobs = ["./my-job"]
```

--------------------------------

### Specify Runner for Cross-Compilation Host

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/ci/customizing.md

When cross-compiling, you can specify the host runner if it differs from the target. This example shows setting `ubuntu-22.04` as the host for `aarch64-unknown-linux-gnu`.

```toml
[dist.github-custom-runners]
aarch64-unknown-linux-gnu = "ubuntu-22.04"
```

--------------------------------

### Configure force-latest

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Forces dist to treat a version as the latest release, bypassing standard semver prerelease logic.

```toml
[dist]
force-latest = true
```

--------------------------------

### Configure GitHub Release Timing

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Controls the stage at which the GitHub Release is created. Changing this from the default 'auto' may introduce race conditions for installers.

```toml
[dist]
github-release = "announce"
```

--------------------------------

### Disable auto-includes in archives

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Set `auto-includes` to `false` to prevent dist from automatically including README, (UN)LICENSE, and CHANGELOG/RELEASES files in archives and installers.

```toml
[dist]
auto-includes = false

```

--------------------------------

### Initialize cargo-dist

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/workspaces/simple-guide.md

Run this command to initialize cargo-dist in your project. It provides interactive prompts to configure your project and can be automated with the --yes flag.

```sh
dist init
```

--------------------------------

### Set Package Description

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Provide a brief description of your package. This can be inherited from native package formats like Cargo.toml or package.json and may be used in installer metadata.

```toml
[package]
version = "A cool application that solves all your problems!"
```

--------------------------------

### Configure SSL.com signing in Cargo.toml

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/supplychain-security/signing/windows.md

Add the signing configuration to the workspace metadata section of your configuration file.

```toml
[workspace.metadata.dist]
ssldotcom-windows-sign = "prod"  # or "test" if you are using a sandbox account
```

--------------------------------

### Add 'dist' npm Script

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/quickstart/javascript.md

Include a 'dist' script in your package.json to automate the build process using a Node.js script. The 'predist' script ensures dependencies are installed.

```json
  "scripts": {
    "predist": "npm install",
    "dist": "node dist.js"
  },
```

--------------------------------

### Commit and Push Changes with Git

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/workspaces/simple-guide.md

After running `dist init`, commit the generated files and push them to your repository.

```shell
git add .
git commit -am 'wow cool new dist CI!'
git push
```

--------------------------------

### Enable Prerelease Publishing

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Set `publish-prereleases` to `true` to allow dist to publish prerelease versions to package managers like Homebrew and npm. The default is `false` to avoid polluting releases with unstable versions.

```toml
[dist]
publish-prereleases = true

```

--------------------------------

### Configure Simple Download URL

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Defines a template URL for downloading releases from a static file server. The {tag} variable is automatically replaced with the current git tag.

```toml
[dist]
simple-download-url = "https://static.myapp.com/{tag}"
```

--------------------------------

### Define Package Metadata in dist.toml

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/quickstart/everyone-else.md

Create this file in the root directory to define project metadata and build instructions for dist.

```toml
[package]
# The name of your package; dist will use this in your installers and announcements
name = "quickstart-example"
# (Optional) Descriptive text about your package; some installers will present this to users
description = "This is a description of your package"
# The current version of your package - you'll update this with every release
version = "1.0.0"
# (Optional) Your package's license
license = "GPL-3.0-only"
# The URL to package's git repository
repository = "https://github.com/example/example"
# A list of all binaries your package will build and install
binaries = ["quickstart-example"]
# A command dist should run that will build your project
build-command = ["make"]
```

--------------------------------

### Specify npm Package Name

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Set `npm-package` to define a custom name for the npm installer package, distinct from the project's package name. This does not affect the publishing scope.

```toml
[dist]
npm-package = "mycoolapp"

```

--------------------------------

### List Artifact Manifest

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Displays the exact artifact names and expected contents for custom CI integration.

```bash
dist manifest --artifacts=local --no-local-paths
```

--------------------------------

### cargo-dist Configuration in Cargo.toml

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/workspaces/simple-guide.md

This TOML snippet shows the default configuration added by 'dist init'. It specifies the preferred dist version, CI backends, installers, and target platforms for building.

```toml
# The profile that 'dist' will build with
[profile.dist]
inherits = "release"
lto = "thin"

# Config for 'dist'
[workspace.metadata.dist]
# The preferred 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"]
```

--------------------------------

### GitHub Latest Release Hotlinking Schema

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/artifact-url.md

This is the specific, non-obvious schema GitHub uses for hotlinking files from the latest release. It is useful for documentation but not directly used by cargo-dist for installer generation.

```text
{repo_url}/releases/latest/download/
```

--------------------------------

### Configure Container for Windows Cross-Compilation

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/ci/customizing.md

Use a specific container image, such as `messense/cargo-xwin`, for cross-compiling Windows binaries. This ensures necessary tools like `cargo-xwin` are pre-installed.

```toml
# in `dist-workspace.toml`

[dist]
targets = ["x86_64-pc-windows-msvc", "aarch64-pc-windows-msvc"]

[dist.github-custom-runners.x86_64-pc-windows-msvc]
container = "messense/cargo-xwin"

[dist.github-custom-runners.aarch64-pc-windows-msvc]
container = "messense/cargo-xwin"
```

--------------------------------

### Configure Package Metadata

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/installers/homebrew.md

Set the description and homepage fields in Cargo.toml to improve the generated formula.

```toml
[package]
description = "a CLI for learning to distribute CLIs in rust"
homepage = "https://github.com/axodotdev/axolotlsay"
```

--------------------------------

### Non-Virtual Workspace Independent Versions Config

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/workspaces/cargo-release-guide.md

Configure this in the root Cargo.toml of a non-virtual workspace when each package needs an independent release tag. This setup is for when the root package is the main application and other packages are libraries.

```toml
[package.metadata.release]
tag-name = "{{crate_name}}-v{{version}}"
```

--------------------------------

### Cargo.toml Configuration for cargo-dist

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/concepts.md

This TOML snippet shows the configuration for cargo-dist within a Cargo.toml file. It specifies the preferred cargo-dist version, CI backends, installers to generate, and target platforms for building applications.

```toml
# Config for 'dist'
[workspace.metadata.dist]
# The preferred 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"]

```

--------------------------------

### Configure package.build-command

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/config.md

Define a custom build command in the package configuration file to execute during the build process.

```toml
[package]
build-command = ["make", "dist"]
```

--------------------------------

### Virtual Workspace Unified Versions Config

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/workspaces/cargo-release-guide.md

Configure this in your root Cargo.toml for a virtual workspace to enable shared versioning and a unified release tag. This setup ensures all packages in the workspace are versioned and released together.

```toml
[workspace.metadata.release]
shared-version = true
tag-name = "v{{version}}"
```

--------------------------------

### Manifest command with all artifacts

Source: https://github.com/axodotdev/cargo-dist/blob/main/book/src/reference/concepts.md

Use this to list all artifacts that would be produced for a given tag. It's useful for understanding the output of a CI push.

```sh
dist manifest --tag=v0.5.0 --artifacts=all --no-local-paths
```