Skip to main content

Crate libcrapapp

Crate libcrapapp 

Source
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 from CRAP.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-crapapp

Run 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.exe

Linux 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-gnu
  • x86_64-pc-windows-msvc
  • aarch64-pc-windows-gnullvm
  • aarch64-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=0

ADD_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:

  • directory
  • file

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 the cargo-crapapp binary.
  • 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-crapapp binary. CLI implementation for the cargo crapapp subcommand.
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.