mirror of https://gitee.com/openkylin/lintian.git
190 lines
4.9 KiB
Plaintext
190 lines
4.9 KiB
Plaintext
# -*- 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
|
|
|