Getting Started with Packager

Packager is currently in public preview, so feel free to report any bugs you find and feature requests you might have!

Cargo Packager is a tool to package executables as installers or app bundles for macOS, Windows and Linux, available both as a Command Line Interface (CLI) and a Rust library. It also has a compatible auto updater through cargo-packager-updater that lets your application update itself when you distribute a new release.

Supported Packages

macOS
- Apple Disk Image (.dmg)
- Application Bundle (.app)
Linux
- Debian package (.deb)
- AppImage (.AppImage)
- Pacman (.tar.gz and PKGBUILD)
Windows
- NSIS (.exe)
- MSI using WiX Toolset (.msi)

Rust

CLI

The packager is distributed on crates.io as a cargo subcommand, you can install it using cargo:

cargo install cargo-packager --locked

You then need to configure your app so the CLI can recognize it. Configuration can be done in Packager.toml or packager.json in your project or modify Cargo.toml.

Packager.toml

The packager configuration can be defined in a standalone Packager.toml file:

name = "my-app"
product-name = "MyApp"
identifier = "com.packager.example"
version = "1.0.0"
out-dir = "./dist"
before-packaging-command = "cargo build --release"

Once you are done configuring your app, run:

cargo packager --release

Configuration

By default, the packager reads its configuration from Packager.toml (or packager.json if it exists) and from the package.metadata.packager table in Cargo.toml. You can also specify a custom configuration using the --config CLI argument.

For a full list of configuration options, see the configuration page.

Building Your Application Before Packaging

By default, the packager doesn’t build your application, so if your app requires a compilation step, the packager has an option to specify a shell command to be executed before packaging your app: beforePackagingCommand.

Cargo Profiles

By default, the packager looks for binaries built using the debug profile, if your beforePackagingCommand builds your app using cargo build --release, you will also need to run the packager in release mode cargo packager --release. Otherwise, if you have a custom cargo profile, you will need to specify it using --profile CLI argument. For example:

cargo packager --profile custom-release-profile

Library

This crate is also published to crates.io as a library, so that you can integrate into your tooling, just make sure to disable the default-feature flags.

cargo add cargo-packager --no-default-features

Feature Flags

cli: Enables the CLI specific features and dependencies.
tracing: Enables tracing crate integration.

NPM (Node.js)

CLI

The packager is distributed on NPM as a CLI, you can install it with your preferred package manager:

# pnpm
pnpm add -D @crabnebula/packager
# yarn
yarn add -D @crabnebula/packager
# npm
npm i -D @crabnebula/packager

You then need to configure your app so the CLI can recognize it. Configuration can be done in your project package.json file by using the packager key in packager.json. Once you are done configuring your app, run:

# pnpm
pnpm packager
# yarn
yarn packager
# npm
npx packager

Building your application before packaging

Library

The packager is also a library that you can import and integrate into your tooling.

Examples

The examples directory contains a number of varying examples, if you want to build them all clone the cargo-packager repository and run cargo r -p cargo-packager -- --release in the root of the repository. Just make sure to have the tooling for each example installed on your system. You can find what tooling they require by checking the README file in each example. The README also contains a command to build the example alone if you wish.

Examples list (non-exhaustive):