namcap

Namcap is an Arch Linux tool to check binary packages and source PKGBUILDs for common packaging mistakes.

Installation

Usage

To run namcap on a file, where filename is PKGBUILD or the name of a package binary package_name.tar.zst:

$ namcap filename

If you want to see extra informational messages, then invoke namcap with the --info (-i) flag:

$ namcap --info filename

Namcap uses a system of tags to classify the output. Tags are of three types — errors (denoted by E), warnings (denoted by W) and informational (denoted by I). An error is important and should be fixed immediately; mostly they relate to insufficient security, missing licenses or permission problems.

Normally namcap prints a human-readable explanation (sometimes with suggestions on how to fix the problem). If you want output which can be easily parsed by a program, then pass the --machine-readable (-m) flag to namcap.

The tag file /usr/share/namcap/namcap-tags (online source) consists of lines specifying the human-readable form of the hyphenated tags used in the namcap code. A line beginning with a # is treated as a comment:

# The comment
machine-parsable-tag %s :: The human-readable description for the tag %s

Note:

:: (double colon) separates the hyphenated machine-readable tag from the human-readable description.
%s is a format specifier, see #Creating a module for more information.

See namcap(1), README and NEWS for more information.

Creating a module

The main namcap program namcap.py takes as parameters the filename of a package or a PKGBUILD and makes a pkginfo object, which it passes to a list of rules defined in __tarball__ and __pkgbuild__. Once your module is finalized, remember to add it to the appropriate array:

__tarball__ defines the rules which process binary packages,
__pkgbuild__ defines the rules which process PKGBUILDs.

A sample namcap module is like this:

namcap/url.py

import pacman

class package:
    def short_name(self):
        return "url"

    def long_name(self):
        return "Verifies url is included in a PKGBUILD"

    def prereq(self):
        return ""

    def analyze(self, pkginfo, tar):
        ret = [[], [], []]
        if not hasattr(pkginfo, 'url'):
            ret[0].append(("missing-url", ()))
        return ret

    def type(self):
        return "pkgbuild"

Each namcap module must have the following methods:

short_name(self) — returns a string containing a short name of the module. Usually, this is the same as the basename(1) of the module file.

long_name(self) — returns a string containing a concise description of the module. This description is used when listing all the rules using namcap --rules=rule_list.

prereq(self) — returns a string containing the prerequisites needed for the module to operate properly. Usually empty string ("") for modules processing PKGBUILDs and "tar" for modules processing package files. "extract" should be specified if the package contents should be extracted to a temporary directory before further processing.

analyze(self, pkginfo, tar) — should return a list comprising in turn of three lists: error, warning and information tags respectively. Each member of these tag lists should be a tuple consisting of two components: the short — hyphenated — form of the tag with the appropriate format specifiers (like %s) and the parameters.

type(self) — returns "pkgbuild" for a module processing PKGBUILDs, and "tarball" for a module processing a binary package file.