Scroll to navigation

DEBCARGO-CONF-LINTER(1) User Commands DEBCARGO-CONF-LINTER(1)

NAME

debcargo-conf-linter - check a debcargo-conf repository for packaging mistakes

SYNOPSIS

debcargo-conf-linter [-r root] [--rule rule] [--format full|compact] [--color auto|always|never] [crate...]
debcargo-conf-linter --list-rules
debcargo-conf-linter -h|--help|-V|--version

DESCRIPTION

debcargo-conf-linter is a linter for the debcargo-conf repository, which holds the packaging configuration of the Debian Rust team. Each crate is packaged from a directory root/src/crate/ whose debian/ subdirectory contains the files that debcargo(1) uses to generate the Debian source package.

The linter walks the crate directories under root/src/ and runs a set of rules against each one. Every problem found is reported with a severity, the name of the rule that found it, the file and, where possible, the line and column it refers to.

When no crate arguments are given, every crate directory is checked. Otherwise only the named crates are checked; each crate is a directory name under root/src/.

OPTIONS

Path to the root of the debcargo-conf checkout. The default is the current directory, so running the linter from inside a checkout needs no arguments.
Only run the named rule. May be given multiple times to run several rules. See RULES below, or use --list-rules.
Print the name and a one-line description of each rule, and exit.
Select the output format, see OUTPUT below. format is full (the default) or compact.
When to use colors in the output. when is auto (the default), which uses colors if standard output is a terminal and NO_COLOR is not set; always; or never.
Print a summary of the options (-h) or a longer help text (--help), and exit.
Print the version, and exit.

OUTPUT

Full format

The default format shows each finding in a compiler-like style, with the line it refers to and the part of it that is wrong underlined. When the rule knows how to fix the problem, a help: line suggests it. Findings that are about a whole file show only the path. After the findings, a summary line gives the number of findings per severity. For example:

error[debcargo-toml-schema]: invalid package key `packages."lib.default"`, \
expected `bin`, `lib`, `lib+FEATURE` or `extra+PACKAGE`

--> src/oauth2/debian/debcargo.toml:7:11
| 7 | [packages."lib.default"]
| ^^^^^^^^^^^^^^ warning[patch-removes-platform-deps]: patch removes dependencies for \ targets Debian does not build for (`getrandom`)
--> src/oauth2/debian/patches/relax-deps.diff:9:1
| 9 | -[target."cfg(target_arch = \"wasm32\")".dependencies.getrandom]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: add `filter_targets = ["debian"]` to debian/debcargo.toml instead 2 findings in 1 package: 1 error, 1 warning, 0 info

(Long lines are wrapped here, marked with a backslash; the program does not wrap them.)

Compact format

With --format compact, each finding is printed on one line on standard output, which suits grep(1) and scripts. The summary line is printed on standard error. The format of a line is

path[:line:column]: SEVERITY [rule] message[; help]

where SEVERITY is ERROR, WARN or INFO. For example:

src/oauth2/debian/debcargo.toml:7:11: ERROR [debcargo-toml-schema] \
invalid package key `packages."lib.default"`, expected `bin`, `lib`, \
`lib+FEATURE` or `extra+PACKAGE`

Severity levels

Every finding has one of three severity levels:

The problem must be fixed. Any finding of this level makes the linter exit with status 1.
The configuration is probably wrong, or can be done in a better way, and should be looked at.
Informational; a possible improvement, or a problem that the linter cannot confirm.

In the full format the levels are shown as error, warning and info.

RULES

debcargo-toml-schema (ERROR)

Checks that debian/debcargo.toml is valid TOML and only contains fields that debcargo understands, with values of the right type. The allowed fields mirror Config, SourceOverride and PackageOverride in debcargo's src/config.rs, as documented in debcargo.toml.example. It reports:

  • TOML syntax errors.
  • Unknown fields at the top level, in [source] and in [packages.KEY].
  • Values of the wrong type, for example a string where a boolean or an array of strings is expected.
  • Invalid values in remove_target_types, filter_targets and test_restrictions.
  • Package keys other than bin, lib, lib+FEATURE or extra+PACKAGE.

Crates without a debian/debcargo.toml are skipped.

changelog-syntax (ERROR)

Checks that debian/changelog is a well formed Debian changelog (see deb-changelog(5)), for example that entry headers are well formed, that every entry ends with a correct " -- name <email>  date" trailer line, and that change lines are indented with spaces. Only the first error on each line is reported, because the parser tends to report every following token of a line after an error. Crates without a debian/changelog are skipped.

Checks that debian/copyright is a well formed machine-readable (DEP-5) copyright file. It reports:

  • Copyright files that are still the placeholder debcargo writes when it cannot generate one (fixme fill me in using ./copyright.debcargo.hint as a guide).
  • Files that do not start with a Format: field, including files with leading empty lines.
  • deb822 syntax errors, such as whitespace-only lines, or unindented lines (for example a bare ".") inside a multi-line field.
  • Paragraphs that are neither Files nor stand-alone License paragraphs.
  • Files paragraphs without a Copyright or License field, and files without any Files paragraph.

Only the first syntax error in each paragraph is reported, because one mistake tends to make the parser report many of the following lines of the paragraph too. The Files/License structure is only checked if there are no syntax errors. Crates without a debian/copyright are skipped.

missing-debcargo-hint (WARN, INFO for tests/control)

When the overlay of a crate contains a file that debcargo would otherwise generate, debcargo writes what it would have generated next to it, as file.debcargo.hint. ./update.sh writes it back into src/crate/debian/, and it should be committed, so that maintainers can see what to merge into their hand-written file when upstream or debcargo changes.

This rule reports overlay files without a hint next to them. It checks every file debcargo generates: cargo-checksum.json, control, copyright, rules, source/format, tests/control, upstream/metadata and watch.

debcargo only generates tests/control for crates that have a library. Crates that only have binaries often have a hand-written tests/control without a hint, which cannot be detected from debcargo-conf alone, so a missing tests/control.debcargo.hint is only reported as INFO.

orphaned-debcargo-hint (WARN)

The reverse of missing-debcargo-hint: reports file.debcargo.hint files anywhere under debian/ without the file they are a hint for. Such a hint is left over from an overlay file that was later removed, or from a file debcargo no longer generates (such as compat). Delete the hint, or restore the overlay file.

patch-removes-platform-deps (WARN)

Reports hand-written patches under debian/patches/ that remove dependencies from a Cargo.toml which are only used on Windows, macOS, iOS, Android or WebAssembly, for example:

-[target."cfg(windows)".dependencies.windows-sys]
-version = "0.59"

Instead of patching, add filter_targets = ["debian"] to debian/debcargo.toml. debcargo then generates a patch that removes every target-specific dependency which matches none of the Debian architectures, and keeps doing so for new upstream versions.

Both the [target.X.dependencies.NAME] form and NAME = ... lines inside a [target.X.dependencies] table are recognised, for dependencies, dev-dependencies and build-dependencies. A target is reported if it mentions one of these platforms, and, evaluated the same way as debcargo does, matches none of the Debian architectures:

  • Windows: windows, target_family or target_os = "windows", target_env = "msvc".
  • macOS, iOS and Android: target_os is "macos", "ios" or "android".
  • WebAssembly: target_arch is "wasm32" or "wasm64", target_family = "wasm", target_os is "wasi" or "emscripten".
  • Target triples of any of these platforms, such as x86_64-pc-windows-msvc or wasm32-unknown-unknown.

So for example cfg(not(windows)), cfg(any(unix, windows)) and cfg(not(target_arch = "wasm32")) are not reported, since they also match Linux. Changing such a dependency, for example its version, is not reported; only removing it is. If filter_targets already contains "debian", the finding says that the patch is redundant instead.

patch-removes-benches, patch-removes-examples (WARN)

Report hand-written patches under debian/patches/ that remove [[bench]] or [[example]] targets from a Cargo.toml, for example:

-[[bench]]
-name = "lines"
-path = "benches/lines.rs"
-harness = false

Instead of patching, add remove_target_types = ["bench"] (or ["example"], or both) to debian/debcargo.toml. debcargo then generates a patch that removes all [[bench]] (or [[example]]) tables and sets autobenches (or autoexamples) to false, and keeps doing so for new upstream versions.

The tables in the old and the new version of each hunk are compared, so removals are found even when the diff does not line up with the tables, and targets that are only changed or renamed are not reported. Disabling benches by renaming the header, for example to [[disabled.bench]], counts as removing them. If remove_target_types already contains "bench" (or "example"), the finding says that the patch is redundant instead.

All three patch rules skip the patches debcargo generates itself, in debian/patches/auto/, and the quilt series file.

EXIT STATUS

0
No ERROR findings. Findings of level WARN and INFO do not change the exit status.
1
One or more ERROR findings.
2
Usage error: the root directory cannot be read, or an unknown rule or crate name was given.

ENVIRONMENT

If set to a non-empty value, colors are not used with --color auto.

FILES

For each checked crate, the linter reads these files under root/src/crate/debian/:

The debcargo configuration of the crate.
The Debian changelog.
The machine-readable copyright file.
*.debcargo.hint, and the files debcargo generates
For the missing-debcargo-hint and orphaned-debcargo-hint rules.
The quilt patches, except patches/auto/ and patches/series.

EXAMPLES

Check every crate of a debcargo-conf checkout:

debcargo-conf-linter --root ~/debcargo-conf

From inside the checkout, check two crates only:

debcargo-conf-linter oauth2 tiny

Run only the copyright rule, and page through the colored output:

debcargo-conf-linter --rule copyright-syntax --color always | less -R

List the patches that could be replaced by remove_target_types:

debcargo-conf-linter --format compact \

--rule patch-removes-benches --rule patch-removes-examples \
2>/dev/null | cut -d: -f1

BUGS

deb822-lossless 0.5.20, which parses debian/copyright, mistakes indented continuation lines whose text starts with "#" (for example " # Blue Oak Model License" in a license text written in Markdown) for comments. To avoid false errors, the copyright-syntax rule replaces such a "#" before parsing.

SEE ALSO

debcargo(1), deb-changelog(5), quilt(1)

The debcargo-conf repository: https://salsa.debian.org/rust-team/debcargo-conf

Machine-readable debian/copyright file format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/

AUTHOR

Alexander Kjäll

COPYRIGHT

Copyright © 2026 Alexander Kjäll.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation. There is NO WARRANTY, to the extent permitted by law.

2026-11-01 debcargo-conf-linter 0.1.0