# -*- pod -*-
#
# Use "perldoc doc/README.developers.pod" to read it like a manpage.

=head1 NAME

README.developers.pod -- README file for developers of Lintian

=head1 SYNOPSIS

This document aims to give an overview of the Lintian internals
and is intended for people, who wants to develop or work on Lintian.

For how to use Lintian, please refer to the (other) README, the manual
page lintian(1) or the User Manual.

=head1 DESCRIPTION

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

This document describes how you can contribute to Lintian's
development as well as adapt it to your needs.

Lintian has a large code base which has as its starting point the
directory "bin". This directory holds the "lintian" executable.
This is what gets called when a user calls lintian. This frontend
then calls the lintian checks which run over the Debian package
that Lintian is checking.

=head2 The source code layout

The source code is divided into self-contained groups.  Here is a
quick overview.

=over 4

=item checks

contains the checks and the tag descriptions.

=item collection

contains unpacking scripts

=item data

Symlink to the data set for the Debian vendor profiles.  See entry for
vendors below.

=item debian

contains Debian packaging

=item doc

contains the User Manuals and general docs (see man/ below)

=item bin

contains the frontends (e.g. code installed in /usr/bin)

=item lib

contains Perl modules/library for common tasks.

=item man

contains the manpages for tools in bin/

=item private

various private helpers etc.

=item profiles

contains vendor profiles

=item reporting

tools/code for the lintian.d.o setup

=item t

the new test suite

=item vendors

Per vendor data sets used by checks (and Lintian::Architecture) via
the Lintian::Data API.  Data set is stored in I<vendors/profilename/data>,
where I<profilename> is the "full name" of the profile (e.g. ubuntu/main).

=back

=head2 Core concepts in Lintian

In Lintian there are a number of concepts (or terms), here is a list of the
most important ones:

=over 4

=item Check

A library checking specific aspects of a package, changes file,
etc. which usually can emit multiple tags.

=item Emit (Tag)

Tag that was not suppressed and was triggered.

=item Lab(oratory)

The Laboratory is Lintian's private little play-ground.  When Lintian
is asked to process a package, it will generally unpack (parts of) the
package in the laboratory. The laboratories  expire as soon as Lintian
is done with them, unless the option '--keep-lab' was specified.

Note that the laboratory is usually abbreviated to "Lab".

=item Overridden (Tag)

Tag that was overridden by the maintainer.  Usually it means that the
maintainer believes Lintian misdiagnosed the issue.  In some cases it
is also used for tags that does not handle "corner-cases"

Overridden tags are not displayed by default, but they are still
counted in statistics.  This should not be confused with "Suppressed".

=item Suppressed (Tag)

Tags that are suppressed cannot be emitted.

Note that suppressed tags are ignored by Lintian, so they are not
counted in statistics.  Not to be confused with "Overridden".

=item Tag

Issue reported by Lintian.

=item Test

An internal test of Lintian.

=back

=head2 Useful tricks

There is an extended description of tricks on
L<https://wiki.debian.org/Teams/Lintian/HackersGuide>, but some of them
are also listed here.

=head3 Running lintian from the git repository

Lintian was designed to be run directly from the git repository.  This
allows you to quickly test your changes on a live package.  In Lintian
2.5.18, the frontends will automatically detect when they are being
run from a source checkout and do the right thing.  Earlier versions
need LINTIAN_BASE (or --root).  The following shell snippet can be
used for 2.5.17 and earlier:

 #!/bin/sh
 # ONLY FOR << 2.5.18~ OR EARLIER.  Lintian (>= 2.5.18~) will DTRT.
 LINTIAN_BASE="<INSERT PATH TO LINTIAN GIT DIR>"
 export LINTIAN_BASE
 exec "$LINTIAN_BASE/bin/lintian" "$@"

Beware of two things: If LINTIAN_BASE is not set, Lintian (<< 2.5.18~)
will attempt to use the code from the installed version (in
/usr/share/lintian).

The other issue is that Lintian needs a C.UTF-8 (or an en_US.UTF-8)
locale.  If this is absent, it may trigger some issues with some
(e.g. manpage) checks.  With libc-bin from Wheezy and Lintian 2.5.5,
this is no longer an issue.

=head2 collections and checks

Collections (as the names suggests) are used to extract or/and
structure data from a package.  This data is then used by the checks
(usually via Lintian::Collect API) to examine the package.

The check may be doing the extraction (or structuring) of data itself,
but it should generally be avoided for "heavy" tasks.  Unlike checks,
collections can (and generally are) run in parallel to improve the
effective runtime.

=cut