1 <!doctype debiandoc system>
5 <title>Lintian User's Manual
6 <author>Christian Schwarz <email>schwarz@debian.org</email>
7 <author>Richard Braakman <email>dark@xs4all.nl</email>
8 <author>Sean 'Shaleh' Perry <email>shaleh@debian.org</email>
9 <author>Frank Lichtenheld <email>djpig@debian.org</email>
10 <author>Contact address: <email>lintian-maint@debian.org</email>
11 <version>version 1.23.8, 31 January 2005
14 This manual describes Lintian, the Debian package checker.
17 <copyright>Copyright © 1998 Christian Schwarz and Richard Braakman
18 Copyright © 2000 Sean 'Shaleh' Perry
19 Copyright © 2004 Frank Lichtenheld
22 This manual is free software; you may redistribute it and/or
23 modify it under the terms of the GNU General Public License as
24 published by the Free Software Foundation; either version 2, or (at
25 your option) any later version.
29 This is distributed in the hope that it will be useful, but without
30 any warranty; without even the implied warranty of merchantability or
31 fitness for a particular purpose. See the GNU General Public License
36 A copy of the GNU General Public License is available as
37 <tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux distribution or on the
38 World Wide Web at <url id="http://www.gnu.org/copyleft/gpl.html">.
39 You can also obtain it by writing to the Free Software Foundation,
40 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
54 Lintian is a Debian package checker. It can be used to check binary
55 and source packages for compliance with the Debian policy and for
56 other common packaging errors.
60 Lintian uses an archive directory, called laboratory, in which it
61 stores information about the packages it examines. It can keep this
62 information between multiple invocations in order to avoid repeating
63 expensive data-collection operations. It's also possible to check the
64 complete Debian archive for bugs -- in a timely manner.
68 <sect>The intention of Lintian
72 Packaging has become complicated--not because dpkg is complicated
73 (indeed, dpkg-deb is very simple to use) but because of the high
74 requirements of our policy. If a developer releases a new package, she
75 has to consider hundreds of guidelines to make the package `policy
80 All parts of our policy have been introduced by the same procedure:
81 Some developer has a good idea how to make packages more `unique' with
82 respect to a certain aspect--then the idea is discussed and a policy
83 proposal is prepared. If we have a consensus about the policy change,
84 it's introduced in our manuals.
88 Therefore, our policy is <em>not</em> designed to make life harder for the
89 maintainers! The intention is to make Debian the best Linux
90 distribution out there. With this in mind, lots of policy changes are
91 discussed on the mailing lists each week.
95 But changing the policy is only a small part of the story: Just having
96 some statement included in the manual does not make Debian any
97 better. What's needed is for that policy to become `real life,' i.e., it's
98 <em>implemented</em> in our packages. And this is where Lintian comes in:
99 Lintian checks packages and reports possible policy violations. (Of
100 course, not everything can be checked mechanically -- but a lot of
101 things can and this is what Lintian is for.)
105 Thus, Lintian has the following goals:
111 <item> <em>To give us some impression of the `gap' between theory (written
112 policy) and praxis (current state of implementation).</em>
116 From the results of the first two Lintian checks I implemented, I see
117 that there is a big need to make this gap smaller. Introducing more
118 policy aspects is worthless unless they are implemented. We first
119 should fix packages to comply with current policy before searching for
120 new ways to make policy more detailed. (Of course, there are also
121 important policy changes that need to be introduced -- but this is not
126 <item> <em>To make us re-think about certain aspects of our policy.</em>
130 For example, it could turn out that some ideas that once sounded great
131 in theory are hard to implement in all our packages -- in which case
132 we should rework this aspect of policy.
136 <item> <em>To show us where to concentrate our efforts in order to make
137 Debian a higher quality distribution.</em>
141 Most release requirements will be implemented through policy.
142 Lintian reports provide an easy way to compare <em>all</em> our packages
143 against policy and keep track of the fixing process by watching bug reports.
144 Note, that all this can be done <em>automatically</em>.
148 <item> <em>To make us avoid making the same mistakes all over again.</em>
152 Being humans, it's natural for us to make errors. Since we all have
153 the ability to learn from our mistakes, this is actually no big
154 problem. Once an important bug is discovered, a Lintian check could
155 be written to check for exactly this bug. This will prevent the bug from
156 appearing in any future revisions of any of our packages.
166 There are three fields of application for Lintian:
172 <item> one person could use Lintian to check the whole Debian archive
177 <item> each maintainer runs Lintian over her packages before uploading
182 <item> dinstall checks packages which are uploaded to master before
183 they are installed in the archive.
189 The authors of Lintian decided to use a very modular design to
190 achieve the following goals:
196 <item> flexibility: Lintian can be used to check single packages or
197 the whole archive and to report and keep track of bug reports, etc.
201 <item> completeness: Lintian will eventually include checks for
202 (nearly) everything that can be checked mechanically.
206 <item> uptodateness: Lintian will be updated whenever policy is
211 <item> performance: Lintian should make it possible to check single packages
212 within seconds or check the full archive within a few hours.
222 Here is a list of important notes on how to use Lintian:
226 <item> Lintian is not finished yet and will probably never be. Please
227 don't use Lintian as a reference for Debian policy. Lintian might miss
228 a lot of policy violations while it might also report some violations
229 by mistake. If in doubt, please check out the policy manuals.
233 <item> The Debian policy gives the maintainers a lot of freedom. In
234 most cases, the guidelines included in the manuals allow
235 exceptions. Thus, if Lintian reports a policy violation on a package
236 and you think this is such an exception (or if you think Lintian has a
237 bug) you can do two things: If your package is a bit non-standard and weird in
238 this regard, you can install an override. If you think however that the check
239 is too easily or outright wrongly triggered, please file a bug on the lintian
244 <item> Please DO NOT use Lintian to file bug reports (neither single
245 ones nor mass bug reports). This is done by the authors of Lintian already
246 and duplication of efforts and bug reports should be avoided! If you
247 think a certain bug is `critical' and should be reported/fixed immediately,
248 please contact the maintainer of the corresponding package and/or the Lintian
253 <item> Any feedback about Lintian is welcomed! Please send your
254 comments to the lintian maintainers <email/lintian-maint@debian.org/.
260 <chapt>Getting started
264 <sect>Installing Lintian
268 Before you can start to check your packages with Lintian, you'll have
269 to install the <prgn>lintian</prgn> Debian package.
273 <sect>Running lintian
277 After that, you can run Lintian over any Debian binary, udeb or source packages
283 $ lintian libc5_5.4.38-1.deb
284 E: libc5: old-fsf-address-in-copyright-file
285 W: libc5: shlib-without-dependency-information usr/lib/libgnumalloc.so.5.4.38
286 W: libc5: shlib-without-dependency-information lib/libc.so.5.4.38
287 W: libc5: shlib-without-dependency-information lib/libm.so.5.0.9
288 E: libc5: shlib-with-executable-bit lib/libc.so.5.4.38 0755
289 E: libc5: shlib-with-executable-bit lib/libm.so.5.0.9 0755
290 E: libc5: shlib-missing-in-control-file libgnumalloc usr/lib/libgnumalloc.so.5.4.38
294 As you can see, Lintian uses a special format for all its error and
295 warning messages. With that, its very easy to write other programs
296 which run Lintian and interpret the displayed messages.
304 The first character of each line indicates the type of
305 message. Currently, the following types are supported:
311 <tag><em>Errors (E)</em>
312 <item>The displayed message indicates a policy violation or a
313 packaging error. For policy violations, Lintian will cite the
314 appropriate policy section when it is invoked with the <tt>-i</tt> option.
318 <tag><em>Warnings (W)</em>
319 <item>The displayed message might be a policy violation or packaging
320 error. A warning is usually an indication that the test is
321 known to sometimes produce false positive alarms, because either
322 the corresponding rule in policy has many exceptions or the test
323 uses some sort of heuristic to find errors.
327 <tag><em>Info (I)</em>
328 <item>The displayed message is meant to inform the maintainer
329 about a certain packaging aspect. Such messages do not usually
330 indicate errors, but might still be of interest to the curious.
331 They are not displayed unless the <tt>-I</tt> option is set.
335 <tag><em>Notes (N)</em>
336 <item>The displayed message is a debugging message which
337 informs you about the current state of Lintian.
341 <tag><em>Experimental (X)</em>
342 <item>The displayed message is one of the types listed above, but has been
343 flagged as `experimental' by the Lintian maintainers. This means that
344 the code that generates this message is not as well tested as the rest
345 of Lintian, and might still give surprising results. Feel free to
346 ignore Experimental messages that do not seem to make sense, though of
347 course bug reports are always welcomed.
349 They are not displayed unless the <tt>-E</tt> option is set.
352 <tag><em>Overridden (O)</em>
353 <item>The displayed message indicates a previous
354 <em>Warning</em> or <em>Error</em> message which has been
355 <em>overridden</em> (see below). They are not displayed unless
356 the <tt>--show-overrides</tt> option is set.
362 The following parameters after the type indicator tell you about the
363 <em>package</em> that has been processed (this can either be a binary or a
364 source package) and about the <em>problem</em> that has been
365 discovered. The problem is identified by a so-called <em>tag</em> (for
366 example, <tt>old-fsf-address-in-copyright-file</tt>).
370 Depending on which tag has been reported, the line may contain
371 additional arguments which tell you, for example, which files are
376 If you do not understand what a certain tag is about, you can specify
377 the <tt>-i</tt> option when calling Lintian to get a detailed description
378 of the reported tags:
383 $ lintian -i libc5_5.4.38-1.deb
384 E: libc5: old-fsf-address-in-copyright-file
386 N: The /usr/doc/<pkg>/copyright file refers to the old postal address of
387 N: the Free Software Foundation (FSF). The new address is:
389 N: Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
390 N: MA 02110-1301, USA.
396 In some cases, the messages contain some additional text with a
397 leading hash character (#). This text should be ignored by any other
398 programs which interpret Lintian's output because it doesn't follow a
399 unique format between different messages and it's only meant as
400 additional information for the maintainer.
408 In some cases, the checked package does not have a bug or does not
409 violate policy, but Lintian still reports an error or warning. This
410 can have the following reasons: Lintian has a bug itself, a specific Lintian
411 check is not smart enough to know about a special case allowed by policy,
412 or the policy does allow exceptions to some rule in general.
416 In the first case (where Lintian has a bug) you should send a bug
417 report to the Debian bug tracking system and describe which package
418 you checked, which messages have been displayed, and why you think
419 Lintian has a bug. Best would be, if you would run Lintian again over
420 your packages using the <tt>-d</tt> (or <tt>--debug</tt>) option,
421 which will cause Lintian to
422 output much more information (debugging info), and include these
423 messages in your bug report. This will simplify the debugging process
424 for the authors of Lintian.
428 In the other two cases (where the error is actually an exception to
429 policy), you should probably add an override. If you're unsure though whether
430 it's indeed a good case for an override, you should contact the Lintian
431 maintainers too, including the Lintian error message and a short note, stating
432 why you think this is an exception. This way, the Lintian maintainers can be
433 sure the problem is not actually a bug in Lintian or an error in the author's
434 reading of policy. Please do not override bugs in lintian, they should rather
435 be fixed than overridden.
437 Once it has been decided that an override is needed, you can easily add one by
438 supply a overrides file. If the override is for a binary or udeb
439 package, you have to place it at
440 <file>/usr/share/lintian/overrides/<package></file> inside the
441 package. If the override is for a source package, you have to place
442 it at <file>debian/source.lintian-overrides</file>. With that, Lintian
443 will know about this exception and not report the problem again when
444 checking your package. (Actually, Lintian will report the problem
445 again, but with type <em>overridden</em>, see above.) Note that
446 support for source overrides was added in Lintian version 1.23.0.
450 Note that Lintian extracts the override file from the (u)deb and stores
451 it in the laboratory. The files currently installed on the system are
452 not used in current Lintian versions.
456 The format of the overrides file is simple, it consists of one override per
457 line (and may contain empty lines and comments, starting with a #, on others):
458 <tt>[<package>[ <type>]: ]<lintian-tag>[
459 <lintian-info>]</tt>. <tt><package></tt> is the package name;
460 <tt><type></tt> is one of <tt>binary</tt>, <tt>udeb</tt> and
461 <tt>source</tt>, and <tt><lintian-info></tt> is all additional
462 information provided by Lintian except for the tag. What's inside brackets is
463 optional and may be omitted if you want to match it all. An example file for
464 a binary package would look like:
467 /usr/share/lintian/overrides/foo, where foo is the name of your package
469 # We use a non-standard dir permission to only allow the webserver to look
470 # into this directory:
471 foo binary: non-standard-dir-perm
472 foo binary: FSSTND-dir-in-usr /usr/man/man1/foo.1.gz
477 An example file for a source package would look like:
479 debian/source.lintian-overrides in your base source directory
480 foo source: debian-files-list-in-source
481 # Upstream distributes it like this, repacking would be overkill though, so
482 # tell lintian to not complain:
483 foo source: configure-generated-file-in-source config.cache
488 Many tags can occour more than once (e.g. if the same error is found
489 in more than one file). You can override a tag either completly by
490 specifying its name (first line in the examples) or only one
491 occurrence of it by specifying the additional info, too (second line
494 <chapt>Advanced usage
498 <sect>How Lintian works
502 Lintian is divided into the following layers:
508 <tag><em>frontend</em>
510 <item> the command line interface (currently, this layer consists of
511 two scripts, namely <prgn>lintian</prgn> and <prgn>lintian-info</prgn>)
515 <tag><em>checkers</em>
517 <item> a set of scripts that check different aspects of binary or
522 <tag><em>data collectors</em>
524 <item> a set of scripts that prepares specific information about a
525 package needed by the checker scripts
529 <tag><em>unpacking scripts</em>
531 <item> a set of scripts that unpack binary and source packages and
532 extract some basic information about the package contents
536 <tag><em>bug reporting scripts</em>
538 <item> a collection of scripts to report bugs and keep track of them
545 When you check a package with Lintian, the following steps are
546 performed (not exactly in this order--but the details aren't important
553 <item> The package contents are unpacked in the <em>laboratory</em> (or
558 <item> Some data is collected about the package. (That's done by the
559 so-called <em>collector scripts</em>.) For example, the <prgn>file</prgn>
560 program is run on each file in the package and the output is saved in the
561 <prgn>file-info</prgn> file in the lab.
565 <item> The package contents are removed again (to save disk space),
566 but the <em>statistics files</em> produced in the last step remain in the
571 <item> The <em>checker scripts</em> are run over the package and report
572 any discovered policy violations or other errors. These scripts don't
573 access the package contents directly, but use the collected data as
578 <item> Depending on the <em>lab mode</em> Lintian uses (see below), the
579 whole lab directory is removed again.
585 This separation of the <em>checker scripts</em> from the <em>unpacking
586 tools</em> and the <em>data collector scripts</em> makes it possible to run
587 Lintian several times over a package without having to unpack the
588 package each time. In addition, the checker scripts don't have to
589 worry about packaging details since they just access the statistics
590 files (not the package files directly).
594 Furthermore, since it is sufficient to save the statistics files of
595 each package in order to run the checks, one can store these files for
596 all packages of the Debian archive if one wants to check the whole
597 distribution several times. The space savings is substantial and continues
598 to grow as the archive does.
606 Lintian's laboratory directory can be defined via the <em>LINTIAN_LAB</em>
607 variable (either in the configuration file or as environment
608 variable). If this variable is not defined, Lintian creates a
609 temporary lab in <tt>/tmp</tt> which is removed again after Lintian
610 has completed its checks. This mode is called <em>temporary lab mode</em>.
614 In the <em>static lab mode</em> (if the laboratory directory is defined by
615 the user), the laboratory has to be set up first before it can be used
616 by Lintian. This can be done with the <tt>-S</tt> (or <tt>--setup-lab</tt>)
617 command line option (see also the next section about the distribution
622 Here is a sketch of the Lintian laboratory:
629 <src-pkg-name>/
633 foo.orig.tar.gz (symlinks to actual files)
635 <binary 1> -> ../../../binary/<binary 1>
637 unpacked/ (opt., contains unpacked source package)
640 <bin-pkg-name>/
642 index (output of `dpkg -c')
643 control-index (same for the control.tar.gz of the pkg)
644 control/ (contains all control files)
645 fields/ (contains all control field settings)
646 source -> ../../source/<source pkg>
647 deb (symlink to actual file)
648 unpacked/ (opt., contains unpacked binary package)
651 <udeb-pkg-name>/
652 ... (same structure as for binary packages)
655 binary-packages list of binary packages in archive
656 udeb-packages list of udeb packages in archive
657 source-packages list of source packages in archive
661 <sect>Distribution directory
665 If you want to check the full Debian distribution with Lintian, you
666 have to set up the <tt>LINTIAN_DIST</tt> variable in the configuration
667 file (or as environment variable). Then, you have to run <tt>lintian
668 -S</tt> to set up the laboratory and to create lists of all binary and
669 source packages in the distribution. (Note, that this might take some
674 After that, you can either check single packages simply be running
678 (without path or extension for the package <tt>foo</tt>) or check the
679 whole distribution with
686 Since Lintian needs an up-to-date list of packages in the
687 distribution, you'll have to rerun the <tt>lintian -S</tt> command
688 whenever the distribution directory has been changed. (But there is no
689 need to remove the laboratory in this situation: Lintian is smart
690 enough to only re-unpack packages that have been changed.)