Installing Lintian
Before you can start to check your packages with Lintian, you'll have to
install the lintian Debian package.
Alternatively you can checkout Lintian from the source repository and
use that directly. By setting LINTIAN_ROOT (or using the --root option)
lintian can be run from the source directory as if it had been installed
on your system.
The only known caveat of using Lintian from the source directory is that
Lintian requires a C.UTF-8 (or en_US.UTF-8) locale to correctly process
some files. Lintian 2.5.5 supports using the C.UTF-8 locale from the
libc-bin in Debian Wheezy.
If either your version of libc-bin or Lintian are too old, you can work
around this issue by generating an en_US.UTF-8 locale. Alternatively,
installing a copy of lintian should solve this, as older versions of
Lintian generates a private locale at install time. Note, older versions
of Lintian can only use the en_US.UTF-8 locale.
Running lintian
After that, you can run Lintian on a changes file or any Debian binary,
udeb or source packages like this:
$ lintian libc5_5.4.38-1.deb
W: libc5: old-fsf-address-in-copyright-file
W: libc5: shlib-without-dependency-information usr/lib/libgnumalloc.so.5.4.38
W: libc5: shlib-without-dependency-information lib/libc.so.5.4.38
W: libc5: shlib-without-dependency-information lib/libm.so.5.0.9
E: libc5: shlib-with-executable-bit lib/libc.so.5.4.38 0755
E: libc5: shlib-with-executable-bit lib/libm.so.5.0.9 0755
E: libc5: shlib-missing-in-control-file libgnumalloc usr/lib/libgnumalloc.so.5.4.38
$
Please note that some checks are cross-package checks and can only be
(accurately) performed if the binary packages and the source are
processed together. If Lintian is passed a changes file, it will attempt
to process all packages listed in the changes file.
Lintian supports a number of command line options, which are documented
in the manpage of lintian(1). Some of the options may appear in the
lintianrc file (without the leading dashes) in Lintian 2.5.1 (or newer).
Overrides
In some cases, the checked package does not have a bug or does not
violate policy, but Lintian still reports an error or warning. This can
have the following reasons: Lintian has a bug itself, a specific Lintian
check is not smart enough to know about a special case allowed by
policy, or the policy does allow exceptions to some rule in general.
In the first case (where Lintian has a bug) you should send a bug report
to the Debian bug tracking system and describe which package you
checked, which messages have been displayed, and why you think Lintian
has a bug. Best would be, if you would run Lintian again over your
packages using the -d (or --debug) option, which will cause
Lintian to output much more information (debugging info), and include
these messages in your bug report. This will simplify the debugging
process for the authors of Lintian.
In the other two cases (where the error is actually an exception to
policy), you should probably add an override. If you're unsure though
whether it's indeed a good case for an override, you should contact the
Lintian maintainers too, including the Lintian error message and a short
note, stating why you think this is an exception. This way, the Lintian
maintainers can be sure the problem is not actually a bug in Lintian or
an error in the author's reading of policy. Please do not override bugs
in lintian, they should rather be fixed than overridden.
Once it has been decided that an override is needed, you can easily add
one by supplying an overrides file. If the override is for a binary or
udeb package, you have to place it at
/usr/share/lintian/overrides/<package> inside the package. The tool
dh_lintian from the Debian package debhelper may be useful for this
purpose.
If the override is for a source package, you have to place it at
debian/source/lintian-overrides or
debian/source.lintian-overrides (the former path is preferred). With
that, Lintian will know about this exception and not report the problem
again when checking your package. (Actually, Lintian will report the
problem again, but with type overridden, see above.)
Note that Lintian extracts the override file from the (u)deb and stores
it in the laboratory. The files currently installed on the system are
not used in current Lintian versions.
Documenting overrides
To assist reviewers, Lintian will extract the comments from the
overrides file and display the related comments next to the overridden
tags.
Comments directly above an override will be shown next to all tags it
overrides. If an override for the same tags appears on the very next
line, it will inherit the comment from the override above it.
# This comment will be shown above all tags overridden by the following
# two overrides, (because they apply to the same tag and there is no
# empty line between them)
foo source: some-tag exact match
foo source: some-tag wildcard * match
# This override has its own comment, and it is not shared with the
# override below (because there is an empty line in between them).
foo source: some-tag another exact match
foo source: some-tag override without a comment
Empty lines can be used to disassociate a comment from an override
following it. This can also be used to make a general comment about the
overrides that will not be displayed.
# This is a general comment not connected to any override, since there
# is one (or more) empty lines after it.
foo source: another-tag without any comments
Architecture specific overrides
In rare cases, Lintian tags may be architecture specific. It is possible
to mark overrides architecture specific by using the optional
architecture list.
The architecture list has the same syntax as the architecture list in
the "Build-Depends" field of a source package. This is described in
detail in the Debian Policy Manual
§7.1.
Examples:
# This is an example override that only applies to the i386
# architecture.
foo [i386] binary: some-tag optional-extra
# An architecture wildcard would look like:
foo [any-i386] binary: another-tag optional-extra
# Negation also works
foo [!amd64 !i386] binary: some-random-tag optional-extra
# Negation even works for wildcards
foo [!any-i386] binary: some-tag-not-for-i386 optional-extra
# The package name and the package type is optional, so this
# also works
[linux-any]: tag-only-for-linux optional-extra.
Support for architecture specific overrides was added in Lintian 2.5.0.
Wildcard support was added in 2.5.5. Basic sanity checking was also
added in 2.5.5, where unknown architectures trigger a
malformed-override tag. As does an architecture specific override
for architecture independent packages.
Vendor Profiles
Vendor profiles allows vendors and users to customize Lintian without
having to modify the underlying code. If a profile is not explicitly
given, Lintian will derive the best possible profile for the current
vendor from dpkg-vendor.
Rules for profile names and location
Profile names should only consist of the lower case characters ([a-z]),
underscore (_), dash (-) and forward slashes (/). Particularly note that
dot (.) are specifically not allowed in a profile name.
The default profile for a vendor is called $VENDOR/main. If Lintian
sees a profile name without a slash, it is taken as a short form of the
default profile for a vendor with that name.
The filename for the profile is derived from the name by simply
concatenating it with .profile, Lintian will then look for a file
with that name in the following directories:
- $XDG_DATA_HOME/lintian/profiles
- $HOME/.lintian/profiles
- /etc/lintian/profiles
- $LINTIAN_ROOT/profiles
Note that an implication of the handling of default vendor profiles
implies that profiles must be in subdirectories of the directories above
for Lintian to recognise them.
The directories are checked in the listed order and the first file
matching the profile will be used. This allows users to override a
system profile by putting one with the same filename in
$XDG_DATA_HOME/lintian/profiles or $HOME/.lintian/profiles.
Profile syntax and semantics
Profiles are written in the same syntax as Debian control files as
described in the Debian Policy Manual
§5.1.
Profiles allow comments as described in the Policy Manual.
Main profile paragraph
The fields in the first paragraph are:
- Profile (simple, mandatory)
- Name of the profile.
- Extends (simple, optional)
- Name of the (parent) profile, which this profile extends. Lintian
will recursively process the extended profile before continuing with
processing this profile. In the absence of this field, the profile is
not based on another profile.
- Load-Checks (folded, optional)
Comma-separated list of checks. Lintian will ensure all checks listed
are loaded (allowing tags from them to be enabled or disabled via
Enable-Tags or Disable-Tags).
If a given check was already loaded before this field is processed,
then it is silently ignored. Otherwise, the check is loaded and all
of its tags are disabled (as if it had been listed in
Disable-Tags-From-Check).
This field is most likely only useful if the profile needs to enable
a list of tags from a check in addition to any tags already enabled
from that check (if any).
- Enable-Tags-From-Check (folded, optional)
- Comma-separated list of checks. All tags from each check listed will
be enabled in this profile. The check will be loaded if it wasn't
already.
- Disable-Tags-From-Check (folded, optional)
- Comma-separated list of checks. All tags from each check listed will
be disabled in this profile. The check will be loaded if it wasn't
already.
- Enable-Tags (folded, optional)
- Comma-separated list of tags that should be enabled. It may only list
tags from checks already loaded or listed in one of the following
fields "Load-Checks", "Enable-Tags-From-Check" or
"Disable-Tags-From-Check" in the current profile.
- Disable-Tags (folded, optional)
- Comma-separated list of tags that should be disabled. It may only
list tags from checks already loaded or listed in one of the
following fields "Load-Checks", "Enable-Tags-From-Check" or
"Disable-Tags-From-Check" in the current profile.
The profile is invalid and is rejected, if Enable-Tags and Disable-Tags
lists the same tag twice - even if it is in the same field. This holds
analogously for checks and the three fields Load-Checks,
Enable-Tags-From-Check and Disable-Tags-From-Check.
It is allowed to list a tag in Enable-Tags or Disable-Tags even if the
check that provides this tag is listed in the Disable-Tags-From-Check or
Enable-Tags-From-Check field. In case of conflict, Enable-Tags /
Disable-Tags shall overrule Disable-Tags-From-Check /
Enable-Tags-From-Check within the profile.
Load-Checks, Enable-Tags-From-Check and Disable-Tags-From-Check can be
used to load third-party or vendor specific checks.
It is not an error to load, enable or disable a check or tag that is
already loaded, enabled or disabled respectively (e.g. by a parent
profile).
A profile is invalid if it directly or indirectly extends itself or if
it extends an invalid profile.
By default the tags from the check "lintian" will be loaded as they
assist people in writing and maintaining their overrides file (e.g. by
emitting malformed-override). However, they can be disabled by
explicitly adding the check lintian in the Disable-Tags-From-Check
field.
Tag alteration paragraphs
The fields in the secondary paragraphs are:
- Tags (folded, mandatory)
- Comma separated list of tags affected by this paragraph.
- Overridable (simple, optional)
- Either "Yes" or "No", which decides whether these tags can be
overridden. Lintian will print an informal message if it sees an
override for a tag marked as non-overridable (except if --quiet is
passed).
- Visibility (simple, optional)
The value must be a valid tag visibility other than "classification".
The visibility of the affected tags is set to this value. This cannot
be used on any tag that is defined as a "classification" tag.
Note that experimental is not a visibility.
The paragraph must contain at least one other field than the Tag field.
An example vendor profile
Below is a small example vendor profile for a fictive vendor called
"my-vendor".
# The default profile for "my-vendor"
Profile: my-vendor/main
# It has all the checks and settings from the "debian" profile
Extends: debian/main
# Add checks specific to "my-vendor"
Enable-Tags-From-Check:
my-vendor/some-check,
my-vendor/another-check,
# Disable a tag
Disable-Tags: dir-or-file-in-opt
# Bump visibility of no-md5sums-control-file
# and file-missing-in-md5sums and make them
# non-overridable
Tags: no-md5sums-control-file,
file-missing-in-md5sums,
Visibility: error
Overridable: no
Vendor specific data files
Lintian uses a number of data files for various checks, ranging from
common spelling mistakes to lists of architectures. While some of these
data files are generally applicable for all vendors (or Debian
derivatives), others are not.
Starting with version 2.5.7, Lintian supports vendor specific data
files. This allows vendors to deploy their own data files tailored for
their kind of system. Lintian supports both extending an existing data
file and completely overriding it.
Load paths and order
Lintian will search the following directories in order for vendor
specific data files:
- $XDG_DATA_HOME/lintian/vendors/PROFILENAME/data
- $HOME/.lintian/vendors/PROFILENAME/data
- /etc/lintian/vendors/PROFILENAME/data
- $LINTIAN_ROOT/vendors/PROFILENAME/data
If none of the directories exists or none of them provide the data file
in question, Lintian will (recursively) retry with the parent of the
vendor (if any). If the vendor and none of its parents provide the data
file, Lintian will terminate with an error.
Basic syntax of data files
Generally, data files are read line by line. Leading whitespace of every
line is removed and (now) empty lines are ignored. Lines starting with a
# are comments and are also ignored by the parser. Lines are
processed in the order they are read.
If the first character of the line is a @, the first word is parsed
as a special processing instruction. The rest of the line is a parameter
to that processing instruction. Please refer to List of processing
instructions.
All other lines are read as actual data. If the data file is a table (or
map), the lines will parsed as key-value pairs. If the data file is a
list (or set), the full line will be considered a single value of the
list.
It is permissible to define the same key twice with a different value.
In this case, the value associated with the key is generally redefined.
There are very rare exceptions to this rule, where the data file is a
table of tables (of values). In this case, a recurring key is used to
generate the inner table.
List of processing instructions
The following processing instructions are recognised:
- @delete ENTRY
Removes a single entry denoted by ENTRY that has already been parsed.
It is permissible to list a non-existent entry, in which case the
instruction has no effect. This instruction does not prevent the
entry from being (re-)defined later, it only affects the current
definition of the entry.
For key-pair based data files, ENTRY must match the key. For single
value data files, ENTRY must match the line to remove.
- @include-parent
Processes parent data file of the current data file.
The informal semantics of this instruction is that it reads the
"next" data file in the vendor "chain". The parsing of the parent is
comparable to a C-style include or sourcing a shell script.
More formally, let CP be the name of the vendor profile that defines
the data file containing the instruction. Let the parent of CP be
referred to as PCP.
Lintian will search for the data file provided by PCP using the rules
as specified in Load paths and order. If no data
file is found, Lintian will terminate the parsing with an error.
Thus, this instruction can only be used by profiles that extends
other profiles.