cargo-deb

Debian packages from Cargo projects

This is a Cargo helper command which automatically creates binary Debian packages (.deb) from Cargo projects.

Installation

rustup update   # Bookworm's Rust is too outdated, use Trixie or rustup.rs
cargo install cargo-deb

Requires Rust 1.76+, and optionally dpkg, dpkg-dev and liblzma-dev. Compatible with Ubuntu. If the LZMA dependency causes you headaches, try cargo install cargo-deb --no-default-features.

If you get a compilation error, run rustup update! If you get an error running rustup update, uninstall your rust/cargo package, and install the official Rust instead.

Usage

cargo deb

When you run cargo deb from the base directory of your Rust/Cargo project, the Debian package will be created in target/debian/_-1_.deb (or you can change the location with the --output option).

This package can be installed with dpkg -i target/debian/*.deb. cargo deb --install builds and immediately installs the package on the local system.

Optional Configuration

No configuration is necessary to make a basic package from a Cargo project with a binary. This command obtains basic information it needs from the Cargo.toml file. It uses Cargo fields: name, version, license, license-file, description, readme, and homepage or repository. For a more complete Debian package, you may also define a new table, [package.metadata.deb] that contains additional metadata (described below).

For a Debian package that includes one or more systemd unit files you may also wish to define a new (inline) table, [package.metadata.deb.systemd-units], so that the unit files are automatically added as assets and the units are properly installed. Systemd integration

Debug symbols

Debug symbols are stripped from built binaries by default, unless [profile.release] debug is enabled in Cargo.toml (debug = "line-tables-only" is recommended). The --separate-debug-symbols and --dbgsym options package debug symbols as separate files installed at /usr/lib/debug/.debug. This can also be enabled via [package.metadata.deb] under separate-debug-symbols.

[package.metadata.deb] options

Everything is optional:

• name: The name of the Debian package. If not present, the name of the crate is used.
• maintainer: The person maintaining the Debian packaging. If not present, the first author is used. Can be set via --maintainer on the command line.
• copyright: To whom and when the copyright of the software is granted. If not present, the list of authors is used.
• license-file: 2-element array with a location of the license file and the amount of lines to skip at the top. If not present, package-level license-file is used.
• depends: The runtime dependencies of the project. Generated automatically when absent, or if the list includes the $auto keyword.
• pre-depends: The pre-dependencies of the project. This will be empty by default.
• recommends: The recommended dependencies of the project. This will be empty by default.
• suggests: The suggested dependencies of the project. This will be empty by default.
• enhances: A list of packages this package can enhance. This will be empty by default.
• conflicts, breaks, replaces, provides — package transition control.
• extended-description: An extended description of the project — the more detailed the better. Either extended-description-file (see below) or package's readme file is used if it is not provided.
• extended-description-file: A file with extended description of the project. When specified, used if extended-description is not provided.
• revision: An additional version of the Debian package (when the package is updated more often than the project). It defaults to "1", but can be set to an empty string to omit the revision. Can be set via --deb-revision on the command line.
• section: The application category that the software belongs to.
• priority: Defines if the package is required or optional.
• assets: Files to be included in the package and the permissions to assign them. If assets are not specified, they default to ["$auto"], which takes binaries built by Cargo (copied to /usr/bin/) and the package's readme (copied to usr/share/doc/…).
  1. source: the first argument of each asset is the location of that asset in the Rust project. Glob patterns are allowed. Always use target/release/ path prefix for packaging binaries built by Cargo, even if that's not the real path to your target directory. Cargo-deb uses this prefix to detect what to compile, and will replace it with the actual target dir path, taking into account cross-compilation, build profiles, workspaces, CARGO_TARGET_DIR, custom configs, etc. If you try to "fix" the hardcoded target/release paths, you will break cargo-deb, and make it package stale files and mishandle debug info.
  2. dest: the second argument is where the file will be copied. If it starts with usr/lib, it will be changed to usr/lib/$tuple when multiarch option is enabled.
     • If this argument ends with / it will be inferred that the target is the directory where the file will be copied.
     • Otherwise, it will be inferred that the source argument will be renamed when copied.
  3. mode: the third argument is the permissions (octal string) to assign that file. Asset entries can also be defined as a table. When using a table you can optionally override preserve-symlinks. Symlinks can be defined by using a table with the entries dest (as above) and link_name.
• merge-assets: See "Merging Assets" section under "Advanced Usage"
• maintainer-scripts: directory containing templates, preinst, postinst, prerm, or postrm scripts.
• triggers-file: Path to triggers control file for use by the dpkg trigger facility.
• changelog: Path to Debian-formatted changelog file.
• features: List of Cargo features to use when building the package.
• default-features: whether to use default crate features in addition to the features list (default true).
• separate-debug-symbols: whether to keep debug symbols, but strip them from executables and save them in separate files (default false). If it is enabled, then cargo deb --no-separate-debug-symbols can be used to suppress extraction of the debug symbols.
• preserve-symlinks: Whether to preserve symlinks in the asset files (default false).
• systemd-units: Optional configuration settings for automated installation of systemd units.
• conf-files: List of absolute paths of config files outside /etc ["/not-etc/app/config"] that the package management system will not overwrite when the package is upgraded. You still need to list the files in assets to have them packaged. Config files in /etc are treated as configuration files automatically and don't need to be listed here.
• profile: Cargo build profile to use. Defaults to release.

Example of custom Cargo.toml additions

…

Advanced usage

--fast flag uses quicker/lighter compression in the .deb file. Useful for quick deployment of large packages. --dbgsym can also improve speed by making two packages in parallel.

--multiarch=same will use /usr/lib/$debian-target-tuple/ for library paths, allowing library packages for different architectures to co-exist.

[package.metadata.deb.variants.$name]

There can be multiple variants of the metadata in one Cargo.toml file. --variant=name selects the variant to use. Options set in a variant override [package.metadata.deb] options. It automatically appends the variant name to the package name (or you can set the name in the variant).

Separate debug info

To get debug symbols in the package, set in Cargo.toml:

[profile.release]
debug = "line-tables-only"
# or debug = 1 for fatter debug info

Note: building using the dev profile is intentionally unsupported. You can specify other profiles with --profile.

Separate -dbgsym.ddeb package

cargo deb --dbgsym

Removes debug symbols from the executables, and makes a second -dbgsym.ddeb package with only /usr/lib/debug/.build-id/* files. Requires GNU objcopy tool. The .ddeb package is a regular deb package that can be installed together with the base .deb package.

Separate debug files in the same package

cargo deb --separate-debug-symbols --compress-debug-symbols

Removes debug symbols from the executables, and places them in separate files in /usr/lib/debug/.build-id/*. Requires GNU objcopy tool. --compress-debug-symbols makes the debug symbols compressed internally, taking less space on disk.

Merging Assets

When defining a variant it can be useful to also define different assets. If the merge-assets option is used, cargo-deb will merge the list of assets provided to the option with the parent asset list. There are three merging strategies, append, by.dest, and by.src.

• merge-assets.append: Appends this list of assets to the parent list of assets.
• merge-assets.by.dest: Merges this list of assets to the parent list of assets, joining on the destination path. Will replace both the source path and permissions.
• merge-assets.by.src: Merges this list of assets to the parent list of assets, joining on the source path. Will replace both the destination path and permissions.

Note: Using both append, and a by.* option are allowed, w/ the former being applied before the latter.

The special "$auto" entry is not expanded before merging. Explicit paths take precedence over "$auto".

Example of merge-assets

…

[package.metadata.deb.systemd-units]

See systemd integration.

Cross-compilation

cargo deb supports cross-compilation. It can be run from any unix-like host, including macOS, provided that the build environment is set up for cross-compilation:

• The cross-compilation target has to be installed via rustup (e.g. rustup target add i686-unknown-linux-gnu) and has to be installed for the host system (e.g. apt-get install libc6-dev-i386). Note that Rust's and Debian's architecture names are different. See rustc --print target-list for the list of supported values for the --target arguments.
• A Linux-compatible linker and system libraries (e.g. glibc or musl) must be installed and available to Rust/Cargo,
  • dpkg --add-architecture
  • apt-get install pkg-config build-essential crossbuild-essential-
• Cargo must be configured to use a cross-linker.
• Cargo dependencies that use C libraries probably won't work