Expand description
§crapapp
Crapapp is a cargo plugin for bundling Rust desktop apps from CRAP.toml without external
dependencies like wixl or nsis.
This crate ships two things:
cargo-crapapp, a Cargo subcommand for building app installers fromCRAP.toml.libcrapapp, the shared implementation used by the CLI.
The workspace example package is only a local fixture for development and
testing. It is not part of the public API.
§cargo-crapapp
Install the Cargo subcommand:
cargo install cargo-crapappRun it from an application crate that has a CRAP.toml next to its
Cargo.toml:
cargo crapapp inspect
cargo crapapp inspect --output json
cargo crapapp build§cargo crapapp inspect
Reads CRAP.toml, validates the configuration, reads Cargo package metadata,
and prints the build manifest that cargo crapapp build will use.
Options:
--output text, the default human-readable output.--output json, machine-readable build manifest output.-o json, short form for JSON output.
§cargo crapapp build
Reads CRAP.toml, builds configured Cargo packages for configured platform
targets, and writes the binaries to the configured Cargo target directory.
§cargo crapapp bundle
Reads CRAP.toml, builds configured Cargo packages for configured platform
targets, collects payload files, and writes generated output under
.crapapp_build.
Use cargo crapapp bundle --no-build or cargo crapapp bundle -n to skip
building configured Cargo packages before bundling existing binaries.
Use platform filters to build only selected bundle formats:
cargo crapapp bundle --no-build --linux deb aur --windows msi --macos app dmg pkgWhen any platform filter is present, only those platforms are bundled. Requested
bundle formats must also be configured for that platform in CRAP.toml.
Bundler output currently lands in:
.crapapp_build/windows/<target>/msi/<display-name-or-package-name>.msi
.crapapp_build/macos/<target>/app/<display-name-or-package-name>.app
.crapapp_build/macos/<target>/pkg/<display-name-or-package-name>.pkg
.crapapp_build/macos/<target>/dmg/<display-name-or-package-name>.dmg
.crapapp_build/linux/<target>/deb/<package-name>.deb
.crapapp_build/linux/<target>/rpm/<package-name>-<version>-1.rpm
.crapapp_build/linux/<target>/aur/<package-name>.aur§CRAP.toml quick start
CRAP.toml declares what cargo-crapapp should build and package.
[build]
publisher = "Acme"
display_name = "Acme Launcher"
description = "Desktop launcher for Acme tools"
homepage = "https://example.com/acme-launcher"
license = "Apache-2.0"
license_file = "LICENSE"
packages = ["acme-launcher"]
features = ["sqlite"]
[windows]
targets = ["x86_64-pc-windows-gnu"]
install_path = "$INSTALLPATH"
path_entries = ["$INSTALLPATH", "$INSTALLPATH/bin"]
bundle = "msi"
display_icon = "assets/app.ico"
files = [
{ source = "assets", destination = "assets" },
]
eulas = [
{ path = "EULA.txt" },
{ path = "THIRD_PARTY.txt", required = false },
]
associated_files = [
{ path = "$HOMEPATH/Documents/Acme/saves", kind = "directory" },
{ path = "$HOMEPATH/Documents/Acme/eulas", kind = "directory", eula_report = true },
]
shortcuts = [
{ binary = "acme-launcher", name = "Acme Launcher", directory = "Acme" },
]
[macos]
targets = ["aarch64-apple-darwin"]
bundle = ["app", "pkg"]
display_icon = "assets/app.icns"
app_binary = "acme-launcher"
eulas = [
{ path = "EULA.txt" },
{ path = "THIRD_PARTY.txt", required = false },
]
files = [
{ source = "assets", destination = "Resources/assets" },
]
[macos.pkg]
identifier = "com.acme.launcher"
install_path = "/Applications"
bin_dir = "/usr/local/bin"
link_bins = true
[linux]
targets = ["x86_64-unknown-linux-gnu"]
bundle = "deb"
bin_dir = "/usr/bin"
display_icon = "assets/app.png"
shortcuts = [
{ binary = "acme-launcher", name = "Acme Launcher" },
]
files = [
{ source = "assets", destination = "/usr/share/acme-launcher/assets" },
]
associated_files = [
{ path = "/var/lib/acme-launcher", kind = "directory" },
]
eulas = [
{ path = "EULA.txt" },
{ path = "THIRD_PARTY.txt", required = false },
]§CRAP.toml reference
CRAP.toml is strict: unknown fields are rejected. The supported top-level
sections are [build], [windows], [macos], [macos.pkg], and [linux].
§[build]
[build] is optional. It controls Cargo package selection, feature selection,
and display metadata reused by platform bundlers.
Fields:
publisher: optional string. Used as the Windows uninstall registryPublisher, as part of the generated macOS package identifier, and as package maintainer metadata for deb output. If omitted, platform outputs use their own fallback.display_name: optional string. User-facing app name. If omitted, the Cargo package name is used. macOS app/pkg names and installer UI labels use this value when present.description: optional string. Package description used by Linux package metadata. If omitted, the Cargo package description is used, thendisplay_name, then the Cargo package name.homepage: optional URL. Used by Linux AppStream metadata to show an App Center Developer website link. If omitted, Cargo’s packagehomepageis used when available.license: optional SPDX license expression such asMITorApache-2.0. Used in Linux AppStream metadata and RPM package metadata. If omitted, Cargo’s packagelicenseis used when available.license_file: optional path to the license document to include verbatim in Linux packages. If omitted, Cargo’s packagelicense-fileis used when available. Use this alongsidelicense: the former supplies the exact legal text, while the latter supplies its SPDX identifier.packages: optional array containing the application package name. The selected package supplies the application metadata and binary targets, and is passed to Cargo with--package. This is required when running from a virtual Cargo workspace, because that workspace root does not itself define a package. Exactly one package may be selected; if omitted, cargo-crapapp uses the package defined by the currentCargo.toml.features: optional array of strings. Entries are passed to Cargo as enabled features. If missing or empty, cargo-crapapp does not pass feature flags.
§Common field types
files entries copy extra payload data in addition to Cargo binaries:
files = [
{ source = "assets", destination = "assets" },
{ source = "config/default.json", destination = "config/default.json" },
]Fields:
source: required path string. It must exist when cargo-crapapp reads the manifest. A file is copied as one payload file. A directory is walked recursively and copied in deterministic path order.destination: required path string. Meaning depends on platform. Windows and Linux use package/install paths directly. macOS app/pkg paths are relative to.app/Contentsunless the destination starts withContents/.
eulas entries describe license files:
eulas = [
"EULA.txt",
{ path = "THIRD_PARTY.txt", required = false },
]An entry can be a plain path string or an object.
path: required for object form. Source text file path.required: optional boolean, defaulttrue. The Windows MSI uses it to decide whether the acceptance checkbox gates the Next button. macOS pkg and Linux packages preserve the license as package content; they do not expose the same optional-license wizard.
associated_files entries create app-owned empty files or directories:
associated_files = [
{ path = "$HOMEPATH/Documents/Acme/saves", kind = "directory" },
{ path = "$INSTALLPATH/settings.json", kind = "file", eula_report = true },
]Fields:
path: required path string.kind: required, eitherfileordirectory.eula_report: retained for manifest compatibility but not currently emitted by MSI, Linux, or macOS package writers. Do not rely on it for audit records. macOS pkg does not useassociated_files.
§[windows]
[windows] configures Windows setup output.
Fields:
targets: optional array of target triples. Supported values arex86_64-pc-windows-gnu,x86_64-pc-windows-msvc,aarch64-pc-windows-gnullvm, andaarch64-pc-windows-msvc.bundle: optional string or array. Defaults tomsi; this is the only currently supported Windows bundle format. It generates a Windows Installer database with an embedded cabinet payload.install_path: optional string. If present, relative binary and payload destinations are prefixed with it in the build manifest.$INSTALLPATHis resolved by the generated installer at runtime.bin_dir: optional string. If omitted, Cargo binaries are installed directly underinstall_pathwheninstall_pathis present. If present, Cargo binaries are installed under that directory relative toinstall_path, unless the path is already absolute/symbolic in the manifest.path_entries: optional array of directories the MSI adds to the current user’sPATH. Each entry must start with$INSTALLPATH; use$INSTALLPATHfor the installation root and$INSTALLPATH/binfor a subdirectory. It defaults to["$INSTALLPATH"]when omitted or empty. The installer shows an enabled Add to PATH checkbox so the user can opt out.files: optional array of payload file mappings.associated_files: optional array of associated file mappings.eulas: optional array of EULA files.shortcuts: optional array. Creates Start Menu.lnkfiles. Windows Search can find those shortcuts, but cargo-crapapp does not pin them.display_icon: optional PNG or ICO path. It is embedded as the Add/Remove Programs product icon and stamped into executable payloads before they are packaged.
MSI support covers payload files, Start Menu shortcuts, shortcut icons,
Add/Remove Programs metadata and product icons, EULAs, per-user PATH updates,
and $INSTALLPATH/$HOMEPATH associated files and directories through standard
Windows Installer tables. The MSI UI includes welcome, license, installation
directory, ready, progress, and completion dialogs; the directory page uses the
native Windows folder picker.
shortcuts fields:
binary: required Cargo binary name without.exe.name: required Start Menu shortcut display name.directory: optional Start Menu directory.icon: optional icon source path. The installer copies it into the payload and points the shortcut at the installed icon. If omitted, the shortcut uses the target executable icon.
Windows Installer resolves INSTALLPATH through its installation-directory UI
and HOMEPATH to the current user’s home directory. ADD_TO_PATH defaults to
1; the configured path_entries are appended to the current user’s PATH
unless the user clears the installer checkbox or an MSI property transform or
command-line property disables it.
§[macos]
[macos] configures .app, .pkg, and .dmg output.
Fields:
targets: optional array of target triples. Supported values arex86_64-apple-darwinandaarch64-apple-darwin.bundle: optional string or array. Defaults toapp. Values areapp,pkg, anddmg.display_icon: optional icon path. The source is copied intoContents/Resources. When the source is.icns,Info.plistalso setsCFBundleIconFile.app_binary: optional Cargo binary name. It becomesCFBundleExecutable. If omitted or empty, cargo-crapapp falls back to the first executable payload.files: optional array of payload file mappings. Destinations are relative to.app/Contentsunless they start withContents/.eulas: optional array of EULA files. For pkg output, files are merged into top-levelResources/License.txt, and the Distribution points Apple Installer at that license resource.pkg: optional table configured through[macos.pkg].
Finder-launched .app bundles should point app_binary at a GUI binary. macOS
does not open Terminal for a CLI executable launched from Finder, so stdout,
stderr, and stdin are not visible as an interactive terminal session.
§[macos.pkg]
[macos.pkg] configures bundle = "pkg".
Fields:
identifier: optional reverse-DNS package receipt id. If omitted, cargo-crapapp derives one frompublisherand the Cargo package name.install_path: optional absolute path, default/Applications. The app installs as<install_path>/<display-name-or-package-name>.app.bin_dir: optional absolute path, default/usr/local/bin. Used only whenlink_bins = true.link_bins: optional boolean, defaulttrue. When enabled, each executable payload gets a shell shim inbin_dirthat forwards to the matching binary in<app>.app/Contents/MacOS.
The pkg writer is implemented in Rust and does not call pkgbuild,
productbuild, or other system packaging tools.
§[linux]
[linux] configures Linux package output.
Fields:
targets: optional array of target triples. Supported values arex86_64-unknown-linux-gnu,x86_64-unknown-linux-musl,aarch64-unknown-linux-gnu, andaarch64-unknown-linux-musl.bundle: optional string or array. Defaults todeb. Values aredeb,rpm, andaur.install_path: optional string. If present, relative binary and payload destinations are prefixed with it in the build manifest.bin_dir: optional string, default/usr/bin. Cargo binaries are installed there, or underinstall_path/bin_dirwheninstall_pathis present and the destination is not already prefixed.files: optional array of payload file mappings.associated_files: optional array of associated file mappings. Linux package output creates these as empty files or directories in the package payload.eulas: optional array of EULA files. deb output installs them under/usr/share/doc/<package>/licenses; rpm and AUR output install them under/usr/share/licenses/<package>.- The
[build].license_filedocument is copied verbatim to/usr/share/licenses/<package>/LICENSEin deb, rpm, and AUR output. deb also writes/usr/share/doc/<package>/copyrightwith the SPDX identifier. shortcuts: optional array of desktop launchers. Each entry creates one.desktopentry using itsname,binary, and optionalicon. When this is set, only declared shortcuts appear in the app finder.display_icon: optional icon path. Linux package writers convert it to a 256×256 PNG and install it under/usr/share/icons/hicolor; generated.desktopentries use that application icon unless a shortcut supplies one.
Linux shortcuts use the same fields as Windows: binary is the Cargo binary
name, name is the app-finder label, and icon is an optional icon source.
The deb, rpm, and AUR writers are implemented in Rust and do not call
dpkg-deb, rpmbuild, or makepkg. AUR output is a single gzip-compressed
.aur archive containing a top-level package directory with PKGBUILD,
.SRCINFO, and all local source files. Extract it, then run makepkg from
that directory.
Building Linux GNU targets from macOS requires a matching Linux GNU linker and
sysroot. The Rust target alone is not enough, because glibc targets still link
against Linux system libraries such as libc, libpthread, and libdl. For
example, aarch64-unknown-linux-gnu needs aarch64-unknown-linux-gnu-gcc or a
Cargo/Rust configuration that points at an equivalent Linux toolchain. If those
tools are not configured, build the Linux binaries on Linux and run
cargo crapapp bundle --no-build.
§libcrapapp
libcrapapp is the library crate behind the CLI.
Current public entrypoints:
run_cli, used by thecargo-crapappbinary.windows_installer, Windows MSI authoring and bundling support.
The cargo-crapapp binary intentionally stays tiny:
use libcrapapp::run_cli;
fn main() -> anyhow::Result<()> {
run_cli()
}The crate does not expose generated Windows setup projects or Windows runtime features; Windows output is authored directly as MSI.
Modules§
- windows_
installer - Windows MSI authoring and bundling.