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 library used by the CLI and by generated Windows installer projects.
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, collects payload files, and writes generated output under
.crapapp_build.
Windows installer output currently lands in:
.crapapp_build/windows/<target>/setup.exeLinux and macOS output are not supported yet.
§CRAP.toml quick start
CRAP.toml declares what cargo-crapapp should build and how Windows setup
should behave.
[build]
publisher = "Acme"
display_name = "Acme Launcher"
packages = ["acme-launcher"]
features = ["sqlite"]
[windows]
targets = ["x86_64-pc-windows-gnu"]
install_path = "$INSTALLPATH"
installer = "gui"
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" },
]§Build section
The optional [build] section controls Cargo package selection and feature
selection.
[build]
publisher = "Acme"
display_name = "Acme Launcher"
packages = ["acme-launcher"]
features = ["sqlite", "native-tls"]packages maps to Cargo package selection. If it is empty or missing,
cargo-crapapp does not pass package flags to Cargo.
features maps to Cargo feature selection. If it is empty or missing,
cargo-crapapp does not pass feature flags to Cargo.
publisher is optional. Windows setup writes the uninstall registry
Publisher value only when this key is present.
display_name is optional. Windows setup uses it for installer text and the
uninstall registry DisplayName. If it is missing, the Cargo package name is
used.
§Windows section
Windows is the only platform with generated installable output right now.
[windows]
targets = ["x86_64-pc-windows-gnu"]
install_path = "$INSTALLPATH"
installer = "gui"
display_icon = "assets/app.ico"
files = [
{ source = "assets", destination = "assets" },
]Supported Windows targets:
x86_64-pc-windows-gnux86_64-pc-windows-msvcaarch64-pc-windows-gnullvmaarch64-pc-windows-msvc
MSVC targets require a working MSVC-compatible Windows toolchain: linker, Windows SDK libraries, and the usual Cargo target configuration. Windows has that path by default through Visual Studio Build Tools. Linux/macOS can build MSVC targets only when that toolchain is configured explicitly, for example with an LLVM/lld-based setup and Windows SDK import libraries. cargo-crapapp does not set up that cross toolchain for you.
§Windows installer mode
installer is optional and defaults to cli.
[windows]
installer = "gui"Supported values:
cli, generates a command-line setup executable.gui, generates a graphical setup executable.
§Windows install path
install_path is optional. If present, relative payload destinations are
prefixed with it in the build manifest.
[windows]
install_path = "$INSTALLPATH"Variables such as $INSTALLPATH stay symbolic in the build manifest and are
resolved by the generated installer at runtime.
Generated Windows setup accepts runtime variables with repeated --args
arguments:
setup.exe --args INSTALLPATH=C:\Users\me\AppData\Local\Acme
setup.exe --args INSTALLPATH=C:\Users\me\AppData\Local\Acme --args ADD_TO_PATH=0ADD_TO_PATH defaults to 1, so executable payload directories are added to the
current user’s PATH unless explicitly disabled.
§Windows binary directory
bin_dir is optional. If omitted, Cargo binaries are installed directly into
install_path when install_path is present.
[windows]
install_path = "$INSTALLPATH"
bin_dir = "bin"§Windows payload files
files is optional. Each entry copies an extra file or directory into the
payload.
[windows]
files = [
{ source = "assets", destination = "assets" },
{ source = "config/default.json", destination = "config/default.json" },
]Cargo binaries are added automatically from the selected Cargo package metadata.
§Windows display icon
display_icon is optional. It names a PNG or ICO file.
[windows]
display_icon = "assets/app.ico"The GUI installer uses this icon in its header. Windows uninstall registry
DisplayIcon points to the installed app executable. The generated setup.exe
itself always uses the cargo-crapapp crab icon.
cargo-crapapp does not modify built application binaries. If the application
executable should have this icon in Explorer or Windows Search, the application
crate must embed it itself, for example from its own build.rs.
§Windows EULAs
eulas is optional. Each entry can be a path string or an object.
[windows]
eulas = [
"EULA.txt",
{ path = "THIRD_PARTY.txt", required = false },
]required defaults to true. GUI installation and reinstallation show each
EULA on its own screen before settings.
§Windows associated files
associated_files is optional. It creates app-owned files or directories during
installation.
[windows]
associated_files = [
{ path = "$HOMEPATH/Documents/Acme/saves", kind = "directory" },
{ path = "$INSTALLPATH/settings.json", kind = "file" },
]Supported kind values:
directoryfile
Associated file paths support:
$INSTALLPATH, resolved from the install path selected at runtime.$HOMEPATH, resolved to the current user’s home directory at installer runtime.
Associated files are not payload files. They are empty files or directories that the installed app can use later. The uninstaller can remove them when the user chooses to remove associated files.
Set eula_report = true on an associated file or directory to write a JSON EULA
acceptance report after installation.
[windows]
associated_files = [
{ path = "$HOMEPATH/Documents/Acme/eulas", kind = "directory", eula_report = true },
]For a directory, the installer writes eulas.json inside it. For a file, the
installer writes the report to that file path.
§Windows shortcuts
shortcuts is optional. It creates Start Menu .lnk files so Windows Search
can find the app by display name. It does not pin anything.
[windows]
shortcuts = [
{ binary = "acme-launcher", name = "Acme Launcher", directory = "Acme" },
]Fields:
binary, the Cargo binary name without.exe.name, the Start Menu shortcut display name.directory, optional Start Menu directory.
§Linux and macOS
Linux and macOS installable output are not supported yet.
The manifest parser accepts [linux] and [macos] sections so the build
manifest shape can evolve across platforms, but cargo crapapp build does not
produce Linux packages, macOS .app bundles, or self-contained Linux/macOS apps
yet.
§libcrapapp
libcrapapp is the library crate behind the CLI and the generated Windows setup
projects.
Current public entrypoints:
run_cli, used by thecargo-crapappbinary.services, build manifest creation and bundling internals used by the CLI.windows_installer, runtime installer and uninstaller code embedded into generated Windows setup projects.
The cargo-crapapp binary intentionally stays tiny:
use libcrapapp::run_cli;
fn main() -> anyhow::Result<()> {
run_cli()
}Generated Windows setup projects depend on libcrapapp with one runtime feature:
cli, for command-line installers.gui, for graphical installers.
Future application-facing helpers, for example Windows icon/resource helpers,
should live under libcrapapp and be documented here.
Re-exports§
pub use cli::run_cli;
Modules§
- cli
- Command-line entrypoint used by the
cargo-crapappbinary. CLI implementation for thecargo crapappsubcommand. - services
- Build manifest, Cargo metadata, payload, and bundling services.
Build-manifest and bundling services used by
cargo crapapp. - windows_
installer - Runtime Windows installer and uninstaller code embedded into generated setup projects. Runtime Windows installer and uninstaller library.