diff options
Diffstat (limited to 'doc/lintian.rst')
| -rw-r--r-- | doc/lintian.rst | 992 |
1 files changed, 992 insertions, 0 deletions
diff --git a/doc/lintian.rst b/doc/lintian.rst new file mode 100644 index 0000000..7fe6d18 --- /dev/null +++ b/doc/lintian.rst @@ -0,0 +1,992 @@ +===================== +Lintian User's Manual +===================== +.. sectnum:: +.. contents:: + :depth: 3 + +.. _chapter-1: + +Introduction +============ + +.. _section-1.1: + +About Lintian +------------- + +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. + +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. + +.. _section-1.2: + +The intention of Lintian +------------------------ + +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.' + +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. + +Therefore, our policy is *not* 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. + +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 +*implemented* 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.) + +Thus, Lintian has the following goals: + +- *To give us some impression of the \`gap' between theory (written + policy) and praxis (current state of implementation).* + + 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.) + +- *To make us re-think about certain aspects of our policy.* + + 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. + +- *To show us where to concentrate our efforts in order to make Debian + a higher quality distribution.* + + Most release requirements will be implemented through policy. Lintian + reports provide an easy way to compare *all* our packages against + policy and keep track of the fixing process by watching bug reports. + Note, that all this can be done *automatically*. + +- *To make us avoid making the same mistakes all over again.* + + 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. + +.. _section-1.3: + +Design issues +------------- + +There are three fields of application for Lintian: + +- one person could use Lintian to check the whole Debian archive and + reports bugs, + +- each maintainer runs Lintian over her packages before uploading them, + +- dinstall checks packages which are uploaded to master before they are + installed in the archive. + +The authors of Lintian decided to use a very modular design to achieve +the following goals: + +- flexibility: Lintian can be used to check single packages or the + whole archive and to report and keep track of bug reports, etc. + +- completeness: Lintian will eventually include checks for (nearly) + everything that can be checked mechanically. + +- uptodateness: Lintian will be updated whenever policy is changed. + +- performance: Lintian should make it possible to check single packages + within seconds or check the full archive within 5 days. + +The design also has a number of constrains that limits the things +Lintian can check for and what tools it can use: + +- static analysis: The code in a package may be analyzed, but it should + *never* be executed. However, Lintian can (and does) use external + tools to analyze files in the package. + +- deterministic replay-ability: Checks should not rely on the state of + system caches or even the system time. These things makes it harder + for others to reproduce (the absence of) tags. + +- same source analysis: Lintian checks packages in small isolated + groups based on the source package. Requiring the presence of all the + dependencies to provide the full results make it harder to run + lintian (not to mention, it makes "deterministic replay-ability" a + lot harder as well). + +.. _section-1.4: + +Disclaimer +---------- + +Here is a list of important notes on how to use Lintian: + +1. 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. + +2. 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. + +3. 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. + +4. Any feedback about Lintian is welcome! Please send your comments to + the lintian maintainers lintian-maint@debian.org. + +.. _chapter-2: + +Getting started +=============== + +.. _section-2.1: + +Installing Lintian +------------------ + +Before you can start to check your packages with Lintian, you'll have to +install the lintian Debian package. + +Alternatively you can checkout Lintian from the source repository and +use that directly. By setting LINTIAN_BASE (or using the --root option) +lintian can be run from the source directory as if it had been installed +on your system. + +The only known caveat of using Lintian from the source directory is that +Lintian requires a C.UTF-8 (or en_US.UTF-8) locale to correctly process +some files. (Is that still true?) + +.. _section-2.2: + +Running lintian +--------------- + +After that, you can run Lintian on a changes file or any Debian binary, +udeb or source packages like this: + +:: + + $ lintian etm_3.2.30-1.1_all.deb + E: etm: appstream-metadata-legacy-format [usr/share/appdata/etm.appdata.xml] + W: etm: appstream-metadata-in-legacy-location [usr/share/appdata/etm.appdata.xml] + I: etm: package-contains-documentation-outside-usr-share-doc [usr/share/etm/etmTk/help/UserManual.html] + $ + +Please note that some checks are cross-package checks and can only be +(accurately) performed if the binary packages and the source are +processed together. If Lintian is passed a changes file, it will attempt +to process all packages listed in the changes file. + +Lintian supports a number of command line options, which are documented +in the manpage of lintian(1). Some of the options may appear in the +lintianrc file without leading dashes. + +.. _section-2.3: + +Lintian Tags +------------ + +Lintian uses a special format for all its error and warning messages. +With that it is very easy to write other programs which run Lintian and +interpret the displayed messages. + +The first character of each line indicates the type of message. +Currently, the following types are supported: + +*Errors (E)* + 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 ``-i`` option. + +*Warnings (W)* + The displayed message might be a policy violation or packaging error. + A warning is usually an indication that the check is known to + sometimes produce false positive alarms, because either the + corresponding rule in policy has many exceptions or the check uses + some sort of heuristic to find errors. + +*Info (I)* + 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 ``-I`` option is set. + +*Notes (N)* + The displayed message is a debugging message which informs you about + the current state of Lintian. + +*Experimental (X)* + 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 welcome. They are not + displayed unless the ``-E`` option is set. + +*Overridden (O)* + The displayed message indicates a previous *Warning* or *Error* + message which has been *overridden* (see below). They are not + displayed unless the ``--show-overrides`` option is set. + +*Pedantic (P)* + The displayed message indicates a message of Lintian at its most + pickiest and include checks for particular Debian packaging styles, + checks that are very frequently wrong, and checks that many people + disagree with. They are not displayed unless the ``--pedantic`` + option is set. + +The type indicator is followed by the name of the package and for +non-binary packages the type of the package. Then comes the *problem* +that was discovered, also known as a *tag* (for example, +``old-fsf-address-in-copyright-file``). + +Depending on which tag has been reported, the line may contain +additional arguments which tell you, for example, which files are +involved. + +If you do not understand what a certain tag is about, you can specify +the ``-i`` option when calling Lintian to get a detailed description of +the reported tags: + +:: + + $ lintian --info --tags appstream-metadata-in-legacy-location etm_3.2.30-1.1_all.deb + N: + W: etm: appstream-metadata-in-legacy-location [usr/share/appdata/etm.appdata.xml] + N: + N: AppStream metadata file was found in /usr/share/appdata/. The AppStream XML files should be placed in /usr/share/metainfo/. + N: + N: Please refer to https://wiki.debian.org/AppStream/Guidelines for details. + N: + N: Visibility: warning + N: Show-Always: no + N: Check: appstream-metadata + N: + $ + +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. + +.. _section-2.4: + +Overrides +--------- + +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. + +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 ``-d`` (or ``--debug``) 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. + +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 supplying an overrides file. If the override is for a binary or +udeb package, you have to place it at +``/usr/share/lintian/overrides/<package>`` inside the package. The tool +``dh_lintian`` from the Debian package debhelper may be useful for this +purpose. + +If the override is for a source package, you have to place it at +``debian/source/lintian-overrides`` or +``debian/source.lintian-overrides`` (the former path is preferred). 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 *overridden*, see above.) + +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. + +.. _section-2.4.1: + +Format of override files +~~~~~~~~~~~~~~~~~~~~~~~~ + +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): ``[[<package>][ <archlist>][ <type>]: ]<lintian-tag>[ +[*]<context>[*]]``. <package> is the package name; +<archlist> is an architecture list (see Architecture specific overrides +for more info); <type> is one of ``binary``, ``udeb`` and ``source``, +and <context> 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. Additionally, if the context of +the tag contains paths to files in the package, they're enclosed with +literal brackets (so called "pointed hints") so that tools which +process lintian tags can link to the according file and potentially +even line in the file. + +An example file for a binary package would look like: + +:: + + /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] + +An example file for a source package would look like: + +:: + + 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] + +Many tags can occur more than once (e.g. if the same error is found in +more than one file). You can override a tag either completely 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). If you add an asterisk (``*``) in the additional info, this +will match arbitrary strings similar to the shell wildcard. For example: + +:: + + # Multiple files need to be covered by the override + source-is-missing [apidoc/html/*.js] + +.. _section-2.4.2: + +Documenting overrides +~~~~~~~~~~~~~~~~~~~~~ + +To assist reviewers, Lintian will extract the comments from the +overrides file and display the related comments next to the overridden +tags. + +Comments directly above an override will be shown next to all tags it +overrides. If an override for the same tags appears on the very next +line, it will inherit the comment from the override above it. + +:: + + # This comment will be shown above all tags overridden by the following + # two overrides, (because they apply to the same tag and there is no + # empty line between them) + foo source: some-tag exact match + foo source: some-tag wildcard * match + # This override has its own comment, and it is not shared with the + # override below (because there is an empty line in between them). + foo source: some-tag another exact match + + foo source: some-tag override without a comment + +Empty lines can be used to disassociate a comment from an override +following it. This can also be used to make a general comment about the +overrides that will not be displayed. + +:: + + # This is a general comment not connected to any override, since there + # is one (or more) empty lines after it. + + foo source: another-tag without any comments + +.. _section-2.4.3: + +Architecture specific overrides +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In rare cases, Lintian tags may be architecture specific. It is possible +to mark overrides architecture specific by using the optional +architecture list. + +The architecture list has the same syntax as the architecture list in +the "Build-Depends" field of a source package. This is described in +detail in the `Debian Policy Manual +§7.1 <https://www.debian.org/doc/debian-policy/#s-controlsyntax>`__. +Examples: + +:: + + # This is an example override that only applies to the i386 + # architecture. + foo [i386] binary: some-tag optional-extra + + # An architecture wildcard would look like: + foo [any-i386] binary: another-tag optional-extra + + # Negation also works + foo [!amd64 !i386] binary: some-random-tag optional-extra + + # Negation even works for wildcards + foo [!any-i386] binary: some-tag-not-for-i386 optional-extra + + # The package name and the package type is optional, so this + # also works + [linux-any]: tag-only-for-linux optional-extra. + +An unknown architecture will trigger a packaging hint. So will an +architecture-specific override in an architecture-independent +installable. + +.. _section-2.5: + +Vendor Profiles +--------------- + +Vendor profiles allows vendors and users to customize Lintian without +having to modify the underlying code. If a profile is not explicitly +given, Lintian will derive the best possible profile for the current +vendor from dpkg-vendor. + +.. _section-2.5.1: + +Rules for profile names and location +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Profile names should only consist of the lower case characters ([a-z]), +underscore (_), dash (-) and forward slashes (/). Particularly note that +dot (.) are specifically *not* allowed in a profile name. + +The default profile for a vendor is called ``$VENDOR/main``. If Lintian +sees a profile name without a slash, it is taken as a short form of the +default profile for a vendor with that name. + +The filename for the profile is derived from the name by simply +concatenating it with ``.profile``, Lintian will then look for a file +with that name in the following directories: + +- ``$XDG_DATA_HOME/lintian/profiles`` + +- ``$HOME/.lintian/profiles`` + +- ``/etc/lintian/profiles`` + +- ``$LINTIAN_BASE/profiles`` + +Note that an implication of the handling of default vendor profiles +implies that profiles must be in subdirectories of the directories above +for Lintian to recognise them. + +The directories are checked in the listed order and the first file +matching the profile will be used. This allows users to override a +system profile by putting one with the same filename in +``$XDG_DATA_HOME/lintian/profiles`` or ``$HOME/.lintian/profiles``. + +.. _section-2.5.2: + +Profile syntax and semantics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Profiles are written in the same syntax as Debian control files as +described in the `Debian Policy Manual +§5.1 <https://www.debian.org/doc/debian-policy/#s-controlsyntax>`__. +Profiles allow comments as described in the Policy Manual. + +.. _section-2.5.2.1: + +Main profile paragraph +^^^^^^^^^^^^^^^^^^^^^^ + +The fields in the first paragraph are: + +*Profile* (simple, mandatory) + Name of the profile. + +*Extends* (simple, optional) + Name of the (parent) profile, which this profile extends. Lintian + will recursively process the extended profile before continuing with + processing this profile. In the absence of this field, the profile is + not based on another profile. + +*Load-Checks* (folded, optional) + Comma-separated list of checks. Lintian will ensure all checks listed + are loaded (allowing tags from them to be enabled or disabled via + Enable-Tags or Disable-Tags). + + If a given check was already loaded before this field is processed, + then it is silently ignored. Otherwise, the check is loaded and all + of its tags are disabled (as if it had been listed in + Disable-Tags-From-Check). + + This field is most likely only useful if the profile needs to enable + a list of tags from a check in addition to any tags already enabled + from that check (if any). + +*Enable-Tags-From-Check* (folded, optional) + Comma-separated list of checks. All tags from each check listed will + be enabled in this profile. The check will be loaded if it wasn't + already. + +*Disable-Tags-From-Check* (folded, optional) + Comma-separated list of checks. All tags from each check listed will + be disabled in this profile. The check will be loaded if it wasn't + already. + +*Enable-Tags* (folded, optional) + Comma-separated list of tags that should be enabled. It may only list + tags from checks already loaded or listed in one of the following + fields "Load-Checks", "Enable-Tags-From-Check" or + "Disable-Tags-From-Check" in the current profile. + +*Disable-Tags* (folded, optional) + Comma-separated list of tags that should be disabled. It may only + list tags from checks already loaded or listed in one of the + following fields "Load-Checks", "Enable-Tags-From-Check" or + "Disable-Tags-From-Check" in the current profile. + +The profile is invalid and is rejected, if Enable-Tags and Disable-Tags +lists the same tag twice - even if it is in the same field. This holds +analogously for checks and the three fields Load-Checks, +Enable-Tags-From-Check and Disable-Tags-From-Check. + +It is allowed to list a tag in Enable-Tags or Disable-Tags even if the +check that provides this tag is listed in the Disable-Tags-From-Check or +Enable-Tags-From-Check field. In case of conflict, Enable-Tags / +Disable-Tags shall overrule Disable-Tags-From-Check / +Enable-Tags-From-Check within the profile. + +Load-Checks, Enable-Tags-From-Check and Disable-Tags-From-Check can be +used to load third-party or vendor specific checks. + +It is not an error to load, enable or disable a check or tag that is +already loaded, enabled or disabled respectively (e.g. by a parent +profile). + +A profile is invalid if it directly or indirectly extends itself or if +it extends an invalid profile. + +By default the tags from the check "lintian" will be loaded as they +assist people in writing and maintaining their overrides file (e.g. by +emitting ``malformed-override``). However, they can be disabled by +explicitly adding the check ``lintian`` in the Disable-Tags-From-Check +field. + +.. _section-2.5.2.2: + +Tag alteration paragraphs +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The fields in the secondary paragraphs are: + +*Tags* (folded, mandatory) + Comma separated list of tags affected by this paragraph. + +*Overridable* (simple, optional) + Either "Yes" or "No", which decides whether these tags can be + overridden. Lintian will print an informal message if it sees an + override for a tag marked as non-overridable (except if --quiet is + passed). + +*Visibility* (simple, optional) + The value must be a valid tag visibility other than "classification". + The visibility of the affected tags is set to this value. This cannot + be used on any tag that is defined as a "classification" tag. + + Note that *experimental* is not a visibility. + +The paragraph must contain at least one other field than the Tag field. + +.. _section-2.5.2.3: + +An example vendor profile +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Below is a small example vendor profile for a fictive vendor called +"my-vendor". + +:: + + # The default profile for "my-vendor" + Profile: my-vendor/main + # It has all the checks and settings from the "debian" profile + Extends: debian/main + # Add checks specific to "my-vendor" + Enable-Tags-From-Check: + my-vendor/some-check, + my-vendor/another-check, + # Disable a tag + Disable-Tags: dir-or-file-in-opt + + # Bump visibility of no-md5sums-control-file + # and file-missing-in-md5sums and make them + # non-overridable + Tags: no-md5sums-control-file, + file-missing-in-md5sums, + Visibility: error + Overridable: no + +.. _section-2.6: + +Vendor specific data files +-------------------------- + +Lintian uses a number of data files for various checks, ranging from +common spelling mistakes to lists of architectures. While some of these +data files are generally applicable for all vendors (or Debian +derivatives), others are not. + +Lintian supports vendor specific data files. This allows vendors to deploy +their own data files tailored for their kind of system. Lintian supports +both extending an existing data file and completely overriding it. + +.. _section-2.6.1: + +Load paths and order +~~~~~~~~~~~~~~~~~~~~ + +Lintian will search the following directories in order for vendor +specific data files: + +- ``$XDG_DATA_HOME/lintian/vendors/PROFILENAME/data`` + +- ``$HOME/.lintian/vendors/PROFILENAME/data`` + +- ``/etc/lintian/vendors/PROFILENAME/data`` + +- ``$LINTIAN_BASE/vendors/PROFILENAME/data`` + +If none of the directories exists or none of them provide the data file +in question, Lintian will (recursively) retry with the parent of the +vendor (if any). If the vendor and none of its parents provide the data +file, Lintian will terminate with an error. + +.. _section-2.6.2: + +Basic syntax of data files +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Generally, data files are read line by line. Leading whitespace of every +line is removed and (now) empty lines are ignored. Lines starting with a +``#`` are comments and are also ignored by the parser. Lines are +processed in the order they are read. + +If the first character of the line is a ``@``, the first word is parsed +as a special processing instruction. The rest of the line is a parameter +to that processing instruction. Please refer to `List of processing +instructions <#section-2.6.2.1>`__. + +All other lines are read as actual data. If the data file is a table (or +map), the lines will parsed as key-value pairs. If the data file is a +list (or set), the full line will be considered a single value of the +list. + +It is permissible to define the same key twice with a different value. +In this case, the value associated with the key is generally redefined. +There are very rare exceptions to this rule, where the data file is a +table of tables (of values). In this case, a recurring key is used to +generate the inner table. + +.. _section-2.6.2.1: + +List of processing instructions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following processing instructions are recognised: + +*@delete ENTRY* + Removes a single entry denoted by ENTRY that has already been parsed. + + It is permissible to list a non-existent entry, in which case the + instruction has no effect. This instruction does *not* prevent the + entry from being (re-)defined later, it only affects the current + definition of the entry. + + For key-pair based data files, ENTRY must match the key. For single + value data files, ENTRY must match the line to remove. + +*@include-parent* + Processes parent data file of the current data file. + + The informal semantics of this instruction is that it reads the + "next" data file in the vendor "chain". The parsing of the parent is + comparable to a C-style include or sourcing a shell script. + + More formally, let CP be the name of the vendor profile that defines + the data file containing the instruction. Let the parent of CP be + referred to as PCP. + + Lintian will search for the data file provided by PCP using the rules + as specified in `Load paths and order <#section-2.6.1>`__. If no data + file is found, Lintian will terminate the parsing with an error. + Thus, this instruction can only be used by profiles that extends + other profiles. + +.. _chapter-3: + +Advanced usage +============== + +.. _section-3.1: + +How Lintian works +----------------- + +Lintian is divided into the following layers: + +*frontend* + the command line interface (currently, this layer consists of the + ``lintian`` program. + +*checks* + a set of modules that check different aspects of packages. + +*data collectors* + a set of scripts that prepares specific information about a package + needed by the check modules + +When you check a package with Lintian, the following steps are performed +(not exactly in this order—but the details aren't important now): + +1. An entry is created for the package in the *laboratory* (or just + *lab*). + +2. Some data is collected about the package. (That is done by the + so-called *data collector* scripts.) For example, the ``file`` + program is run on each file in the package and the output is stored + in the lab. + +3. The *checks* 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. + +4. Depending on the *lab mode* Lintian uses (see below), the whole lab + directory is removed again. If the lab is not removed, parts of the + data collected may be auto cleaned to reduce disk space. + +This separation of the *check* from the *data collector scripts* makes +it possible to run Lintian several times over a package without having +to recollect all the data each time. In addition, the checker scripts do +not have to worry about packaging details since this is abstracted away +by the collector scripts. + +.. _section-3.2: + +The laboratory +-------------- + +Lintian creates a temporary lab in ``/tmp`` which is removed again after +Lintian has completed its checks, unless the ``--keep-lab`` is used. + +.. _section-3.3: + +Writing your own Lintian checks +------------------------------- + +This section describes how to write and deploy your own Lintian checks. +Lintian will load checks from the following directories (in order): + +- ``$LINTIAN_BASE/checks`` + +Existing checks can be shadowed by placing a check with the same name in +a directory appearing earlier in the list. This also holds for the +checks provided by Lintian itself. + +Checks in Lintian consist of a Perl module implementing the actual check +(.pm). The files names of such checks are expected to be in CamelCase. For +the check name used on the command line, case transitions are replaced with +hyphens. Perl's two colons (::) are replaced with a slash. + +Vendors are recommended to use their vendor name before the first slash +(e.g. "ubuntu/fields"). + +.. _section-3.3.1: + +Check description file +~~~~~~~~~~~~~~~~~~~~~~ + +The check description file is written in the same syntax as Debian +control files as described in the `Debian Policy Manual +§5.1 <https://www.debian.org/doc/debian-policy/#s-controlsyntax>`__. +Check description files allow comments as described in the Policy +Manual. + +The check description file has two paragraph types. The first is the +check description itself and must be the first paragraph. The rest of +the descriptions describe tags, one tag per paragraph. + +.. _section-3.3.1.1: + +Check description paragraph +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The fields in the check description paragraph are: + +*Check-Script* (simple, mandatory) + Name of the check. This is used to determine the package name of the + Perl module implementing the check. + +*Type* (simple, mandatory) + Comma separated list of package types for which this check should be + run. Allowed values in the list are "binary" (.deb files), "changes" + (.changes files), "source" (.dsc files) and "udeb" (.udeb files). + +*Info* (multiline, optional) + A short description of what the check is for. + +*Author* (simple, optional) + Name and email of the person, who created (or implemented etc.) the + check. + +*Abbrev* (simple, optional) + Alternative or abbreviated name of the check. These can be used with + certain command line options as an alternative name for the check. + +.. _section-3.3.1.2: + +Tag description paragraph +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The fields in the tag description paragraph are: + +*Tag* (simple, mandatory) + Name of the tag. It must consist entirely of the lower or/and upper + case characters ([a-zA-Z]), digits ([0-9]), underscore (_), dash (-) + and period (.). The tag name should be at most 68 characters long. + +*Severity* (simple, mandatory) + Determines the default value for the alert level. The value must be + one of "error", "warning", "info", "pedantic", or "classification". + This correlates directly to the one-letter code (of non-experimental + tags). + +*Info* (multiline, mandatory) + The tag descriptions can be found on Lintian's website + ("https://lintian.debian.org"). The description is in the standard + Markdown format. + + The symbols &, < and > must be escaped as &, < and > + (respectively). Please also escape _ as _ and * as *. + + Indented lines are considered "pre-formatted" and will not be line + wrapped. These lines are still subject to the allowed HTML tags and + above mentioned escape sequences. + +*Ref* (simple, optional) + A comma separated list of references. It can be used to refer to + extra documentation. It is primarily used for manual references, HTTP + links or Debian bug references. + + If a reference contains a space, it is taken as a manual reference + (e.g. "policy 4.14"). These references are recorded in the + "output/manual-references" data file. + + Other references include manpages ("lintian(1)"), ftp or http(s) + links ("https://lintian.debian.org"), file references + ("/usr/share/doc/lintian/changelog.gz") or Debian bug numbers + prefixed with a hash ("#651816"). + + Unknown references are (silently) ignored. + +*Experimental* (simple, optional) + Whether or not the tag is considered "experimental". Recognised + values are "no" (default) and "yes". Experimental tags always use "X" + as their "one-letter" code. + +.. _section-3.3.2: + +Check Perl module file +~~~~~~~~~~~~~~~~~~~~~~ + +This section describes the requirements for the Perl module implementing +a given check. + +The Perl package name of the check must be identical to the check name +(as defined by the "Check-Script" field in the description file) with +the following transformations: + +- All periods and dashes are replaced with underscores. + +- All forward slashes are replaced by two colons (::). + +- The resulting value is prefixed with "Lintian::". + +As an example, the check name ``contrib/hallo-world`` will result in the +Perl package name ``Lintian::contrib::hallo_world``. + +.. _section-3.3.2.1: + +API of the "run" sub +^^^^^^^^^^^^^^^^^^^^ + +The Perl module must implement the sub called ``run`` in that Perl +package. This sub will be run once for each package to be checked with 5 +arguments. These are (in order): + +- The package name. + +- The package type being checked in this run. This string is one of + "binary" (.deb), "changes" (.changes), "source" (.dsc) or "udeb" + (.udeb). + +- An instance of API Lintian::Collect. Its exact type depends on the + type being processed and is one of Lintian::Collect::Binary (.deb or + .udeb), Lintian::Collect::Changes (.changes) or + Lintian::Collect::Source (.dsc). + +- An instance of Lintian::Processable that represents the package being + processed. + +- An instance of Lintian::ProcessableGroup that represents the other + processables in the given group. An instance of the + Lintian::Collect::Group is available via its "info" method. + +Further arguments may be added in the future after the above mentioned +ones. Implementations should therefore ignore extra arguments beyond the +ones they know of. + +If the run sub returns "normally", the check was run successfully. +Implementations should ensure the return value is undefined. + +If the run sub invokes a trappable error (e.g. "die"), no further checks +are done on the package and Lintian will (eventually) exit with 1 to its +caller. The check may still be run on other packages. |