Debian Rust Team Book

https://rust-team.pages.debian.net/book/
Admin
The Debian Rust Team Book provides packaging policies, workflow processes, guidelines, and tool...
Tokens:27,390
Snippets:244
Trust Score:7
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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 <crate-name>                     # or
$ ./release.sh <crate-name> <old-version>       # as appropriate
DISTRO=experimental ./release.sh <crate-name>   # to target another distro
EXTRA_DEBS=foo.deb ./release.sh <crate-name>    # 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 <crate-name> [<old-version>]
```

--------------------------------

### 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 <crate-name>
$ ./build.sh <crate-name> <version>                # for a versioned package
$ REALVER=<wanted-version> ./build.sh <crate-name> # 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 [<old-version>] parts are optional and can be omitted as needed.

```bash
cd build && [SOURCEONLY=1] ./build.sh <crate-name> [<old-version>]

```

--------------------------------

### 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 <crate-name>
```

--------------------------------

### 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 <crate-name>
```

--------------------------------

### 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=<wanted-version> ./update.sh  <crate-name>
$ REALVER=<wanted-version> ./build.sh   <crate-name>
$ REALVER=<wanted-version> ./release.sh <crate-name>
```

--------------------------------

### 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 <crate-name>
```

--------------------------------

### 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 <crate-name> <old-version>
```
Tokens:
Raw