--- /dev/null
+<!doctype debiandoc system>
+
+<book>
+
+<title>Lintian User's Manual
+<author>Christian Schwarz <email>schwarz@debian.org</email>
+<author>Richard Braakman <email>dark@xs4all.nl</email>
+<author>Sean 'Shaleh' Perry <email>shaleh@debian.org</email>
+<author>Frank Lichtenheld <email>djpig@debian.org</email>
+<author>Contact address: <email>lintian-maint@debian.org</email>
+<version>version 1.23.8, 31 January 2005
+
+<abstract>
+This manual describes Lintian, the Debian package checker.
+</abstract>
+
+<copyright>Copyright © 1998 Christian Schwarz and Richard Braakman
+ Copyright © 2000 Sean 'Shaleh' Perry
+ Copyright © 2004 Frank Lichtenheld
+<p>
+
+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.
+
+<p>
+
+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.
+
+<p>
+
+A copy of the GNU General Public License is available as
+<tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux distribution or on the
+World Wide Web at <url id="http://www.gnu.org/copyleft/gpl.html">.
+You can also obtain it by writing to the Free Software Foundation,
+Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
+
+<p>
+
+<toc sect>
+
+<chapt>Introduction
+
+<p>
+
+<sect>About Lintian
+
+<p>
+
+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.
+
+<p>
+
+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.
+
+<p>
+
+<sect>The intention of Lintian
+
+<p>
+
+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.'
+
+<p>
+
+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.
+
+<p>
+
+Therefore, our policy is <em>not</em> 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.
+
+<p>
+
+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
+<em>implemented</em> 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.)
+
+<p>
+
+Thus, Lintian has the following goals:
+
+<p>
+
+<list compact>
+
+<item> <em>To give us some impression of the `gap' between theory (written
+policy) and praxis (current state of implementation).</em>
+
+<p>
+
+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.)
+
+<p>
+
+<item> <em>To make us re-think about certain aspects of our policy.</em>
+
+<p>
+
+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.
+
+<p>
+
+<item> <em>To show us where to concentrate our efforts in order to make
+Debian a higher quality distribution.</em>
+
+<p>
+
+Most release requirements will be implemented through policy.
+Lintian reports provide an easy way to compare <em>all</em> our packages
+against policy and keep track of the fixing process by watching bug reports.
+Note, that all this can be done <em>automatically</em>.
+
+<p>
+
+<item> <em>To make us avoid making the same mistakes all over again.</em>
+
+<p>
+
+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.
+
+<p>
+
+</list>
+
+<sect>Design issues
+
+<p>
+
+There are three fields of application for Lintian:
+
+<p>
+
+<list compact>
+
+<item> one person could use Lintian to check the whole Debian archive
+and reports bugs,
+
+<p>
+
+<item> each maintainer runs Lintian over her packages before uploading
+them,
+
+<p>
+
+<item> dinstall checks packages which are uploaded to master before
+they are installed in the archive.
+
+<p>
+
+</list>
+
+The authors of Lintian decided to use a very modular design to
+achieve the following goals:
+
+<p>
+
+<list compact>
+
+<item> flexibility: Lintian can be used to check single packages or
+the whole archive and to report and keep track of bug reports, etc.
+
+<p>
+
+<item> completeness: Lintian will eventually include checks for
+(nearly) everything that can be checked mechanically.
+
+<p>
+
+<item> uptodateness: Lintian will be updated whenever policy is
+changed.
+
+<p>
+
+<item> performance: Lintian should make it possible to check single packages
+within seconds or check the full archive within a few hours.
+
+<p>
+
+</list>
+
+<sect>Disclaimer
+
+<p>
+
+Here is a list of important notes on how to use Lintian:
+
+<enumlist>
+
+<item> 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.
+
+<p>
+
+<item> 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) you can do two things: If your package is a bit non-standard and weird in
+this regard, you can install an override. If you think however that the check
+is too easily or outright wrongly triggered, please file a bug on the lintian
+package.
+
+<p>
+
+<item> 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.
+
+<p>
+
+<item> Any feedback about Lintian is welcomed! Please send your
+comments to the lintian maintainers <email/lintian-maint@debian.org/.
+
+<p>
+
+</enumlist>
+
+<chapt>Getting started
+
+<p>
+
+<sect>Installing Lintian
+
+<p>
+
+Before you can start to check your packages with Lintian, you'll have
+to install the <prgn>lintian</prgn> Debian package.
+
+<p>
+
+<sect>Running lintian
+
+<p>
+
+After that, you can run Lintian over any Debian binary, udeb or source packages
+like this:
+
+<p>
+
+<example>
+$ 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
+$
+</example>
+
+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.
+
+<p>
+
+<sect>Lintian Tags
+
+<p>
+
+The first character of each line indicates the type of
+message. Currently, the following types are supported:
+
+<p>
+
+<taglist>
+
+<tag><em>Errors (E)</em>
+<item>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 <tt>-i</tt> option.
+
+<p>
+
+<tag><em>Warnings (W)</em>
+<item>The displayed message might be a policy violation or packaging
+error. A warning is usually an indication that the test is
+known to sometimes produce false positive alarms, because either
+the corresponding rule in policy has many exceptions or the test
+uses some sort of heuristic to find errors.
+
+<p>
+
+<tag><em>Info (I)</em>
+<item>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 <tt>-I</tt> option is set.
+
+<p>
+
+<tag><em>Notes (N)</em>
+<item>The displayed message is a debugging message which
+informs you about the current state of Lintian.
+
+<p>
+
+<tag><em>Experimental (X)</em>
+<item>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.
+
+They are not displayed unless the <tt>-E</tt> option is set.
+<p>
+
+<tag><em>Overridden (O)</em>
+<item>The displayed message indicates a previous
+<em>Warning</em> or <em>Error</em> message which has been
+<em>overridden</em> (see below). They are not displayed unless
+the <tt>--show-overrides</tt> option is set.
+
+<p>
+
+</taglist>
+
+The following parameters after the type indicator tell you about the
+<em>package</em> that has been processed (this can either be a binary or a
+source package) and about the <em>problem</em> that has been
+discovered. The problem is identified by a so-called <em>tag</em> (for
+example, <tt>old-fsf-address-in-copyright-file</tt>).
+
+<p>
+
+Depending on which tag has been reported, the line may contain
+additional arguments which tell you, for example, which files are
+involved.
+
+<p>
+
+If you do not understand what a certain tag is about, you can specify
+the <tt>-i</tt> option when calling Lintian to get a detailed description
+of the reported tags:
+
+<p>
+
+<example>
+$ 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., 51 Franklin St, Fifth Floor, Boston,
+N: MA 02110-1301, USA.
+N:
+[...]
+$
+</example>
+
+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.
+
+<p>
+
+<sect>Overrides
+
+<p>
+
+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.
+
+<p>
+
+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 <tt>-d</tt> (or <tt>--debug</tt>) 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.
+
+<p>
+
+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
+supply a overrides file. If the override is for a binary or udeb
+package, you have to place it at
+<file>/usr/share/lintian/overrides/<package></file> inside the
+package. If the override is for a source package, you have to place
+it at <file>debian/source.lintian-overrides</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 <em>overridden</em>, see above.) Note that
+support for source overrides was added in Lintian version 1.23.0.
+
+<p>
+
+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.
+
+<p>
+
+The format of the overrides file is simple, it consists of one override per
+line (and may contain empty lines and comments, starting with a #, on others):
+<tt>[<package>[ <type>]: ]<lintian-tag>[
+<lintian-info>]</tt>. <tt><package></tt> is the package name;
+<tt><type></tt> is one of <tt>binary</tt>, <tt>udeb</tt> and
+<tt>source</tt>, and <tt><lintian-info></tt> is all additional
+information provided by Lintian except for the tag. What's inside brackets is
+optional and may be omitted if you want to match it all. An example file for
+a binary package would look like:
+
+<example>
+/usr/share/lintian/overrides/foo, where foo is the name of your package
+
+# We use a non-standard dir permission to only allow the webserver to look
+# into this directory:
+foo binary: non-standard-dir-perm
+foo binary: FSSTND-dir-in-usr /usr/man/man1/foo.1.gz
+</example>
+
+<p>
+
+An example file for a source package would look like:
+<example>
+debian/source.lintian-overrides in your base source directory
+foo source: debian-files-list-in-source
+# Upstream distributes it like this, repacking would be overkill though, so
+# tell lintian to not complain:
+foo source: configure-generated-file-in-source config.cache
+</example>
+
+<p>
+
+Many tags can occour more than once (e.g. if the same error is found
+in more than one file). You can override a tag either completly by
+specifying its name (first line in the examples) or only one
+occurrence of it by specifying the additional info, too (second line
+in the examples).
+
+<chapt>Advanced usage
+
+<p>
+
+<sect>How Lintian works
+
+<p>
+
+Lintian is divided into the following layers:
+
+<p>
+
+<taglist>
+
+<tag><em>frontend</em>
+
+<item> the command line interface (currently, this layer consists of
+two scripts, namely <prgn>lintian</prgn> and <prgn>lintian-info</prgn>)
+
+<p>
+
+<tag><em>checkers</em>
+
+<item> a set of scripts that check different aspects of binary or
+source packages
+
+<p>
+
+<tag><em>data collectors</em>
+
+<item> a set of scripts that prepares specific information about a
+package needed by the checker scripts
+
+<p>
+
+<tag><em>unpacking scripts</em>
+
+<item> a set of scripts that unpack binary and source packages and
+extract some basic information about the package contents
+
+<p>
+
+<tag><em>bug reporting scripts</em>
+
+<item> a collection of scripts to report bugs and keep track of them
+afterwards
+
+<p>
+
+</taglist>
+
+When you check a package with Lintian, the following steps are
+performed (not exactly in this order--but the details aren't important
+now):
+
+<p>
+
+<enumlist>
+
+<item> The package contents are unpacked in the <em>laboratory</em> (or
+just <em>lab</em>).
+
+<p>
+
+<item> Some data is collected about the package. (That's done by the
+so-called <em>collector scripts</em>.) For example, the <prgn>file</prgn>
+program is run on each file in the package and the output is saved in the
+<prgn>file-info</prgn> file in the lab.
+
+<p>
+
+<item> The package contents are removed again (to save disk space),
+but the <em>statistics files</em> produced in the last step remain in the
+lab.
+
+<p>
+
+<item> The <em>checker scripts</em> 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.
+
+<p>
+
+<item> Depending on the <em>lab mode</em> Lintian uses (see below), the
+whole lab directory is removed again.
+
+<p>
+
+</enumlist>
+
+This separation of the <em>checker scripts</em> from the <em>unpacking
+tools</em> and the <em>data collector scripts</em> 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).
+
+<p>
+
+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.
+
+<p>
+
+<sect>The laboratory
+
+<p>
+
+Lintian's laboratory directory can be defined via the <em>LINTIAN_LAB</em>
+variable (either in the configuration file or as environment
+variable). If this variable is not defined, Lintian creates a
+temporary lab in <tt>/tmp</tt> which is removed again after Lintian
+has completed its checks. This mode is called <em>temporary lab mode</em>.
+
+<p>
+
+In the <em>static lab mode</em> (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 <tt>-S</tt> (or <tt>--setup-lab</tt>)
+command line option (see also the next section about the distribution
+directory).
+
+<p>
+
+Here is a sketch of the Lintian laboratory:
+
+<example>
+
+ $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)
+
+ udeb/
+ <udeb-pkg-name>/
+ ... (same structure as for binary packages)
+
+ info/
+ binary-packages list of binary packages in archive
+ udeb-packages list of udeb packages in archive
+ source-packages list of source packages in archive
+
+</example>
+
+<sect>Distribution directory
+
+<p>
+
+If you want to check the full Debian distribution with Lintian, you
+have to set up the <tt>LINTIAN_DIST</tt> variable in the configuration
+file (or as environment variable). Then, you have to run <tt>lintian
+-S</tt> 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...)
+
+<p>
+
+After that, you can either check single packages simply be running
+<example>
+ $ lintian foo
+</example>
+(without path or extension for the package <tt>foo</tt>) or check the
+whole distribution with
+<example>
+ $ lintian --all
+</example>
+
+<p>
+
+Since Lintian needs an up-to-date list of packages in the
+distribution, you'll have to rerun the <tt>lintian -S</tt> 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.)
+
+<p>
+
+</book>
projects / maemian / blobdiff