Fixing problems

Whichever process is followed, some problems and the way to solve them are similar. After getting familiar with the process(es), this section describes them.

The documents on each process describe problems and solutions unique to them.

Unsatisfiable dependencies

When there are unsatisfiable dependencies, dpkg-checkbuilddeps will fail. It might be missing dependencies, version mismatches, or both.

For missing dependencies, check if they are mandatory. If so, package them first. If optional, and functionalities requiring them are less than important, they could be temporarily disabled to ease initial packaging. See how to disable them.

For version mismatches, first check if simply relaxing the version constraints would do:

Sometimes it's a patch or minor level version too high, e.g. when dependency foo 1.2.3 is required, while we only have 1.2.1 on Debian. This is the simplest case; just patch the version constraint to be 1.2.1, or even simpler, 1.2.
Sometimes it's a major version mismatch, e.g. foo 2 is required but only 1 is in Debian. In this case, first check if patching it to use foo 1 would work. If so, just go with that; if not, try downgrading it. If that's too hard, try upgrading foo to 2. Sometimes it's the other way around: foo 1 is required but 2 is in Debian. Then there's one more option: asking upstream to upgrade.
If the last point didn't work, you can probably consider splitting out a versioned package. But ask the team before doing so.

Note: major version changes usually mean a transition, which needs coordination in and sometimes out of the team, unless affected are few and it's easy to migrate all of them in sync.

Update dependencies

In some cases, old versions of some dependencies are still used. To limit the number of duplicated libraries in the archive, please try to evaluate if a newer version of the dependencies could be used.

This is done by patching Cargo.toml to use the newer version.

Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds with no further source changes, then change the required version in Cargo.toml from 0.3 to >= 0.3, < 0.6 or something like that. Then the convention is to put all these changes into a single patch called relax-deps.patch.

OTOH, if the cargo build fails, and you can fix it by editing the source code in a minor way to use the new crate API, then for each crate that needs to be updated, you should instead name the patch relax-dep-<crate>.patch, and add changes of both the relevant entry in Cargo.toml and the source code to it. The change to Cargo.toml should then simply say, for the above example, 0.5, since the older versions in the range >= 0.3, < 0.6 won't work.

If you want to make a crate work with an older dependency version than listed in Cargo.toml (for example 0.3 instead of 0.5), you can use a flexible version requirement like >= 0.3, < 0.6 iff that range is satisfied by the unversioned (latest) package of that crate. If the latest packaged version is too new, and your dependency needs to be satisifed by a semver-suffixed package, you need to depend on that specific semver version.

Failing patches

As upstream releases new versions, patches become out of date and fail to apply. You should refresh/update applicable patches, drop outdated/obsolete ones, introduce new ones as failures occur.

There are several ways to manage patches: quilt, gbp-pq, etc. In workspace process, the maintainer is free to use any they see fit. In single crate process, due to its monorepo nature, and the particular way files are organized, options are limited. See the process document for details.

Breaking changes due to changed version

When a dependency is patched to upgrade or downgrade, there are likely breaking changes. Consult docs of the corresponding dependency, including docs.rs (https://docs.rs/<crate>/<version>) and their changelogs (some maintain a CHANGELOG.md in the repo, some record in GitHub Releases notes).

Test failures

Sometimes, tests require extra tweaks and settings to work. Edit the corresponding test definitions. For single crate process, this means copying build/<crate>/debian/tests/control over to src/<crate>/debian/tests/.

Sometimes, the tests fail, due to missing test data/fixtures, no network access in buildds or debci runners, feature combinations not considered by upstream, etc. You can patch them out: see General tips.

Alternatively, for (1) the tests can be disabled by running dh_auto_test -- build instead of dh_auto_test -- test --all in debian/rules, and for (2) they can be marked broken ("flaky"). They are still run by autopkgtest, but their failing is no longer considered an error.

For workspace process, add Restriction: flaky to the test case.

For single crate process, add this to debcargo.toml:

[packages."lib+feature"] ## --no-default-features --features feature
test_is_broken = true

[packages.lib] # --no-default-features
test_is_broken = true

[packages."lib+@"] # --all-features
test_is_broken = true

Note that marking packages.lib.test_is_broken = true (i.e. --no-default-features) will transitively disable tests for all combinations of features. Sometimes this is correct e.g. if the test actually breaks for all features. Sometimes this is not correct, e.g. if the test only breaks for --no-default-features. In the latter case you should instead patch the crate to ignore those tests when the relevant features are absent.

Debug info & backtrace

Sometimes, the error messages are not the most informative. In this case you can try re-running the command with RUST_BACKTRACE=1.

If you are following the single crate process, and using the debcargo from Debian's own repositories, you should also install the debcargo-dbgsym package, which includes debug symbols for debcargo. Otherwise backtraces of itself could be less useful. Make sure you have the debug repository enabled in your apt sources.

Keyboard shortcuts