Package: cargo-deb
Debian packages from Cargo projectsThis is aCargohelper command which automatically creates binaryDebian packages(.deb) from Cargo projects.NoteSince v2.0.0 the deb package version will have a "-1" suffix. You can disable this by adding--deb-revision=""flag orrevision = ""in Cargo metadata. The default suffix is for compliance with Debian's packaging standard.Installationrustupupdate# Debian's Rust is too outdated, use rustup.rscargoinstallcargo-debRequires Rust 1.63+, and optionallydpkg,dpkg-devandliblzma-dev. Compatible with Ubuntu. If the LZMA dependency causes you headaches, trycargo install cargo-deb --no-default-features.If you get a compilation error, runrustup update! If you get an error runningrustup update, uninstall your rust/cargo package, and installthe official Rustinstead.UsagecargodebUpon runningcargo debfrom the base directory of your Rust project, the Debian package will be created intarget/debian/<project_name>_<version>-1_<arch>.deb(or you can change the location with the--outputoption). This package can be installed withdpkg -i target/debian/*.deb.Debug symbols are stripped from the main binary by default, unless[profile.release] debug = trueis set inCargo.toml. Ifcargo deb --separate-debug-symbolsis run, the debug symbols will be packaged as a separate file installed at/usr/lib/debug/<path-to-binary>.debug.cargo deb --installbuilds and installs the project system-wide.ConfigurationNo configuration is necessary to make a basic package from a Cargo project with a binary. This command obtains basic information it needs fromtheCargo.tomlfile. It uses Cargo fields:name,version,license,license-file,description,readme,homepage, andrepository.For a more complete Debian package, you may also define a new table,[package.metadata.deb]that containsmaintainer,copyright,license-file,changelog,depends,conflicts,breaks,replaces,provides,extended-description/extended-description-file,section,priority, andassets.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[package.metadata.deb]optionsEverything 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.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-levellicense-fileis used.depends: The runtimedependenciesof the project. Generated automatically when absent, or if the list includes the$autokeyword.pre-depends: Thepre-dependenciesof the project. This will be empty by default.recommends: The recommendeddependenciesof the project. This will be empty by default.suggests: The suggesteddependenciesof 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 transitioncontrol.extended-description: An extended description of the project — the more detailed the better. Eitherextended-description-file(see below) or package'sreadmefile is used if it is not provided.extended-description-file: A file with extended description of the project. When specified, used ifextended-descriptionis 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.section: Theapplication categorythat the software belongs to.priority: Defines if the package isrequiredoroptional.assets: Files to be included in the package and the permissions to assign them. If assets are not specified, then defaults are taken from binaries listed in[[bin]](copied to/usr/bin/) and packagereadme(copied tousr/share/doc/…).The first argument of each asset is the location of that asset in the Rust project. Glob patterns are allowed. You can usetarget/release/in asset paths, even if Cargo is configured to cross-compile or use customCARGO_TARGET_DIR. The target dir paths will be automatically corrected.The second argument is where the file will be copied.If is 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.The third argument is the permissions (octal string) to assign that file.merge-assets:See "Merging Assets" section under "Advanced Usage"maintainer-scripts: directory containingtemplates,preinst,postinst,prerm, orpostrmscripts.conf-files:List of configuration filesthat the package management system will not overwrite when the package is upgraded.triggers-file: Path to triggers control file for use by the dpkg trigger facility.changelog: Path to Debian-formattedchangelog file.features: List ofCargo featuresto use when building the package.default-features: whether to use default crate features in addition to thefeatureslist (defaulttrue).separate-debug-symbols: whether to keep debug symbols, but strip them from executables and save them in separate files (defaultfalse).preserve-symlinks: Whether to preserve symlinks in the asset files (defaultfalse).systemd-units: Optional configuration settings for automated installation ofsystemd units.Example of customCargo.tomladditions[package.metadata.deb]maintainer="Michael Aaron Murphy <mmstickman@gmail.com>"copyright="2017, Michael Aaron Murphy <mmstickman@gmail.com>"license-file=["LICENSE","4"]extended-description="""\A simple subcommand for the Cargo package manager for \building Debian packages from Rust projects."""depends="$auto"section="utility"priority="optional"assets=[["target/release/cargo-deb","usr/bin/","755"],["README.md","usr/share/doc/cargo-deb/README","644"],]Advanced usageDebian packages can use a number of different compression formats, but the target system may only support of them.
The default format is currently xz, but this may change at any point to support newer formats.
The format can be explicitly specified using the--compress-typecommand-line option. The supported formats are "gzip" and "xz".--fastflag uses lighter compression. Useful for very large packages or quick deployment.--compress-systemforces the use of system command-line tools for data compression.[package.metadata.deb.variants.$name]There can be multiple variants of the metadata in oneCargo.tomlfile.--variant=nameselects the variant to use. Options set in a variant override[package.metadata.deb]options. It automatically adjusts package name.Merging AssetsWhen defining a variant it can be useful to also define a asset merging strategy.If themerge-assetsoption is used,cargo-debwill merge the list of assets provided to the option with the parent asset list. There are three merging strategies,append,by.dest, andby.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 bothappend, and aby.*option are allowed, w/ the former being applied before the latter.Example ofmerge-assets# Example parent asset list
[package.metadata.deb]
assets = [
    # binary
    ["target/release/example", "usr/bin/", "755"],
    # assets
    ["assets/*", "var/lib/example", "644"],
    ["target/release/assets/*", "var/lib/example", "644"],
    ["3.txt", "var/lib/example/3.txt", "644"],
    ["3.txt", "var/lib/example/merged.txt", "644"],
]

# Example merging by appending asset list
[package.metadata.deb.variants.mergeappend]
merge-assets.append = [
    ["4.txt", "var/lib/example/appended/4.txt", "644"]
]

# Example merging by `dest` path
[package.metadata.deb.variants.mergedest]
merge-assets.by.dest = [
    ["4.txt", "var/lib/example/merged.txt", "644"]
]

# Example merging by `src` path
[package.metadata.deb.variants.mergesrc]
merge-assets.by.src = [
    ["3.txt", "var/lib/example/merged-2.txt", "644"]
]

# Example merging by appending and by `src` path
[package.metadata.deb.variants.mergeappendandsrc]
merge-assets.append = [
    ["4.txt", "var/lib/example/appended/4.txt", "644"]
]
merge-assets.by.src = [
    ["3.txt", "var/lib/example/merged-2.txt", "644"]
][package.metadata.deb.systemd-units]See systemd integration.Cross-compilationcargo debsupports 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 beinstalled via rustup(e.g.rustup target add i686-unknown-linux-gnu) and has to beinstalled for the host system(e.g.apt-get install libc6-dev-i386). Note thatRust'sandDebian's architecture namesare different. Seerustc --print target-listfor the list of supported values for the--targetargument.A Linux-compatible linker and system libraries (e.g. glibc or musl) must be installed and available to Rust/Cargo,dpkg --add-architecture <debian architecture name>apt-get install pkg-config build-essential crossbuild-essential-<debian architecture name>Cargo must beconfigured to use a cross-linker.Cargo dependencies that use C libraries probably won't work, unless you install a target's sysroot for pkg-config. SettingPKG_CONFIG_ALLOW_CROSS=1will not help at all, and will only make thingsworse.apt-get install libssl-dev:<debian architecture name>Cargo dependencies that build C code probably won't work, unless you install a C compiler for the target system, and configure appropriateCC_<target>variables.export HOST_CC=gccexport CC_x86_64_unknown_linux_gnu=/usr/bin/x86_64-linux-gnu-gcc(correct the target and paths for your OS)Stripping probably won't work, unless you install versions compatible with the target and configure their paths in.cargo/configby adding[target.<target triple>] strip = { path = "…" } objcopy = { path = "…" }. Alternatively, use--no-strip.Yes, these requiremens are onerous. You can also trycrossorcargo zigbuild, since Zig is way better at cross-compiling, and then runcargo deb --target=… --no-build.cargodeb--target=i686-unknown-linux-gnuCross-compiled archives are saved intarget/<target triple>/debian/*.deb. The actual archive path is printed on success.Note that you can't use cross-compilation to build for an older verison of Debian. If you need to support Debian releases older than the host, consider using a container or a VM, or make a completely static binary for MUSL instead.Separate debug infoTo get debug symbols, set[profile.release] debug = trueinCargo.toml. Building using the dev profile is intentionally unsupported.cargo deb --separate-debug-symbolsRemoves debug symbols from executables and places them as separate files in/usr/lib/debug. Requires GNUobjcopytool.Custom build flagsIf you would like to handle the build process yourself, you can usecargo deb --no-buildso that thecargo-debcommand will not attempt to rebuild your project.cargo deb -- <cargo build flags>Flags after--are passed tocargo build, so you can use options such as-Z,--frozen, and--locked. Please use that only for features thatcargo-debdoesn't support natively.WorkspacesCargo-deb understands workspaces and can build all crates in the workspace if necessary. However, you must choose one crate to be the source of the package metadata. You can select which crate to build with-p crate_nameor--manifest-path=<path/to/Cargo.toml>.Custom version stringscargo deb --deb-version my-custom-versionOverrides the version string generated from the Cargo manifest. It also suppresses therevisionoption.Undefined reference tolzma_stream_encoder_mterrorThis happens when the system-provided LZMA library is too old. Try with a bundled version:cargoinstallcargo-deb--features=static-lzmaor use the xz command-line tool by setting the--compress-systemflag.