# Copyright 2010 Niels Thykier
#  - based on the work Richard Braakman and Christian
#    Schwarz (copyrighted 1998).
#
# This manual page is free software.  It is distributed under the
# terms of the GNU General Public License as published by the Free
# Software Foundation; either version 2 of the License, or (at your
# option) any later version.
#
# This manual page 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.
#
# You should have received a copy of the GNU General Public License
# along with this manual page; if not, write to the Free Software
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
# USA
#

=head1 NAME

lintian - Static analysis tool for Debian packages

=head1 SYNOPSIS

B<lintian> [I<action>] [I<options>] [I<packages>] ...

=head1 DESCRIPTION

Lintian dissects Debian packages and reports bugs and policy
violations.  It contains automated checks for many aspects of Debian
policy as well as some checks for common errors.

It uses an archive directory, called I<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.

There are three ways to specify binary, udeb or source packages for
Lintian to process: by file name (the .deb file for a binary package
or the .dsc file for a source package), by naming a I<.changes> file,
or by using a lab query (see L</LAB QUERY> below).

If you specify a I<.changes> file, Lintian will process all packages
listed in that file.  This is convenient when checking a new package
before uploading it.

If you specify packages to be checked or use one of the options
B<--all>, B<--packages-from-file> or B<--packages-file>, the packages
requested will be processed.  Otherwise, if I<debian/changelog>
exists, it is parsed to determine the name of the .changes file to
look for in the parent directory (when using the actions B<--check> or
B<--unpack>).  See L</CHECKING LAST BUILD> for more information.


=head1 OPTIONS

Actions of the lintian command: (Only one action can be specified per invocation)

=over 4

=item B<-c>, B<--check>

Run all checks over the specified packages.  This is the default action.

=item B<-C> chk1,chk2,..., B<--check-part> chk1,chk2,...

Run only the specified checks.  You can either specify the name of the
check script or the abbreviation.  For details, see the L</CHECKS> section
below.

=item B<-F>, B<--ftp-master-rejects>

Run only the checks that issue tags that result in automatic rejects
from the Debian upload queue.  The list of such tags is refreshed with
each Lintian release, so may be slightly out of date if it has changed
recently.

This is implemented via a profile and thus this option cannot be used
together with B<--profile>.

=item B<-r>, B<--remove>

Removed the specified packages from the lintian lab.  This is only
useful with static labs.

=item B<-R>, B<--remove-lab>

Remove the laboratory directory.  This is only useful with static
labs.

=item B<-S>, B<--setup-lab>

Set up or update a static lintian laboratory.

=item B<-T> tag1,tag2,..., B<--tags> tag1,tag2,...

Run only the checks that issue the requested tags.  The tests for
other tags within the check scripts will be run but the tags will not
be issued.

With this options all tags listed will be displayed regardless of the
display settings.

=item B<--tags-from-file> filename

Same functionality as B<--tags>, but read the list of tags from a
file.  Blank lines and lines beginning with # are ignored.  All other
lines are taken to be tag names or comma-separated lists of tag names
to (potentially) issue.

With this options all tags listed will be displayed regardless of the
display settings.

=item B<-u>, B<--unpack>

Unpacks the package will all collections.  See the L</COLLECTION>
section below.

Note in this option will also run all collections.  See the
L</COLLECTION> section below.

=item B<-X> chk1,chk2,..., B<--dont-check-part> chk1,chk2,...

Run all but the the specified checks.  You can either specify the name
of the check script or the abbreviation.  For details, see the
L</CHECKS> section below.

=back

General options:

=over 4

=item B<-d>, B<--debug>

Display debugging messages. (Implies B<-v> and overrules any B<-q>).

Can be used multiple times to increase the debug information.  If
passed twice or more, Lintian will emit approximate run times for
collections and checks (if L<Time::HiRes> can be loaded).

This option cannot be specified in the config file.  If used on the
command line it will override the B<verbose> and the B<quiet> options
in the config file.

=item B<-h>, B<--help>

Display usage information and exit.

=item B<-q>, B<--quiet>

Suppress all informational messages including override comments
(normally shown with B<--show-overrides>).

This option is silently ignored if B<--debug> is given.  Otherwise, if
both B<--verbose> and B<--quiet> is used, the last of these two options
take effect.

This option overrides the B<verbose> and the B<quiet> variable in the
configuration file.  In the configuration file, this option is enabled
by using B<quiet> variable.  The B<verbose> and B<quiet> variables may
not both appear in the config file.

=item B<-v>, B<--verbose>

Display verbose messages.

If B<--debug> is used this option is always enabled.  Otherwise, if
both B<--verbose> and B<--quiet> is used (and B<--debug> is not used),
the last of these two options take effect.

This option overrides the B<quiet> variable in the configuration file.
In the configuration file, this option is enabled by using B<verbose>
variable.  The B<verbose> and B<quiet> variables may not both appear
in the config file.

=item B<-V>, B<--version>

Display lintian version number and exit.

=item B<--print-version>

Print unadorned version number and exit.

=back

Behaviour options for B<lintian>.

=over 4

=item B<--allow-root>

Override lintian's warning when it is run with superuser privileges.

=item B<--color> (never|always|auto|html)

Whether to colorize tags in lintian output based on their severity.
The default is "never", which never uses color.  "always" will always
use color, "auto" will use color only if the output is going to a
terminal, and "html" will use HTML E<lt>spanE<gt> tags with a color style
attribute (instead of ANSI color escape sequences).

This option overrides the B<color> variable in the configuration file.

=item B<--display-source> X

Only display tags from the source X (e.g. the Policy Manual or the
Developer Reference).  This option can be used multiple times to
add additional sources.  Example sources are "policy" or "devref"
being the Policy Manual and the Developer Reference (respectively).

The entire list of sources can be found in
I<$LINTIAN_ROOT/data/output/manual-references>

=item B<-E>, B<--display-experimental>

Display experimental ("X:") tags as well.  They are normally
suppressed.

If a tag is marked experimental, 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 (particularly if they include fixes).

This option overrides the B<display-experimental> variable in the
configuration file.

=item B<--fail-on-warnings>

By default, B<lintian> exits with 0 status if only warnings were
found.  If this flag is given, exit with a status of 1 if either
warnings or errors are found.

This option overrides the B<fail-on-warnings> variable in the
configuration file.

=item B<-i>, B<--info>

Print explanatory information about each problem discovered in
addition to the lintian error tags. To print a long tag description
without running lintian, see L<lintian-info(1)>.

This option overrides B<info> variable in the configuration file.

=item B<-I>, B<--display-info>

Display informational ("I:") tags as well.  They are normally
suppressed.  (This is equivalent to B<-L> ">=wishlist").

This option overrides the B<display-info> variable in the
configuration file.

Note: B<display-level> and B<display-info> may not both appear in the
configuration file.

=item B<--keep-lab>

By default, temporary labs will be removed after lintian is finished.
Specifying this options will leave the lab behind, which might be
useful for debugging purposes.  You can find out where the temporary
lab is located by running lintian with the B<--verbose> option.

For static (non-temporary) labs this option causes Lintian to skip
the automatic clean up of some collections.

=item B<-L> [+|-|=][>=|>|<|<=][S|C|S/C], B<--display-level> [+|-|=][>=|>|<|<=][S|C|S/C]

Fine-grained selection of tags to be displayed. It is possible to add,
remove or set the levels to display, specifying a severity (S:
serious, important, normal, minor, wishlist, pedantic), a certainty
(C: certain, possible, wild-guess), or both (S/C).  The default
settings are equivalent to B<-L> ">=important" B<-L>
"+>=normal/possible" B<-L> +minor/certain).

This option overrides the B<display-level> variable in the
configuration file.  The value of the B<display-level> in
configuration file should be space separated entries in the same
format as passed via command-line.

Note: B<display-level> may not be used with B<display-info> or B<pedantic>
in the configuration file.

=item B<-m>, B<--md5sums>, B<--checksums>

This has become redundant in lintian 2.5.1 and may be removed in a
later release.

This option used to control whether Lintian would verify checksums
in changes files.  As of 2.5.1, Lintian always does this.

=item B<-o>, B<--no-override>

Don't use the overrides file.

This option overrides the B<override> variable in the configuration
file.

=item B<--pedantic>

Display pedantic ("P:") tags as well.  They are normally suppressed.

Pedantic tags are Lintian at its most pickiest and include checks for
particular Debian packaging styles and checks that many people
disagree with.  Expect false positives and Lintian tags that you don't
consider useful if you use this option.  Adding overrides for pedantic
tags is probably not worth the effort.

This option overrides the B<pedantic> variable in the configuration
file.

Note: B<pedantic> and B<display-info> may not both appear in the
configuration file.

=item B<--profile> vendor[/prof]

Use the profile from vendor (or the profile with that name).  If the
profile name does not contain a slash, the default profile for than
vendor is chosen.

If not specified, B<lintian> loads the best profile for the current
vendor.

Please Refer to the Lintian User Manual for the full documentation of
profiles.

=item B<--show-overrides>

Output tags that have been overridden.  The related override comments
will also be printed (unless --quiet is used).  Please refer to the
Lintian User Manual for the documentation on how lintian relates
comments to a given override.

This option overrides the B<show-overrides> variable in the
configuration file.

=item B<--suppress-tags> tag1,tag2,...

Suppress the listed tags.  They will not be reported if they occur and
will not affect the exit status of Lintian.

=item B<--suppress-tags-from-file> file

Suppress all tags listed in the given file.  Blank lines and lines
beginning with # are ignored.  All other lines are taken to be tag
names or comma-separated lists of tag names to suppress.  The
suppressed tags will not be reported if they occur and will not affect
the exit status of Lintian.

=item B<-U> info1,info2,..., B<--unpack-info> info1,info2,...

Collect information info1, info2, etc. even if these are not required
by the checks.  Collections requested by this option are also not
auto-removed (in this run).

This option is mostly useful for debugging or special purpose setups.

It is allowed to give this option more than once.  The following
two lines of arguments are semantically equivalent:

 -U info1 -U info2
 -U info1,info2

=back

Configuration options:

=over 4

=item B<--arch> arch

Deprecated, does nothing and may be removed in a later release.

=item B<--area> area

Deprecated, does nothing and may be removed in a later release.

=item B<--archivedir> archivedir

Deprecated, does nothing and may be removed in a later release.

=item B<--cfg> configfile

Read the configuration from configfile rather than the default
locations.  This option overrides the B<LINTIAN_CFG> environment
variable.

=item B<--no-cfg>

Do not read any configuration file.  This option overrides the
B<--cfg> above.

=item B<--dist> distdir

Deprecated, does nothing and may be removed in a later release.

=item B<--section> area

Deprecated, does nothing and may be removed in a later release.

=item B<--lab> labdir

Use labdir as the permanent laboratory.  This is where Lintian keeps
information about the packages it checks.  This option overrides the
B<LINTIAN_LAB> environment variable and the configuration file entry
of the same name.

=item B<-j> X, B<--jobs> X

Limit the number of unpacking jobs Lintian will run in parallel.

This option overrides the B<jobs> variable in the configuration file.

By default Lintian will use I<nproc> to determine a reasonable default
(or 2, if the nproc fails).

=item B<--root> rootdir

Look for B<lintian>'s support files (such as check scripts and
collection scripts) in rootdir.  This overrides the B<LINTIAN_ROOT>
environment variable.  The default location is I</usr/share/lintian>.

=back

Package selection options:

=over 4

=item B<-a>, B<--all>

Check all packages in the laboratory.

Note: If B<--binary>, B<--udeb> or B<--source> is specified, then only
packages of that type is considered.

=item B<-b>, B<--binary>

The lab-queries listed on the command line are by default binary
packages.

With B<--all> this means check all binary packages in the lab.

=item B<-p> X, B<--packages-file> X

Process all packages which are listed in file X.  Each package has to
be listed in a single line using the following format:

B<type> B<package> B<version> B<file>

where B<type> is either `b', `u', or `s' (binary, udeb, or source
package), B<package> is the package name, B<version> is the package's
version, and B<file> is the package file name (absolute path
specification).

Please note this has been deprecated in favour B<--packages-from-file>,
which does not require a weird/special syntax.

=item B<--packages-from-file> X

Process the packages listed in X.  If the line starts with "!query:",
then the rest of that line is processed as a lab query (see L</LAB QUERY>).

Otherwise the line is read as the path to a file to process (all
whitespace is included!).

If X is "-", Lintian will read the packages from STDIN.

=item B<-s>, B<--source>

The lab-queries listed on the command line are by default source
packages.

With B<--all> this means check all source packages in the lab.

The following packages listed on the command line are source packages.

=item B<--udeb>

The lab-queries listed on the command line are by default udeb
packages.

With B<--all> this means check all udeb packages in the lab.

=back

=head1 CHECKS

@CHECKS@

=head1 COLLECTION

@COLLECTION@

=head1 FILES

Lintian looks for its configuration file in the following locations:

The file name given with the --cfg option

=over 4

=item I<$LINTIAN_CFG>

=item I<$LINTIAN_ROOT/lintianrc>

=item I<$HOME/.lintianrc>

=item I</etc/lintianrc>

=back

Lintian uses the following directories:

=over 4

=item I</tmp>

If no lab location is specified via the LINTIAN_LAB environment
variable, configuration, or the B<--lab> command-line option, lintian
defaults to creating a temporary lab directory in I</tmp>.  To change
the directory used, set the TMPDIR environment variable to a suitable
directory.  TMPDIR can be set in the configuration file.

=item I</usr/share/lintian/checks>

Scripts that check aspects of a package.

=item I</usr/share/lintian/collection>

Scripts that collect information about a package and store it for use
by the check scripts.

=item I</usr/share/lintian/data>

Supporting data used by Lintian checks and for output formatting.

=item I</usr/share/lintian/lib>

Utility scripts used by the other lintian scripts.

=item I</usr/share/lintian/unpack>

Scripts that manage the I<laboratory>.

=back

The I</usr/share/lintian> directory can be overridden with the
B<LINTIAN_ROOT> environment variable or the B<--root> option.

For binary packages, Lintian looks for overrides in a file named
I<usr/share/lintian/overrides/E<lt>packageE<gt>> inside the binary
package, where I<E<lt>packageE<gt>> is the name of the binary
package.  For source packages, Lintian looks for overrides in
I<debian/source/lintian-overrides> and then in
I<debian/source.lintian-overrides> if the first file is not found.
The first path is preferred.  See the Lintian User's Manual for the
syntax of overrides.

=head1 CONFIGURATION FILE

The configuration file can be used to specify default values for some
options.  The general format is:

 option = value

All whitespace adjacent to the "=" sign as well as leading and
trailing whitespace is ignored.  However whitespace within the
value is respected, as demonstrated by this example:

 # Parsed as "opt1" with value "val1"
    opt1    =   val1
 # Parsed as "opt2" with value "val2.1  val2.2     val2.3"
 opt2 = val2.1  val2.2     val2.3

Unless otherwise specified, no option may appear more than once.
Lintian will ignore empty lines or lines starting with the
B<#>-character.

Generally options will be the long form of the command-line option
without the leading dashes.  There some exceptions (such as
--profile), where Lintian uses the same name as the environment
variable.

Lintian only allows a subset of the options specified in the
configuration file; please refer to the individual options in
L</OPTIONS>.

In the configuration file, all options listed must have a value, even
if they do not accept a value on command line (e.g. --pedantic).  The
values "yes", "y", "1", or "true" will enable such a option and "no",
"n", "0" or "false" will disable it.  Prior to the 2.5.2 release,
these values were case sensitive.

For other options, they generally take the same values as they do on
the command line.  Though some options allow a slightly different
format (e.g. --display-level).  These exceptions are explained for the
relevant options in L</OPTIONS>.

Beyond command line options, it is also allowed to specify the
environment variable "TMPDIR" in the configuration file.

A sample configuration file could look like:

 # Sample configuration file for lintian
 #
 # Set the default profile (--profile)
 LINTIAN_PROFILE = debian
 
 # Set the default TMPDIR for lintian to /var/tmp/lintian
 # - useful if /tmp is tmpfs with "limited" size.
 TMPDIR = /var/tmp/lintian/
 
 # Show info (I:) tags by default (--display-info)
 #  NB: this cannot be used with display-level
 display-info=yes
 
 # Ignore all overrides (--no-override)
 #  NB: called "overrides" in the config file
 #      and has inverted value!
 overrides = no
 
 # Automatically determine if color should be used
 color = auto

=head1 EXIT STATUS

=over 4

=item B<0>

No policy violations or major errors detected.
(There may have been warnings, though.)

=item B<1>

Policy violations or major errors detected.

=item B<2>

Lintian run-time error. An error message is sent to stderr.

=back

=head1 LAB QUERY

A lab query can be used to refer to a (set of) package(s) in the
Lintian Laboratory.  The general format of a query is:

 [type:]package[/version[/arch]]

Where:

=over 4

=item type

This is the type of the package and (if present) must be one of "ALL",
"GROUP", "binary", "udeb", "source" or "changes".  This is case
sensitive.

If omitted this defaults to "ALL" unless another default has been
specified (see B<--binary>, B<--udeb> or B<--source>).  The pseudo
type "ALL" acts as a wildcard for any real package type.

The special type "GROUP" can be used to match all packages related to
a given source package.  For more info, please see L<Group query>
below.

=item package

This is the name of the package.  This is mandatory and must match
exactly.

=item version

This is the version of the package, if left out (or if it is "_") then
any version will do.  Otherwise the version must match exactly.

=item arch

This is the architecture of the package, if left out (or it is "_")
then any architecture will do.  Otherwise the architecture must match
exactly.

Note: This is I<completely> ignored when matching against source
packages or when type is "GROUP".

Note: For changes packages, this must match the contents of the
architecture field in the changes.  This field may contain a space
(e.g. "source all") and therefore may also need proper shell escape.

=back

=head2 Group query

A group query can be used to (re-)process all packages in a given
group.  The I<package> and I<version> part will be used to look up one
or more source packages.  The binaries, udebs and changes files for
each matching source package will also be activated.

=head1 CHECKING LAST BUILD

When run in an unpacked package dir (with no package selection
arguments), Lintian will use I<debian/changelog> to determine the
source and version of the package.  Lintian will then attempt to find
a matching I<.changes> file for this source and version combination.

Lintian will (in order) search the following directories:

=over 4

=item ..

Used by dpkg-buildpackage(1).

=item ../build-area

Used by svn-buildpackage(1).

=item /var/cache/pbuilder/result

Used by pbuilder(1) and cowbuilder(1).

=back

In each directory, Lintian will attempt to find a I<.changes> file
using the following values as architectecture (in order):

=over 4

=item I<$DEB_BUILD_ARCH>

The environment variable DEB_BUILD_ARCH.

=item I<$DEB_HOST_ARCH> (or I<dpkg --print-architecture>)

The environment variable DEB_HOST_ARCH (if not set, "dpkg
--print-architecture" will be used instead)

=item I<dpkg --print-foreign-architectures>

If dpkg(1) appears to support multi-arch, then any architecture listed
by "dpkg --print-foreign-architectures" will be used (in the order
returned by dpkg).

=item I<multi>

Pseudo architecture used by mergechanges(1).

=item I<all>

Used when building architecture indep packages only (e.g
dpkg-buildpackage -A).

=item I<source>

Used for "source only" builds (e.g. dpkg-buildpackage -S).

=back

If a I<.changes> file matches any combination above exists, Lintian
will process the first match as if you had passed it per command line.
If no I<.changes> file can be found, Lintian will print a list of attempted
locations on STDERR and exit 0.

=head1 EXAMPLES

=over 4

=item B<$ lintian foo.changes>

Check the changes file itself and any (binary, udeb or source) package
listed in it.

=item B<$ lintian foo.deb>

Check binary package foo given by foo.deb.

=item B<$ lintian foo.dsc>

Check source package foo given by foo.dsc.

=item B<$ lintian foo.dsc -L +minor/possible>

Check source package foo given by foo.dsc, including minor/possible
tags.

=item B<$ lintian -i foo.changes>

Check the changes file and, if listed, the source and binary package
of the upload. The output will contain detailed information about the
reported tags.

=item B<$ lintian -c --binary foo>

Check the binary package foo in the Lintian laboratory.

=item B<$ lintian -C cpy --source foo>

Run the copyright checks on source package foo.  The package foo must
be in the Lintian laboratory.

=item B<$ lintian -u foo -U unpacked>

Unpack all packages named foo in the Lintian laboratory.

=item B<$ lintian -r foo>

Remove all packages named foo from the Lintian laboratory.

=item B<$ lintian>

Assuming I<debian/changelog> exists, look for a changes file for the
source in the parent dir.  Otherwise, print usage information and
exit.

=back

=head1 BUGS

Lintian does not have any locking mechanisms yet.  (Running several
Lintian processes on the same laboratory simultaneously is likely to fail
or corrupt the laboratory.)

If you discover any other bugs in lintian, please contact the authors.

=head1 SEE ALSO

L<lintian-info(1)>, Lintian User Manual
(file:/usr/share/doc/lintian/lintian.html/index.html)

Packaging tools: L<debhelper(7)>, L<dh_make(8)>,
L<dpkg-buildpackage(1)>.

=head1 AUTHORS

Niels Thykier <niels@thykier.net>

Richard Braakman <dark@xs4all.nl>

Christian Schwarz <schwarz@monet.m.isar.de>

Please use the email address <lintian-maint@debian.org> for
Lintian related comments.

=cut


