Lintian User's Manual
---------------------
Christian Schwarz <schwarz@debian.org>
Richard Braakman <dark@xs4all.nl>
Sean 'Shaleh' Perry <shaleh@debian.org>
Contact address: <lintian-maint@debian.org>
version 0.3.3, 6 September 2000
-------------------------------------------------------------------------------
Abstract
--------
This manual describes Lintian, the Debian package checker.
Copyright Notice
----------------
Copyright (C)1998 Christian Schwarz and Richard Braakman Copyright
(C)2000 Sean 'Shaleh' Perry
This manual is free software; you may redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.
This is distributed in the hope that it will be useful, but without
any warranty; without even the implied warranty of merchantability or
fitness for a particular purpose. See the GNU General Public License
for more details.
A copy of the GNU General Public License is available as
`/usr/share/common-licenses/GPL' in the Debian GNU/Linux distribution
or on the World Wide Web at http://www.gnu.org/copyleft/gpl.html. You
can also obtain it by writing to the Free Software Foundation, Inc.,
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-------------------------------------------------------------------------------
Contents
--------
1. Introduction
1.1. About Lintian
1.2. The intention of Lintian
1.3. Design issues
1.4. Disclaimer
2. Getting started
2.1. Installing Lintian
2.2. Running lintian
2.3. Lintian Tags
2.4. Overrides
3. Advanced usage
3.1. How Lintian works
3.2. The laboratory
3.3. Distribution directory
-------------------------------------------------------------------------------
1. Introduction
---------------
1.1. About Lintian
------------------
Lintian is a Debian package checker. It can be used to check binary
and source packages for compliance with the Debian policy and for
other common packaging errors.
Lintian uses an archive directory, called laboratory, in which it
stores information about the packages it examines. It can keep this
information between multiple invocations in order to avoid repeating
expensive data-collection operations. It's also possible to check the
complete Debian archive for bugs -- in a timely manner.
1.2. The intention of Lintian
-----------------------------
Packaging has become complicated--not because dpkg is complicated
(indeed, dpkg-deb is very simple to use) but because of the high
requirements of our policy. If a developer releases a new package,
she has to consider hundreds of guidelines to make the package `policy
compliant.'
All parts of our policy have been introduced by the same procedure:
Some developer has a good idea how to make packages more `unique' with
respect to a certain aspect--then the idea is discussed and a policy
proposal is prepared. If we have a consensus about the policy change,
it's introduced in our manuals.
Therefore, our policy is _not_ designed to make life harder for the
maintainers! The intention is to make Debian the best Linux
distribution out there. With this in mind, lots of policy changes are
discussed on the mailing lists each week.
But changing the policy is only a small part of the story: Just having
some statement included in the manual does not make Debian any better.
What's needed is for that policy to become `real life,' i.e., it's
_implemented_ in our packages. And this is where Lintian comes in:
Lintian checks packages and reports possible policy violations. (Of
course, not everything can be checked mechanically -- but a lot of
things can and this is what Lintian is for.)
Thus, Lintian has the following goals:
* _To give us some impression of the `gap' between theory (written
policy) and praxis (current state of implementation)._
From the results of the first two Lintian checks I implemented, I
see that there is a big need to make this gap smaller.
Introducing more policy aspects is worthless unless they are
implemented. We first should fix packages to comply with current
policy before searching for new ways to make policy more
detailed. (Of course, there are also important policy changes
that need to be introduced -- but this is not what's meant here.)
* _To make us re-think about certain aspects of our policy._
For example, it could turn out that some ideas that once sounded
great in theory are hard to implement in all our packages -- in
which case we should rework this aspect of policy.
* _To show us where to concentrate our efforts in order to make
Debian a higher quality distribution._
Most release requirements will be implemented through policy.
Lintian reports provide an easy way to compare _all_ our packages
against policy and keep track of the fixing process by watching
bug reports. Note, that all this can be done _automatically_.
* _To make us avoid making the same mistakes all over again._
Being humans, it's natural for us to make errors. Since we all
have the ability to learn from our mistakes, this is actually no
big problem. Once an important bug is discovered, a Lintian
check could be written to check for exactly this bug. This will
prevent the bug from appearing in any future revisions of any of
our packages.
1.3. Design issues
------------------
There are three fields of application for Lintian:
* one person could use Lintian to check the whole Debian archive
and reports bugs,
* each maintainer runs Lintian over her packages before uploading
them,
* dinstall checks packages which are uploaded to master before they
are installed in the archive.
The authors of Lintian decided to use a very modular design to achieve
the following goals:
* flexibility: Lintian can be used to check single packages or the
whole archive and to report and keep track of bug reports, etc.
* completeness: Lintian will eventually include checks for (nearly)
everything that can be checked mechanically.
* uptodateness: Lintian will be updated whenever policy is changed.
* performance: Lintian should make it possible to check single
packages within seconds or check the full archive within a few
hours.
1.4. Disclaimer
---------------
Here is a list of important notes on how to use Lintian:
1. Lintian is not finished yet and will probably never be. Please
don't use Lintian as a reference for Debian policy. Lintian
might miss a lot of policy violations while it might also report
some violations by mistake. If in doubt, please check out the
policy manuals.
2. The Debian policy gives the maintainers a lot of freedom. In
most cases, the guidelines included in the manuals allow
exceptions. Thus, if Lintian reports a policy violation on a
package and you think this is such an exception (or if you think
Lintian has a bug itself) please contact the authors of Lintian
about this. There is an `override' file which tells Lintian
about policy exceptions.
3. Please DO NOT use Lintian to file bug reports (neither single
ones nor mass bug reports). This is done by the authors of
Lintian already and duplication of efforts and bug reports should
be avoided! If you think a certain bug is `critical', and should
be reported/fixed immediately, please contact the maintainer of
the corresponding package and/or the Lintian maintainers.
4. Any feedback about Lintian is welcomed! Please send your
comments to the lintian maintainers <lintian-maint@debian.org>.
-------------------------------------------------------------------------------
2. Getting started
------------------
2.1. Installing Lintian
-----------------------
Before you can start to check your packages with Lintian, you'll have
to install the `lintian' Debian package. With Lintian version 0.3.0,
you don't need a configuration file in order to check packages.
2.2. Running lintian
--------------------
After that, you can run Lintian over any Debian binary or source
packages like this:
$ lintian libc5_5.4.38-1.deb
E: 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
$
As you can see, Lintian uses a special format for all its error and
warning messages. With that, its very easy to write other programs
which run Lintian and interpret the displayed messages.
2.3. Lintian Tags
-----------------
The first character of each line indicates the type of message.
Currently, the following types are supported:
_Errors (E)_
The displayed message indicates a policy violation or a packaging
error. For policy violations, Lintian will cite the appropriate
policy section when it is invoked with the `-i' option.
_Warnings (W)_
The displayed message might be a policy violation or packaging
error.
_Info (I)_
The displayed message is meant to inform the maintainer about a
certain packaging aspect. Such messages do not usually indicate
errors, but might still be of interest to the curious. They are
not displayed unless the `-I' option is set.
_Notes (N)_
The displayed message is a debugging message which informs you
about the current state of Lintian.
_Experimental (X)_
The displayed message is one of the types listed above, but has
been flagged as `experimental' by the Lintian maintainers. This
means that the code that generates this message is not as well
tested as the rest of Lintian, and might still give surprising
results. Feel free to ignore Experimental messages that do not
seem to make sense, though of course bug reports are always
welcomed.
_Overridden (O)_
The displayed message indicates a previous _Warning_ or _Error_
message which has been _overridden_ (see below).
The following parameters after the type indicator tell you about the
_package_ that has been processed (this can either be a binary or a
source package) and about the _problem_ that has been discovered. The
problem is identified by a so-called _tag_ (for example,
`old-fsf-address-in-copyright-file').
Depending on which tag has been reported, the line may contain
additional arguments which tell you, for example, which files are
involved.
If you do not understand what a certain tag is about, you can specify
the `-i' option when calling Lintian to get a detailed description of
the reported tags:
$ lintian -i libc5_5.4.38-1.deb
E: libc5: old-fsf-address-in-copyright-file
N:
N: The /usr/doc/<pkg>/copyright file refers to the old postal address of
N: the Free Software Foundation (FSF). The new address is:
N:
N: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
N: MA 02111-1307, USA.
N:
[...]
$
In some cases, the messages contain some additional text with a
leading hash character (#). This text should be ignored by any other
programs which interpret Lintian's output because it doesn't follow a
unique format between different messages and it's only meant as
additional information for the maintainer.
2.4. 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: Either, 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' 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
of the authors of Lintian.
In the other two cases (where the error is actually an exception to
policy) 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. Once it has been decided that an override is
needed, you can easily add one by supply a
`/usr/share/lintian/overrides/package' file. 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.)
The format of the overrides file is simple: package: lintian-message.
An example file would look like:
/usr/share/lintian/overrides/foo, where foo is the name of your package
foo: FSSTND-dir-in-usr
foo: non-standard-dir-perm
-------------------------------------------------------------------------------
3. Advanced usage
-----------------
3.1. How Lintian works
----------------------
Lintian is divided into the following layers:
_frontend_
the command line interface (currently, this layer consists of two
scripts, namely `lintian' and `lintian-info')
_checkers_
a set of scripts that check different aspects of binary or source
packages
_data collectors_
a set of scripts that prepares specific information about a
package needed by the checker scripts
_unpacking scripts_
a set of scripts that unpack binary and source packages and
extract some basic information about the package contents
_bug reporting scripts_
a collection of scripts to report bugs and keep track of them
afterwards
When you check a package with Lintian, the following steps are
performed (not exactly in this order--but the details aren't important
now):
1. The package contents are unpacked in the _laboratory_ (or just
_lab_).
2. Some data is collected about the package. (That's done by the
so-called _collector scripts_.) For example, the `file' program
is run on each file in the package and the output is saved in the
`file-info' file in the lab.
3. The package contents are removed again (to save disk space), but
the _statistics files_ produced in the last step remain in the
lab.
4. The _checker scripts_ are run over the package and report any
discovered policy violations or other errors. These scripts
don't access the package contents directly, but use the collected
data as input.
5. Depending on the _lab mode_ Lintian uses (see below), the whole
lab directory is removed again.
This separation of the _checker scripts_ from the _unpacking tools_
and the _data collector scripts_ makes it possible to run Lintian
several times over a package without having to unpack the package each
time. In addition, the checker scripts don't have to worry about
packaging details since they just access the statistics files (not the
package files directly).
Furthermore, since it is sufficient to save the statistics files of
each package in order to run the checks, one can store these files for
all packages of the Debian archive if one wants to check the whole
distribution several times. The space savings is substantial and
continues to grow as the archive does.
3.2. The laboratory
-------------------
Lintian's laboratory directory can be defined via the _LINTIAN_LAB_
variable (either in the configuration file or as environment
variable). If this variable is not defined, Lintian creates a
temporary lab in `/tmp' which is removed again after Lintian has
completed its checks. This mode is called _temporary lab mode_.
In the _static lab mode_ (if the laboratory directory is defined by
the user), the laboratory has to be set up first before it can be used
by Lintian. This can be done with the `-S' (or `--setup-lab') command
line option (see also the next section about the distribution
directory).
Here is a sketch of the Lintian laboratory:
$LINTIAN_LAB/
source/
<src-pkg-name>/
.lintian-status
dsc dsc file
foo.diff.gz
foo.orig.tar.gz (symlinks to actual files)
binary/
<binary 1> -> ../../../binary/<binary 1>
...
unpacked/ (opt., contains unpacked source package)
binary/
<bin-pkg-name>/
.lintian-status
index (output of `dpkg -c')
control-index (same for the control.tar.gz of the pkg)
control/ (contains all control files)
fields/ (contains all control field settings)
source -> ../../source/<source pkg>
deb (symlink to actual file)
unpacked/ (opt., contains unpacked binary package)
info/
binary-packages list of binary packages in archive
source-packages list of source packages in archive
3.3. Distribution directory
---------------------------
If you want to check the full Debian distribution with Lintian, you
have to set up the `LINTIAN_DIST' variable in the configuration file
(or as environment variable). Then, you have to run `lintian -S' to
set up the laboratory and to create lists of all binary and source
packages in the distribution. (Note, that this might take some
time...)
After that, you can either check single packages simply be running
$ lintian foo
(without path or extension for the package `foo') or check the whole
distribution with
$ lintian --all
Since Lintian needs an up-to-date list of packages in the
distribution, you'll have to rerun the `lintian -S' command whenever
the distribution directory has been changed. (But there is no need to
remove the laboratory in this situation: Lintian is smart enough to
only re-unpack packages that have been changed.)
-------------------------------------------------------------------------------
Lintian User's Manual
Christian Schwarz <schwarz@debian.org>
Richard Braakman <dark@xs4all.nl>
Sean 'Shaleh' Perry <shaleh@debian.org>
Contact address: <lintian-maint@debian.org>
version 0.3.3, 6 September 2000