Distributing CLI Tools

22 min read

Quick Overview

You wrote a great command-line tool — now how do people get it? In the Node world the answer is almost always “publish to npm and tell users to npm install -g”, which means every machine needs Node and a network round-trip to a registry. Rust compiles to a single self-contained native binary, which opens up faster, simpler distribution paths: cargo install from source, prebuilt downloads, and automated GitHub releases. This page covers the four pieces you actually ship with: cargo install, prebuilt binaries (and how to cross-compile them), the cargo-dist/dist tool that automates a full release pipeline, and the release profiles that decide how small and fast your binary is.

The current stable toolchain is Rust 1.96.0 on the latest stable edition (2024); cargo new selects it automatically. The release-profile and version-embedding examples are pure standard Cargo and need no dependencies; the optional build-metadata example uses the built crate.

TypeScript/JavaScript Example

Distributing a Node CLI means publishing a package and relying on the user’s installed runtime. A typical package.json for a global CLI looks like this:

1
{
2
  "name": "@acme/greet",
3
  "version": "1.2.0",
4
  "type": "module",
5
  "bin": {
6
    "greet": "./dist/cli.js"
7
  },
8
  "files": ["dist"],
9
  "engines": {
10
    "node": ">=18"
11
  },
12
  "scripts": {
13
    "build": "tsc -p tsconfig.json",
14
    "prepublishOnly": "npm run build"
15
  }
16
}

1
#!/usr/bin/env node
2
// dist/cli.js — the shebang tells the OS to run this with node.
3
console.log(`Hello from greet ${process.env.npm_package_version ?? ""}!`);

Users then install it globally and run it:

1
$ npm install -g @acme/greet
2
$ greet
3
Hello from greet !

This works, but notice what travels with the tool. The bin entry is a JavaScript file, not an executable — it relies on the #!/usr/bin/env node shebang and the user already having a compatible Node (the engines field is a hint, not enforcement). The user downloads your code plus a node_modules tree, then your code is interpreted at every launch. There is no single artifact you can hand someone who does not have Node installed.

Note: Tools like pkg, nexe, or Node 21+‘s Single Executable Applications can bundle Node into one binary, but they are bolt-on solutions producing 40-90 MB artifacts. With Rust, a single static-ish binary is the default output, not an afterthought.

Rust Equivalent

A Rust CLI compiles to one native executable. The Cargo manifest declares the binary, and cargo build --release produces it:

1
[package]
2
name = "greet"
3
version = "1.2.0"
4
edition = "2024"
5

6
# A [[bin]] is implied for src/main.rs, but you can name it explicitly.
7
[[bin]]
8
name = "greet"
9
path = "src/main.rs"

1
use std::process::ExitCode;
2

3
fn main() -> ExitCode {
4
    // Cargo bakes these values in at compile time from Cargo.toml.
5
    let name = env!("CARGO_PKG_NAME");
6
    let version = env!("CARGO_PKG_VERSION");
7
    println!("Hello from {name} {version}!");
8
    ExitCode::SUCCESS
9
}

Building and running it:

1
$ cargo build --release
2
   Compiling greet v1.2.0 (/tmp/greet)
3
    Finished `release` profile [optimized] target(s) in 0.34s
4

5
$ ./target/release/greet
6
Hello from greet 1.2.0!

That target/release/greet file is the entire deliverable. There is no runtime to install, no node_modules, and no interpreter — you can copy it to a machine that has never seen Rust and run it. The rest of this page is about (1) the three ways to get that binary to users and (2) tuning how it is built.

Detailed Explanation

Path 1: `cargo install` — the `npm install -g` analogue

cargo install is the closest thing to npm install -g, with one big difference: it compiles from source on the user’s machine and drops the resulting binary into ~/.cargo/bin (which rustup already put on your PATH). The user needs a Rust toolchain, but the artifact they end up with is a native executable, not interpreted source.

1
# From crates.io (like `npm install -g <name>`):
2
$ cargo install ripgrep        # installs the `rg` binary
3

4
# From a specific version (a caret range, newest matching):
5
$ cargo install ripgrep --version "14"
6

7
# Directly from a git repository (no registry needed):
8
$ cargo install --git https://github.com/BurntSushi/ripgrep
9

10
# From a local checkout — the inner-loop command while developing:
11
$ cargo install --path .

Here is a real cargo install --path . run for a small tool (output paths abbreviated):

1
$ cargo install --path .
2
   Compiling clap v4.6.1
3
   Compiling mytool v0.1.0 (/tmp/mytool)
4
    Finished `release` profile [optimized] target(s) in 9.98s
5
  Installing /home/you/.cargo/bin/mytool
6
   Installed package `mytool v0.1.0 (/tmp/mytool)` (executable `mytool`)
7
warning: be sure to add `/home/you/.cargo/bin` to your PATH to be able to run the installed binaries

Key behaviors a Node developer should internalize:

It always builds in release mode. Unlike cargo build (debug by default), cargo install optimizes by default — there is no --release flag to pass.
It installs the binary, not the source. ~/.cargo/bin/mytool is a standalone executable; the source is discarded after the build.
Reinstalling upgrades in place. Running cargo install again with a newer version replaces the old binary. Use cargo install --list to see what is installed, and cargo uninstall mytool to remove it.

1
$ cargo install --list
2
mytool v0.1.0:
3
    mytool
4
ripgrep v14.1.1:
5
    rg

The trade-off versus npm: the user pays a one-time compile cost (seconds to minutes) instead of a download. That is fine for developer-facing tools but a poor experience for everyone else — which is why you also ship prebuilt binaries.

Tip: cargo-binstall (current version 1.19.1) is a popular companion: cargo binstall mytool downloads a prebuilt binary from your GitHub releases when one exists and only falls back to compiling if it does not — combining the discoverability of cargo install with the speed of a download.

Path 2: Prebuilt binaries

The reason ripgrep, fd, bat, and friends feel instant to install is that their maintainers publish prebuilt binaries for each platform. A user (or a Homebrew/Scoop/apt formula) downloads a .tar.gz or .zip, extracts one file, and runs it — no toolchain, no compile.

To produce a binary for a platform other than your own, you cross-compile to a target triple. Add the target with rustup, then pass --target:

1
# See your host triple and what's installed:
2
$ rustc -vV | grep host
3
host: aarch64-apple-darwin
4

5
$ rustup target list --installed
6
aarch64-apple-darwin
7
x86_64-unknown-linux-gnu
8
wasm32-unknown-unknown
9

10
# Add a target and build for it:
11
$ rustup target add x86_64-unknown-linux-musl
12
$ cargo build --release --target x86_64-unknown-linux-musl

The output then lives under target/<triple>/release/. Common triples you will ship:

Target triple	Platform	Notes
`x86_64-unknown-linux-gnu`	Linux (Intel/AMD)	Dynamically links glibc
`x86_64-unknown-linux-musl`	Linux (Intel/AMD)	Fully static; runs on any distro, Alpine included
`aarch64-unknown-linux-gnu`	Linux (ARM64)	Servers, Raspberry Pi
`x86_64-apple-darwin`	macOS (Intel)
`aarch64-apple-darwin`	macOS (Apple Silicon)
`x86_64-pc-windows-msvc`	Windows	Produces `.exe`; needs the MSVC linker

Pure cross-compiling works out of the box for many targets, but anything that links C libraries (or needs a different libc) often needs a cross linker. Two tools smooth this over:

cross (current 0.2.5) — a drop-in cargo replacement that runs the build inside a Docker/Podman container with the right toolchain: cross build --release --target aarch64-unknown-linux-gnu. No host setup beyond a container runtime.
GitHub Actions matrix builds — run the native compiler on each OS runner (ubuntu-latest, macos-latest, windows-latest) so no cross-compilation is needed at all. This is what cargo-dist automates (Path 3).

Tip: For maximum portability on Linux, build the musl target. A x86_64-unknown-linux-musl binary is statically linked, so it runs on Ubuntu, Debian, Alpine, and inside scratch containers without “glibc version too old” surprises — a class of problem Node sidesteps by shipping its own runtime and that Rust sidesteps by static linking.

Path 3: `cargo-dist` — automating the whole release

Building six binaries by hand, tarring them up, computing checksums, writing installer scripts, and attaching everything to a GitHub release is tedious and error-prone. cargo-dist (crate cargo-dist, current 0.32.0; the command was renamed to dist) generates a complete release pipeline from a few lines of config. Think of it as the Rust analogue of a fully wired npm publish plus release-please plus platform installers — but producing native binaries.

Install it and initialize:

1
$ cargo install cargo-dist
2
$ dist init

dist init interviews you (which targets, which installers, CI provider) and writes configuration into your Cargo.toml/dist-workspace.toml plus a .github/workflows/release.yml. The config looks roughly like this:

1
# In Cargo.toml (or dist-workspace.toml for a workspace)
2
[workspace.metadata.dist]
3
# Which cargo-dist version to pin the generated CI to:
4
cargo-dist-version = "0.32.0"
5
# Which CI provider to generate workflows for:
6
ci = ["github"]
7
# Generated user-facing installers:
8
installers = ["shell", "powershell", "homebrew"]
9
# Platforms to build for:
10
targets = [
11
    "x86_64-unknown-linux-gnu",
12
    "aarch64-apple-darwin",
13
    "x86_64-apple-darwin",
14
    "x86_64-pc-windows-msvc",
15
]

From then on, pushing a version tag (git tag v1.2.0 && git push --tags) triggers the generated workflow, which:

Builds release binaries for every target on the matching CI runner.
Bundles them into per-platform archives with checksums.
Creates a GitHub Release and uploads the artifacts.
Publishes the installer scripts, so users can run a one-liner like curl --proto '=https' --tlsv1.2 -LsSf https://github.com/you/mytool/releases/latest/download/mytool-installer.sh | sh.

The end result: your users get the instant-download experience of ripgrep, and you maintain a handful of config lines instead of a fragile shell script.

Note: cargo-dist reads your release profile (below) and builds with it. It defines its own optimized build settings; if you want to customize them, add a [profile.dist] section that inherits = "release".

Release profiles — how Cargo decides what to build

A profile is a named set of compiler settings. Cargo ships two you use constantly:

dev (used by cargo build, cargo run): no optimization, fast compiles, full debug info. The target/debug/ binary.
release (used by cargo build --release, and always by cargo install): optimized, slower to compile. The target/release/ binary.

The single most common distribution mistake is shipping the debug binary. The difference is dramatic in both size and speed, so for anything users run, always build --release.

You tune the release build in Cargo.toml under [profile.release]. Here is a size-focused profile, with each knob explained:

1
[profile.release]
2
opt-level = "z"     # optimize aggressively for size ("s" is a milder variant)
3
lto = true          # link-time optimization: inline/strip across crate boundaries
4
codegen-units = 1   # one codegen unit = better optimization, slower compile
5
strip = true        # remove symbol/debug info from the final binary
6
panic = "abort"     # drop unwinding tables; smaller binary, but no catch_unwind

The effect is real and measurable. For the same trivial program, with the default release profile versus this size-tuned profile:

1
default release bytes:   406272
2
optimized release bytes: 285936

That is a ~30% reduction on a tiny program; on a real CLI with many dependencies the absolute savings are far larger. The knobs in detail:

Setting	Default (release)	What it does	Cost
`opt-level`	`3` (speed)	`"z"`/`"s"` optimize for size; `3` for raw speed	Size vs. speed trade
`lto`	`false`	`true`/`"thin"` optimize across crates	Longer link time
`codegen-units`	`16`	`1` lets the optimizer see everything	Slower, non-parallel compile
`strip`	`false`	`true`/`"symbols"` removes symbols	Worse stack traces
`panic`	`"unwind"`	`"abort"` removes unwinding machinery	No `catch_unwind`; affects some tests

You can also define custom profiles that inherit from another — exactly what cargo-dist does:

1
[profile.dist]
2
inherits = "release"
3
lto = "thin"
4
codegen-units = 1

1
$ cargo build --profile dist
2
    Finished `dist` profile [optimized] target(s) in 0.41s
3
# Output lands in target/dist/ (named after the profile).

Warning: panic = "abort" is great for shrinking a binary, but it disables std::panic::catch_unwind and changes how some test harnesses behave. If your tool deliberately catches panics (rare in a CLI) or you hit odd test failures, drop this one knob first.

Key Differences

Concern	Node / npm	Rust / Cargo
What ships	JS source + `node_modules`	One native binary
Runtime on user’s machine	Required (Node ≥ X)	None (self-contained)
Registry-based install	`npm install -g pkg`	`cargo install pkg` (compiles from source)
Prebuilt-binary install	`pkg`/`nexe` (bolt-on, large)	First-class: any target triple
Cross-platform builds	Same JS runs everywhere	Compile per target triple (`--target`)
Static linking	N/A (ships the runtime)	`*-linux-musl` → fully static
Automated release pipeline	release-please, np, etc.	`cargo-dist` / `dist`
Build tuning	minifier/bundler config	`[profile.release]` knobs
Versioning source of truth	`package.json` `version`	`Cargo.toml` `version` (`env!("CARGO_PKG_VERSION")`)

The deepest difference is the shape of the artifact. An npm package is fundamentally a bundle of source plus a manifest, interpreted at runtime; a Cargo “package” is a recipe that produces a compiled binary. Distribution in Node is about getting source and dependencies to a runtime; distribution in Rust is about getting one compiled file to a machine. That is why cargo install compiles (it received a recipe, not a product) and why prebuilt binaries are the natural high-performance path.

A second difference: in Node the version a user runs is whatever package.json said and whatever Node they happen to have. In Rust the version, the target triple, and even the build profile are baked into the binary at compile time, so mytool --version can report exactly what was shipped (see the Real-World Example).

Common Pitfalls

Pitfall 1: Distributing the debug binary

cargo build (no flags) writes to target/debug/, which is unoptimized and often several times larger and much slower than release. Shipping that is the classic mistake.

1
$ cargo build            # -> target/debug/mytool   (unoptimized, large)
2
$ cargo build --release  # -> target/release/mytool (what you ship)

cargo install sidesteps this because it always builds release, but if you copy a binary out of target/ by hand, double-check you took it from target/release/.

Pitfall 2: `env!` fails the build when the variable is missing

The env! macro reads an environment variable at compile time and is a hard error if it is unset. People reach for it to embed a git hash, then break the build on machines where that variable was never exported. The real compiler error:

1
fn main() {
2
    // does not compile if GIT_HASH is not set at build time
3
    let hash = env!("GIT_HASH");
4
    println!("{hash}");
5
}

1
error: environment variable `GIT_HASH` not defined at compile time
2
 --> src/main.rs:3:16
3
  |
4
3 |     let hash = env!("GIT_HASH");
5
  |                ^^^^^^^^^^^^^^^^

Use option_env! instead, which returns Option<&str> and never fails to compile:

1
fn main() {
2
    // option_env! yields None instead of failing the build.
3
    let hash = option_env!("GIT_HASH").unwrap_or("dev");
4
    println!("build {hash}");
5
}

1
$ cargo run --quiet
2
build dev

Better still, set the variable yourself from a build.rs script (shown in the Real-World Example) so it is always present.

Pitfall 3: Forgetting that `cargo install` requires a toolchain

cargo install mytool is convenient for Rust developers but useless to someone without rustup/cargo. If your audience is non-developers, do not tell them to cargo install — ship a prebuilt binary or an installer script (Path 2/3). Reserve cargo install instructions for fellow Rust users.

Pitfall 4: Assuming one binary runs on every Linux

A default x86_64-unknown-linux-gnu build links against the host’s glibc. A binary built on a new Ubuntu may refuse to start on an older distro (“version `GLIBC_2.34’ not found”). For broad Linux compatibility, build the musl target, which links statically and has no such dependency:

1
$ rustup target add x86_64-unknown-linux-musl
2
$ cargo build --release --target x86_64-unknown-linux-musl

Pitfall 5: Bumping the version in the wrong place

In Node you bump package.json (often via npm version). In Rust the source of truth is Cargo.toml’s version, surfaced at runtime via env!("CARGO_PKG_VERSION") and by clap’s #[command(version)]. Editing a constant in main.rs instead means --version and the published crate disagree. Keep one source of truth: Cargo.toml.

Best Practices

Always build and ship --release. Add a tuned [profile.release] once and forget it. Start with lto = true, codegen-units = 1, and strip = true; add opt-level = "z" and panic = "abort" only if binary size matters more than raw speed.
Let Cargo.toml own the version. Read it with env!("CARGO_PKG_VERSION") and wire clap’s #[command(version)] to it so --version is always correct. See clap-derive.md.
Offer both install paths. Document cargo install mytool for Rust developers and a prebuilt-binary/installer one-liner for everyone else.
Automate releases with cargo-dist early. Wiring it up on day one is far cheaper than retrofitting a hand-rolled release script later.
Build musl for Linux distribution. A static binary eliminates an entire class of glibc support tickets.
Embed build metadata in --version (git hash, target triple, profile) so a bug report tells you exactly which build the user has.
Set sensible package metadata — description, license, repository, keywords, categories in Cargo.toml — before cargo publish; crates.io enforces some of these and users read them.

Real-World Example

A production CLI’s --version should answer “exactly which build is this?” — semver alone is not enough when you are chasing a bug. This example wires up a build.rs script that captures the git commit at build time, exposes it via an environment variable, and composes a rich version string that clap prints. It degrades gracefully when there is no git repository (e.g. building from a release tarball).

1
[package]
2
name = "deploy"
3
version = "1.2.0"
4
edition = "2024"
5

6
[dependencies]
7
clap = { version = "4", features = ["derive"] }
8

9
[profile.release]
10
lto = true
11
codegen-units = 1
12
strip = true

1
// build.rs — runs at build time, before the crate is compiled.
2
use std::process::Command;
3

4
fn main() {
5
    // Capture the short git hash, if git and a repository are available.
6
    let git_hash = Command::new("git")
7
        .args(["rev-parse", "--short", "HEAD"])
8
        .output()
9
        .ok()
10
        .filter(|out| out.status.success())
11
        .map(|out| String::from_utf8_lossy(&out.stdout).trim().to_string());
12

13
    match git_hash {
14
        // Expose the value to the crate as the GIT_HASH compile-time env var.
15
        Some(hash) => println!("cargo:rustc-env=GIT_HASH={hash}"),
16
        None => println!("cargo:rustc-env=GIT_HASH=unknown"),
17
    }
18

19
    // Re-run this script when HEAD moves, so the hash stays current.
20
    println!("cargo:rerun-if-changed=.git/HEAD");
21
}

1
use clap::Parser;
2

3
// Compose a richer version string from compile-time values.
4
// CARGO_PKG_* come from Cargo.toml; GIT_HASH is set by build.rs.
5
const VERSION: &str = concat!(
6
    env!("CARGO_PKG_VERSION"),
7
    " (",
8
    env!("GIT_HASH"),
9
    ", ",
10
    env!("CARGO_PKG_NAME"),
11
    ")"
12
);
13

14
/// A deploy helper whose --version reports the exact build.
15
#[derive(Parser)]
16
#[command(name = "deploy", version = VERSION)]
17
struct Cli {
18
    /// Environment to deploy to.
19
    #[arg(default_value = "staging")]
20
    target: String,
21
}
22

23
fn main() {
24
    let cli = Cli::parse();
25
    println!("deploying to {}", cli.target);
26
}

Running it outside a git repository (e.g. an unpacked release tarball) falls back cleanly, and inside one it reports the commit:

1
# No git repository present:
2
$ cargo run --quiet -- --version
3
deploy 1.2.0 (unknown, deploy)
4

5
# Inside a git repository:
6
$ cargo run --quiet -- --version
7
deploy 1.2.0 (1aa8128, deploy)
8

9
$ cargo run --quiet
10
deploying to staging

For an even richer version line (target triple, build profile, rustc version), the built crate captures all of it for you. Add it as a build dependency and generate the metadata:

1
[build-dependencies]
2
built = { version = "0.8", features = ["git2"] }

1
fn main() {
2
    // Writes $OUT_DIR/built.rs with PKG_VERSION, GIT_COMMIT_HASH_SHORT,
3
    // TARGET, PROFILE, RUSTC_VERSION, and more as constants.
4
    built::write_built_file().expect("failed to gather build-time info");
5
}

1
use clap::Parser;
2

3
// Pull in the constants `built` generated.
4
mod build_info {
5
    include!(concat!(env!("OUT_DIR"), "/built.rs"));
6
}
7

8
fn long_version() -> &'static str {
9
    use build_info::{GIT_COMMIT_HASH_SHORT, PKG_VERSION, PROFILE, TARGET};
10
    let commit = GIT_COMMIT_HASH_SHORT.unwrap_or("unknown");
11
    // Leak the formatted string so clap can hold a &'static str.
12
    Box::leak(format!("{PKG_VERSION} ({commit} {TARGET} {PROFILE})").into_boxed_str())
13
}
14

15
/// A tool whose --version shows the full build provenance.
16
#[derive(Parser)]
17
#[command(name = "buildinfo", version = long_version())]
18
struct Cli {}
19

20
fn main() {
21
    let _ = Cli::parse();
22
    println!("running");
23
}

1
$ cargo run --quiet -- --version
2
buildinfo 0.1.0 (374eb71 aarch64-apple-darwin debug)

Now every bug report that includes --version tells you the semver, the exact commit, the platform it was built for, and whether it was a debug or release build — invaluable when you ship binaries to platforms you do not control.

Exercises

Exercise 1: A size-tuned release profile

Difficulty: Beginner

Objective: Measure the impact of release-profile settings on binary size.

Instructions: Create a new binary crate with cargo new sizer. Build it once with the default release profile (cargo build --release) and record the size of target/release/sizer. Then add a [profile.release] section enabling lto = true, codegen-units = 1, and strip = true, rebuild, and compare. (On macOS/Linux, ls -l target/release/sizer shows the byte count.)

Solution

Add this to Cargo.toml:

1
[profile.release]
2
lto = true          # optimize across crate boundaries at link time
3
codegen-units = 1   # let the optimizer see the whole crate
4
strip = true        # remove symbol/debug info from the binary

1
fn main() {
2
    println!("Hello, world!");
3
}

1
$ cargo build --release   # before adding the profile
2
$ ls -l target/release/sizer    # note the size
3
$ cargo build --release   # after adding the profile
4
$ ls -l target/release/sizer    # smaller

For a near-trivial program, the default release profile produced a ~406 KB binary while a tuned profile (here using opt-level = "z" as well) produced ~286 KB — about a 30% reduction. strip = true removes the symbol table (which is why the binary shrinks even though the code is identical), and lto + codegen-units = 1 let the optimizer eliminate cross-crate dead code. The savings grow with the number of dependencies.

Exercise 2: Wire `--version` to `Cargo.toml`

Difficulty: Intermediate

Objective: Make a single source of truth for the version, surfaced via --version.

Instructions: Using clap’s derive API, build a CLI named whatver whose --version prints the value from Cargo.toml and nothing hard-coded in source. Set the version field in Cargo.toml to "2.3.1" and confirm whatver --version reports it. (Add clap with cargo add clap --features derive.)

Solution

1
[package]
2
name = "whatver"
3
version = "2.3.1"
4
edition = "2024"
5

6
[dependencies]
7
clap = { version = "4", features = ["derive"] }

1
use clap::Parser;
2

3
/// A tool that reports its version from Cargo.toml.
4
// `version` with no value uses env!("CARGO_PKG_VERSION") automatically.
5
#[derive(Parser)]
6
#[command(name = "whatver", version)]
7
struct Cli {
8
    /// Optional name to greet.
9
    #[arg(default_value = "world")]
10
    name: String,
11
}
12

13
fn main() {
14
    let cli = Cli::parse();
15
    println!("Hello, {}!", cli.name);
16
}

1
$ cargo run --quiet -- --version
2
whatver 2.3.1
3

4
$ cargo run --quiet -- Ada
5
Hello, Ada!

#[command(version)] with no explicit value tells clap to read CARGO_PKG_VERSION, which Cargo bakes in from the manifest. Bumping the version in Cargo.toml is now the only place you change it — --version and the published crate can never drift apart.

Exercise 3: Embed a build-time fingerprint

Difficulty: Advanced

Objective: Use a build.rs script to inject a value into the binary that is available at runtime, degrading gracefully.

Instructions: Write a build.rs that sets a BUILD_TIME environment variable to the current UTC date (you may shell out to date -u +%Y-%m-%d, or hard-code a placeholder if date is unavailable). In main.rs, read it with option_env! so the build never fails if the variable is missing, defaulting to "unknown", and print it. Explain why option_env! is the safe choice over env! here.

Solution

1
use std::process::Command;
2

3
fn main() {
4
    // Try to capture today's UTC date; fall back if `date` is unavailable.
5
    let build_date = Command::new("date")
6
        .args(["-u", "+%Y-%m-%d"])
7
        .output()
8
        .ok()
9
        .filter(|out| out.status.success())
10
        .map(|out| String::from_utf8_lossy(&out.stdout).trim().to_string());
11

12
    if let Some(date) = build_date {
13
        // Expose it as a compile-time env var for the crate.
14
        println!("cargo:rustc-env=BUILD_TIME={date}");
15
    }
16
    // If we printed nothing, BUILD_TIME is simply unset — handled below.
17
}

1
fn main() {
2
    // option_env! returns Option<&str> resolved at compile time.
3
    // It yields None (instead of failing the build) when BUILD_TIME is unset.
4
    let built = option_env!("BUILD_TIME").unwrap_or("unknown");
5
    println!("built on {built}");
6
}

1
$ cargo run --quiet
2
built on 2026-06-01

option_env! is the safe choice because env! is a compile error if the variable is not defined — and a build script is not guaranteed to set it (the date command might fail, or someone might compile in an unusual environment). option_env! turns “not set” into a None you can handle (unwrap_or("unknown")), so the binary always builds. The build.rs runs before crate compilation and communicates back to the compiler purely through the cargo:rustc-env=KEY=VALUE lines it prints to stdout.

Distributing CLI Tools

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Path 1: cargo install — the npm install -g analogue

Path 2: Prebuilt binaries

Path 3: cargo-dist — automating the whole release

Release profiles — how Cargo decides what to build

Key Differences

Common Pitfalls

Pitfall 1: Distributing the debug binary

Pitfall 2: env! fails the build when the variable is missing

Pitfall 3: Forgetting that cargo install requires a toolchain

Pitfall 4: Assuming one binary runs on every Linux

Pitfall 5: Bumping the version in the wrong place

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: A size-tuned release profile

Exercise 2: Wire --version to Cargo.toml

Exercise 3: Embed a build-time fingerprint

Path 1: `cargo install` — the `npm install -g` analogue

Path 3: `cargo-dist` — automating the whole release

Pitfall 2: `env!` fails the build when the variable is missing

Pitfall 3: Forgetting that `cargo install` requires a toolchain

Exercise 2: Wire `--version` to `Cargo.toml`