### Install dependencies and clone debcargo-conf Source: https://rust-team.pages.debian.net/book/process-single.html Commands to install the necessary Debian packaging tools and clone the debcargo-conf repository. ```bash $ sudo apt update && sudo apt install cargo rustc dh-cargo debcargo autopkgtest git devscripts quilt reprepro sbuild $ git clone git@salsa.debian.org:rust-team/debcargo-conf.git $ cd debcargo-conf/ ``` -------------------------------- ### Setup environment variables for cargo wrapper in debian/rules Source: https://rust-team.pages.debian.net/book/process-workspace.html This snippet shows how to set up environment variables in debian/rules to use the cargo wrapper from /usr/share/cargo/bin/cargo. It includes including dpkg and rustc architecture makefiles, setting PATH, CARGO, CARGO_HOME, and DEB_CARGO_CRATE. ```makefile include /usr/share/dpkg/default.mk include /usr/share/rustc/architecture.mk export DEB_HOST_RUST_TYPE export DEB_HOST_GNU_TYPE export PATH := /usr/share/cargo/bin:$(PATH) export CARGO=/usr/share/cargo/bin/cargo export CARGO_HOME=$(CURDIR)/debian/cargo_home export DEB_CARGO_CRATE=$(DEB_SOURCE)_$(DEB_VERSION_UPSTREAM) ``` -------------------------------- ### autopkgtest output with failing features Source: https://rust-team.pages.debian.net/book/hacks.html Example autopkgtest output showing that the serde and @ features failed while other features and the package itself passed. Such failing features need to be marked as flaky so the package can migrate to testing. ```text autopkgtest [22:45:42]: test librust-foo-dev:: -----------------------] autopkgtest [22:45:42]: test librust-foo-dev:: - - - - - - - - - - results - - - - - - - - - - librust-foo-dev: PASS autopkgtest [22:45:42]: @@@@@@@@@@@@@@@@@@@@ summary rust-foo:@ FAIL non-zero exit status 101 librust-foo-dev:default PASS librust-foo-dev: PASS librust-foo-dev:serde: FAIL non-zero exit status 101 ``` -------------------------------- ### debian/rules for cargo-c build Source: https://rust-team.pages.debian.net/book/cdylibs.html Example debian/rules for building a C-compatible Rust library with cargo-c. It sets NUMJOBS from DEB_BUILD_OPTIONS, defines CARGO_C_FLAGS with --release, --destdir, --prefix, --libdir, --offline, -v, and -j, and uses dh with the cargo buildsystem. It runs cargo cbuild after dh_auto_build, overrides dh_auto_install to run cargo cinstall, and deletes Cargo.lock files after dh_install. ```makefile #!/usr/bin/make -f include /usr/share/dpkg/architecture.mk ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS))) NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS))) else NUMJOBS = 1 endif CARGO_C_FLAGS = --release \ --destdir=debian/tmp \ --prefix=/usr \ --libdir=/usr/lib/${DEB_HOST_MULTIARCH} \ --offline \ -v \ -j $(NUMJOBS) %: dh $@ --buildsystem cargo execute_after_dh_auto_build: CARGO_HOME=debian/cargo_home \ /usr/share/cargo/bin/cargo cbuild $(CARGO_C_FLAGS) override_dh_auto_install: CARGO_HOME=debian/cargo_home \ /usr/share/cargo/bin/cargo cinstall $(CARGO_C_FLAGS) dh_auto_install execute_after_dh_install: find debian -name Cargo.lock -delete ``` -------------------------------- ### Run release.sh for package uploads Source: https://rust-team.pages.debian.net/book/process-single.html Commands to prepare a package for upload, including targeting specific distributions or using local dependencies. ```bash $ ./release.sh # or $ ./release.sh # as appropriate DISTRO=experimental ./release.sh # to target another distro EXTRA_DEBS=foo.deb ./release.sh # use local dependencies ``` -------------------------------- ### Mark all tests as broken in debcargo.toml Source: https://rust-team.pages.debian.net/book/hacks.html Mark all tests as broken in debcargo.toml when upstream tests require a specific container or setup, or when the crate is only tested with default features. Example: tokio-postgres. ```toml # tests need a postgres container to run [packages.lib] test_is_broken = true ``` -------------------------------- ### Add test dependencies via test_depends in debcargo.toml Source: https://rust-team.pages.debian.net/book/hacks.html Add test dependencies to debcargo.toml when the autopkgtest fails on official runners due to a slightly different setup. This happens very rarely; see cxx for an example. ```toml test_depends = ["foo"] ``` -------------------------------- ### Build a crate for testing Source: https://rust-team.pages.debian.net/book/print.html Use this command to test a crate. Omit the optional parameters in brackets as needed. ```bash cd build && [SOURCEONLY=1] ./build.sh [] ``` -------------------------------- ### Run build.sh for crate builds Source: https://rust-team.pages.debian.net/book/process-single.html Commands to execute build.sh for standard, versioned, or older versions of unversioned packages. ```bash $ ./build.sh $ ./build.sh # for a versioned package $ REALVER= ./build.sh # for older version of unversioned package ``` -------------------------------- ### Disable auto-discovery of tests and examples Source: https://rust-team.pages.debian.net/book/tips.html Disables automatic discovery of tests and examples in the [package] section of Cargo.toml, useful when they are flaky or lack necessary resources. ```toml +autotests = false +autoexamples = false ``` -------------------------------- ### Run dev/chain_build.py Source: https://rust-team.pages.debian.net/book/hacks.html Run the chain_build.py script with a list of dependencies and the target crate. The script builds dependencies in order, and you must solve build failures interactively by pressing enter to continue. ```bash dev/chain_build.py lowest_dep_1 lowest_dep2 lower_dep_1 lower_dep_2 target_crate ``` -------------------------------- ### Whitelist suspicious files in debcargo.toml Source: https://rust-team.pages.debian.net/book/hacks.html Whitelist files that debcargo marks as suspicious, most often C tests for -sys crates. Example: libadwaita-sys. ```toml whitelist = ["tests/foo.c"] ``` -------------------------------- ### Prepare cargo wrapper for packaging usage Source: https://rust-team.pages.debian.net/book/process-workspace.html This snippet shows a debian/rules target that runs 'cargo prepare-debian' to set up a local registry directory and configure the build. It ensures debug symbols, optimization flags, and correct target selection. ```makefile execute_before_dh_auto_configure: /usr/share/cargo/bin/cargo prepare-debian debian/cargo_registry --link-from-system ``` -------------------------------- ### Test a crate with build.sh Source: https://rust-team.pages.debian.net/book/single-conventions.html Run this command from the build directory to test a crate, optionally specifying the old version. The [SOURCEONLY=1] and [] parts are optional and can be omitted as needed. ```bash cd build && [SOURCEONLY=1] ./build.sh [] ``` -------------------------------- ### Mark failing features as broken in debcargo.toml Source: https://rust-team.pages.debian.net/book/hacks.html Mark specific features as broken in debcargo.toml when only some feature tests fail. Do this only if some features fail; if all feature tests fail, read the test logs and look at the upstream test system. Examples: cxx, hashbrown, uom. ```toml #serde and @ feature fail the autopkgtest [packages.lib] test_is_broken = false [packages."lib+@"] test_is_broken = true [packages."lib+serde"] test_is_broken = true ``` -------------------------------- ### Prepare cargo registry for packaging Source: https://rust-team.pages.debian.net/book/print.html Use the cargo wrapper to prepare a local registry directory for the package build, replacing crates.io. ```makefile execute_before_dh_auto_configure: /usr/share/cargo/bin/cargo prepare-debian debian/cargo_registry --link-from-system ``` -------------------------------- ### Build packages with dependency chains Source: https://rust-team.pages.debian.net/book/process-single.html Build packages together by passing local deb files as dependencies to avoid build failures. ```bash $ ( cd build && ./build.sh A ) $ ( cd build && ./build.sh B librust-A*.deb ) ``` -------------------------------- ### Configuring debcargo.toml metadata Source: https://rust-team.pages.debian.net/book/print.html Minimum required content for debcargo.toml, including summary, description, and source section. ```toml summary = "short program summary" description = """ long, exhaustive description of the program. this equals the extended-description line in debian/control for "regular" packages. """ # the section for the application [source] section = "rust" ``` -------------------------------- ### Comment out benchmarks in Cargo.toml Source: https://rust-team.pages.debian.net/book/tips.html Demonstrates the approach of commenting out benchmark configurations in Cargo.toml to disable them. ```toml -[[bench]] -name = "file" -path = "benches/file.rs" +#[[bench]] +#name = "file" +#path = "benches/file.rs" ``` -------------------------------- ### Configure Cargo for local Debian packages Source: https://rust-team.pages.debian.net/book/tips.html Place this configuration in ~/.cargo/config.toml or a project's .cargo/config.toml to force Cargo to use local Debian-provided packages instead of crates.io. ```toml [net] offline = true [source] [source.crates-io] replace-with = "debian" [source.debian] directory = "/usr/share/cargo/registry" ``` -------------------------------- ### Build a package with debcargo-conf Source: https://rust-team.pages.debian.net/book/process-single.html Build the version of a package as currently defined in debcargo-conf. ```bash $ ./repackage.sh ``` -------------------------------- ### Update a crate version Source: https://rust-team.pages.debian.net/book/process-single.html Run the update script for a specific crate and follow the provided instructions. ```bash $ ./update.sh ``` -------------------------------- ### Use EXTRA_DEBS for local dependencies Source: https://rust-team.pages.debian.net/book/process-single.html Pass local deb files as dependencies using the EXTRA_DEBS environment variable. ```bash $ EXTRA_DEBS=librust-A*.deb ./build.sh B $ EXTRA_DEBS=librust-A.deb,librust-B.deb ./build.sh C ``` -------------------------------- ### Manage specific crate versions with REALVER Source: https://rust-team.pages.debian.net/book/process-single.html Prefix scripts with REALVER to maintain an older version of a package than what is currently released on crates.io. ```bash $ REALVER= ./update.sh $ REALVER= ./build.sh $ REALVER= ./release.sh ``` -------------------------------- ### Remove benchmarks in Cargo.toml Source: https://rust-team.pages.debian.net/book/tips.html Demonstrates the approach of removing benchmark configurations entirely from Cargo.toml. ```toml -[[bench]] -name = "file" -path = "benches/file.rs" ``` -------------------------------- ### Set SBUILD_OPTS environment variable Source: https://rust-team.pages.debian.net/book/process-single.html Pass additional options to sbuild by setting the SBUILD_OPTS environment variable. ```bash $ SBUILD_OPTS="--arch=i386" ./build.sh ``` -------------------------------- ### Split out an older crate version Source: https://rust-team.pages.debian.net/book/process-single.html Use this command to split out an older version of a crate when necessary for dependency compatibility. ```bash $ ./update.sh ```