namcap

Check a specific PKGBUILD file

$ namcap [path/to/pkgbuild]

$ namcap [path/to/package.pkg.tar.zst]

$ namcap [[-i|--info]] [path/to/file]

namcap [options] <package_file|PKGBUILD_path|directory|installed_package_name>

Examples:
namcap PKGBUILD
namcap my-package-1.0-1-x86_64.pkg.tar.xz
namcap -i bash

-i, --installed
    Checks an already installed package by name instead of a file path.

-s, --strict
    Enables strict checking, which may report more potential issues.

-w N, --warn-level=N
    Sets the warning level (0-10). 0 shows errors only, 10 shows all warnings. Default is 5.

--enable=CHECK[,CHECK...]
    Enables specific checks by their ID. Can be used multiple times to activate various categories of checks.

--disable=CHECK[,CHECK...]
    Disables specific checks by their ID. Useful for known exceptions or to reduce noise.

--ignore=ERROR[,ERROR...]
    Ignores specific error/warning messages by their ID, preventing them from being reported.

--check-dependencies
    Explicitly enables or reinforces dependency checks, ensuring all required libraries and packages are listed.

--check-for-stripped-binaries
    Checks if executable binaries and shared libraries are properly stripped to remove debugging symbols, reducing package size.

-h, --help
    Displays a help message with available options and exits.

namcap is a powerful and specialized linting tool primarily used within the Arch Linux ecosystem to analyze packages for common errors and inconsistencies. It operates on `PKGBUILD` files, built `.pkg.tar.xz` package files, or even already installed packages. Its main purpose is to help package maintainers and developers ensure their packages adhere to Arch Linux packaging standards and best practices.

The tool performs a variety of checks, including but not limited to: verifying dependencies, checking file permissions and ownership, detecting unstripped binaries, identifying missing or incorrect licenses, and flagging issues related to `PKGBUILD` syntax or deprecated functions. By automating these checks, `namcap` significantly aids in maintaining the quality, security, and stability of packages distributed through the official repositories and the Arch User Repository (AUR). Its name, "namcap," is a playful reversal of "pacman," Arch Linux's package manager, highlighting its close relationship to the system's packaging workflow.

`namcap` is primarily designed for the Arch Linux packaging environment. While it provides valuable insights, not every warning it generates indicates a critical error; some might be intentional design choices by the package maintainer. It is a diagnostic tool and does not automatically fix any reported issues; maintainers must manually address them. Running `namcap` effectively often requires the full package environment (e.g., a chroot) to properly detect all potential issues, especially regarding dependencies and file paths.

namcap performs a wide array of checks, categorizing them into errors, warnings, and informational messages. These include:

• Dependency Checks: Ensuring all required runtime and build-time dependencies are correctly specified.
• File System Checks: Verifying correct file permissions, ownership, and the absence of empty directories or problematic dot files.
• Binary Checks: Detecting unstripped binaries, which can unnecessarily increase package size.
• PKGBUILD Specific Checks: Analyzing the `PKGBUILD` script for deprecated functions, common syntax errors, or non-standard practices.
• Licensing Checks: Ensuring licenses are properly specified and included.
• Source Checks: Flagging instances where unpacked source files are left in the installed package.

namcap provides extensibility by allowing users to define and integrate their own custom checks. These checks can be written as scripts and loaded via the --add-check or --add-check-file options, enabling maintainers to enforce project-specific conventions or perform highly specialized analyses beyond the default capabilities. This feature makes `namcap` a flexible tool for custom packaging workflows.

`namcap` was conceived and developed specifically for the Arch Linux distribution. Its name is a clever anagram of "pacman," Arch Linux's highly regarded package manager, signifying its role as a complementary tool. The development of `namcap` has been driven by the need to maintain high standards of package quality, consistency, and adherence to the Arch Linux Packaging Guidelines. It has evolved over time, incorporating new checks and adapting to changes in the Arch Linux packaging ecosystem, becoming an indispensable utility for package maintainers and developers to ensure the integrity and stability of the Arch Linux software repositories and the Arch User Repository (AUR).

pacman(8), makepkg(8), ldd(1), strip(1), lintian(1)