The installrs command-line tool builds a self-contained installer
executable from an installer crate.
installrs build <dir> --output <file> [options]| Arg / flag | Description |
|---|---|
<PATH> (positional) |
Directory containing the installer source crate. Default: . |
--output <file> |
Output installer file path. Default: ./installer |
--compression <method> |
Compression method for embedded files (default lzma) |
--ignore <patterns> |
Comma-separated glob patterns to ignore when gathering directories |
--target <triple> |
Rust target triple for cross-compilation |
--feature <name> |
Enable a user-library cargo feature (repeatable) |
-m / --metadata <K=V> |
Override a [package.metadata.installrs] key (repeatable) |
--installrs-path <path> |
Depend on installrs via path = "<path>" instead of crates.io |
-v / -vv |
Debug output / trace output |
-q / --quiet |
Suppress non-error output |
-s / --silent |
Suppress all output |
The --installrs-path flag is for InstallRS-on-InstallRS development
(CI, integration tests, the release script). End users should leave it
unset; the generated crate then pulls a version-pinned installrs
runtime from crates.io that matches the CLI version.
Build an installer with defaults:
installrs build my-installer --output installerCross-compile for Windows from Linux (requires mingw):
installrs build my-installer --output installer.exe \
--target x86_64-pc-windows-gnuUse gzip compression for faster builds at the cost of larger binaries:
installrs build my-installer --output installer --compression gzipVerbose build to see what files got embedded:
installrs build my-installer --output installer -vEnable user-library cargo features — gates source!(..., features = [...]) entries and activates matching #[cfg(feature = "...")] code
in your installer library:
installrs build my-installer --feature pro --feature docsOverride individual [package.metadata.installrs] keys at build time
without touching Cargo.toml — handy for stamping CI-supplied version
strings or per-build values:
installrs build . -m file-version="$(cat version.txt)" \
-m product-version="$(cat version.txt)" \
-m installer.file-description="My App Installer (CI)" \
-m gui=true \
-m language=0x0409KEY is a dotted path into the metadata table (file-version,
installer.file-description, etc.). VALUE parses as TOML — true /
false become booleans, integers (decimal or 0x-hex) become
integers, everything else stays a string. Overrides apply after
feature overlays and after the package-version fallback for
file-version / product-version, so they always win.
The named features must exist in your installer crate's [features]
table. The builder passes them through to the user-crate dependency of
the generated installer and uninstaller, so one --feature flag
covers both the embedded-file gating and the compile-time code
gating.
[package.metadata.installrs.feature.<name>] subtables are merged
onto the base [package.metadata.installrs] table when <name> is
passed via --feature. This lets one crate produce multiple installers
that differ in product name, icon, version info, or any other metadata
key — without duplicating source.
[package.metadata.installrs]
product-name = "My App"
icon = "assets/base.png"
[package.metadata.installrs.feature.pro]
product-name = "My App Pro"
icon = "assets/pro.png"
file-version = "1.2.3.4"
[package.metadata.installrs.feature.lite]
product-name = "My App Lite"installrs build . --feature pro --output installer-pro
installrs build . --feature lite --output installer-lite
installrs build . --output installer-base # no overlayPer-feature overlays can also override individual keys inside the
installer / uninstaller subtables — useful when only the installer
or uninstaller side differs per edition:
[package.metadata.installrs.installer]
file-description = "My App Installer"
internal-name = "myapp-installer"
[package.metadata.installrs.feature.pro.installer]
file-description = "My App Pro Installer"
# internal-name inherits "myapp-installer" from the baseMerge rules:
- Top-level keys: overlay keys replace base keys wholesale.
installer/uninstallersubtables: merged key-by-key, so an overlay can override individual fields without restating the rest.- Multiple
--featureflags apply in argument order; later wins on conflicts. - Overlay subtables can set
gui = trueto enable the wizard for certain editions only.
The generated installer/uninstaller crates use an aggressive
size-optimized release profile (lto = true, codegen-units = 1,
opt-level = "z") which is slow to compile. For faster iteration
during development, override via cargo env vars — they're inherited by
the inner cargo build --release that installrs spawns:
CARGO_PROFILE_RELEASE_LTO=false \
CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16 \
CARGO_PROFILE_RELEASE_OPT_LEVEL=1 \
installrs build my-installerExpect a 3–5× speedup at the cost of a larger binary. Drop these for the real release build.
[package.metadata.installrs]reference — every key the--metadataflag and the metadata table accept.- Building for production — cross-compilation, reproducibility, payload integrity, code signing, and a snippet for installing the matching CLI in CI from a prebuilt GitHub release tarball.
- Getting Started — the walkthrough that uses these flags in context.