namcap - ArchWiki

Jump to content

# namcap

From ArchWiki

Related articles

- Creating packages
- pacman

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

## Installation

Install the namcap package.

## Usage

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

    $ namcap file_name

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

    $ namcap --info file_name

Namcap uses a system of tags of three types to classify the output:

- `E:` — Errors — are things that namcap is very sure are wrong and need to be fixed. An error is important and should be fixed immediately; mostly they relate to insufficient security, missing licenses or permission problems.
- `W:` — Warnings — are things that namcap thinks should be changed, but if you know what you are doing then you can leave them.
- `I:` — Information — are only shown when you use the `info` argument. Information messages give information that might be helpful but is not anything that needs changing—think of them as notes or comments.

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.

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

To filter unneeded namcap messages you can use grep(1), for example:

    namcap --info file_name \
      | grep \
          --invert-match \
          --perl-regexp \
          --regexp=" W: Package was [[:digit:]]+% docs by size; maybe you should split out a docs package|\
     I: Dependency .* detected and satisfied \(libraries \['.*'\] needed in files \['.*'\]\)|\
     I: Dependency .* detected and satisfied \(programs \['.*'\] needed in scripts \['.*'\]\)|\
     I: Link-level dependence .* in file \['.*'\]|\
     I: Script link detected \(.*\) in file \['.*'\]|\
     I: Soname dependency '.*\.so=.*' provided by .* is satisfied \(needed in files \['.*'\]\)"

## Tag file

The `/usr/share/namcap/namcap-tags` tag file consists of lines specifying the human-readable form of the hyphenated machine-parsable tags used in the namcap code:

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

Tip

- A line beginning with a `#` is treated as a comment.
- `%s` is a format specifier, see #Creating a module for more information.
- `::` (double colon) separates the hyphenated machine-parsable tag from the human-readable description.

## 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 `PKGBUILD`s.

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 `PKGBUILD`s 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 `PKGBUILD`s, and `"tarball"` for a module processing a binary package file.

## Troubleshooting

### W: Directory (usr/src/debug/…) is empty

Machine-parsable message: `empty-directory usr/src/debug/…`.

You may silence this warning by applying `options=(!debug)` in your PKGBUILD. This might be useful for Arch User Repository (AUR) packages which use Debian packages as the source.

### I: Soname … is not specified as provides by … yet (needed in files …)

Machine-parsable tag: `libdepends-missing-provides`.

The dependency provides array does not contain the soname—i.e. the dependency's `PKGBUILD` file should be changed and the dependecy should be rebuilded.

### I: Soname dependency … provided by … detected and not included (needed in files …)

Machine-parsable tag: `libdepends-detected-not-included`.

Include the soname in the depends array.

`autodeps` can add soname dependency automatically, but the dependency must be built with `autodeps` first. For more information, see:

- makepkg.conf(5) § OPTIONS
- alpm-soname(7)
- Library dependencies.

Categories:

- Arch projects
- Commands
- Package development

namcap
Add topic