Linting

17 min read

pekit lint checks a recipe against a set of rules and reports every violation in one pass. It is the mechanical half of a packaging review: the things a person would otherwise verify by reading the recipe and running readelf over the build, written down once and run everywhere.

pekit ships the rules but enables none of them by default. A lint.pekit.toml file turns rules on and sets their parameters, so a distribution decides what its recipes are held to and a standalone project decides the same for itself. A tree with no lint file has nothing to lint, and pekit lint says so (missing_lint_config).

Every rule is an error. There is no warning level: a rule is either on, or exempted for a stated reason. A warning would be a finding nobody has to justify.

Running it #

pekit lint
pekit lint --version 1.5.7
pekit workspace lint --json

With no version flag, an ordinary non-delegated recipe reads only its committed recipe files, pekit.lock, and patch series. It resolves no source and touches no network.

A delegated recipe is the deliberate exception. Plain pekit lint acquires one source snapshot, loads the delegated pekit.toml, package files, and lint.pekit.toml, merges them with the wrapper, and runs static rules against that effective recipe. A templated, tracked-path, or PyPI source selects the newest discoverable version; a fixed Git ref or fixed URL needs no synthetic version; a local-only delegate uses its configured [source.local] tree. This may contact the source and populate out_dir's source cache, but it runs no target and needs no build stage.

With an explicit source/version flag (--version, --latest, --local), lint performs the same effective-recipe checks and additionally checks the payload each package would pack, read from an existing build stage. It never builds: a missing stage is stage_missing, naming the pekit build to run first. The rules that need a payload are marked in the tables below; without an explicit selection they are skipped with a lint_skipped event that says how many.

lint takes the version-selection and local-source flags, --env and --keyring, and the global flags. It accepts no selectors and no --all: every package a recipe defines is checked. pekit workspace lint fans out across every member like any other command. A versioned run applies the selected environment's [lint.allow] exemptions, as the package gate does.

pekit package and pekit publish also run this policy, as the lint gate: the static rules against the recipe and the payload rules against the archives the run just wrote. Any finding stops the run before publication.

Output is one lint event per finding, with rule, package and path fields under --json, an event per exemption that applied (lint_allowed), one per exemption that did not (lint_unused_allow), and a lint_summary. The command fails with lint_failed when any finding stands.

The lint.pekit.toml file #

A rule is enabled by giving its key a value. A boolean rule takes true; a rule with a real choice takes one of its enumerated strings; a rule with a parameter takes the parameter. An absent key is a rule that does not run.

[package]
name.style    = "reverse-dns"
license       = "spdx"
license_class = true
description   = 80

[source]
discovery      = true
versions.floor = true
lock           = true

[elf]
pie   = true
relro = "full"

A rule's ID is its key path in the file: package.name.style, elf.relro. That ID is what findings carry, what [allow] names and what this page lists. Unknown keys are rejected (unknown_key), as is a value of the wrong shape (invalid_value), so a misspelled rule cannot silently not run.

Where files are found, and how they layer #

Files are found by walking up from the recipe directory to the workspace root. A recipe outside a workspace reads only its own, except that a delegated recipe also reads the file at its acquired source root. Plain lint performs that acquisition automatically; it is not necessary to request payload lint just to apply the source project's rules.

They merge outermost first, nearest winning per key, in this order:

1. the delegated source root, when there is one;
2. the workspace root;
3. each directory down to the recipe directory;
4. the recipe directory.

The source root comes first, not last, deliberately. A project may carry a lint file that holds itself to a higher bar than the distribution packaging it, but it cannot relax the distribution's rules.

A nearer file may re-parameterise a rule (description = 40 under a workspace that says 80) but may not switch one off. Setting a rule that an outer file enabled to false is refused (lint_rule_disabled). Switching a rule off goes through [allow].

[allow]: exemptions with reasons #

For a payload exception limited to particular files, prefer allow_files:

[allow_files."payload.junk"]
"usr/lib/compiler/*/crtbegin.o" = "startup object linked into user programs"

Keys are case-sensitive, package-root-relative payload paths or glob patterns (* matches within one path component; ** can cross directories). They match destinations, not build-host source paths. Every entry requires a nonempty reason and a known payload rule; absolute paths, parent traversal and malformed patterns are rejected. Other files and other rules remain enforced. Exceptions apply to all splits of the recipe, so keep paths narrow. Configurations merge per rule and pattern, nearest winning for the same pair. Matching findings remain visible as lint_allowed, and unused entries produce lint_unused_allow. A whole-rule allow takes precedence; otherwise the first matching pattern in lexical order is used. Neither form enables a rule that is disabled or absent.

Use a whole-rule exemption only when it genuinely applies to the entire recipe:

[allow]
"source.reproducible" = "non-public: grants unauthenticated SYSTEM access to a DWE guest"
"payload.manpages.required" = "upstream ships no manual pages; tracked in PEI-27"

An [allow] entry names a rule and gives a reason. The reason is mandatory (missing_reason) and may not be empty. While the entry stands, that rule's findings for the recipe are reported as lint_allowed rather than failing the run. An entry that never applies is reported as lint_unused_allow, so an exemption outlives its cause visibly and can be removed.

[allow] may appear in any file in the chain, but it belongs as close to the recipe as the exemption is true for. Under --json, a workspace-wide pekit workspace lint lists every exemption in the tree and its reason: the review list of what is not yet up to standard and why.

Rules #

Each rule is general packaging hygiene, of the kind lintian, rpmlint, rpminspect or a Homebrew audit also checks. Anything distribution-specific is a parameter, never a value baked into pekit. Rules marked payload need a staged build and run only with a version flag.

[package] #

Checked for each package definition the recipe produces.

Architecture-specific directory inference uses wildcard entries in payload.dirs.lib, such as usr/lib/*-linux-*, and the split-debug directory usr/lib/debug. Source text under usr/src/debug does not become architecture-specific merely because of that directory name. ELF objects are still detected there. Portable scripts and data may remain noarch when they depend on native packages: those dependencies are resolved for the target machine, not inherited as the portable package's architecture. Actual ELF or architecture-specific directory content in a noarch package is still reported. For an explicitly architecture-constrained source or header split, a required architecture-specific sibling can justify that constraint. This payload check cannot infer external dependency architectures; a genuinely architecture-tied package without visible payload or sibling evidence needs a documented exception.

package.virtual_capabilities is an array parameter shared by the package.references checks. It is for genuine interchangeable interfaces such as sh or an operating-system role, never for a compatibility alias for a concrete package. For example:

[package]
references = "reverse-dns"
virtual_capabilities = ["init", "sh"]

[source] #

Checked against the recipe's [source] table. Rules for a source kind the recipe does not use do nothing.

[build] #

[payload] #

All payload rules. Paths are payload destinations, slash-separated, relative to the package root.

Claim metadata uses canonical absolute paths in the installed logical root, such as /usr/bin/sh. Staged and final-archive lint convert these to package-relative keys when indexing claim slots; the leading slash does not refer to the build host. Relative, root-only and noncanonical claim paths (including .. components) are not valid claim-slot exemptions.

Parameters, all optional: payload.interpreters (default /bin/sh, /usr/bin/sh, /bin/bash, /usr/bin/bash, /usr/bin/env, /usr/bin/python3, /usr/bin/perl), payload.dirs.bin (default bin, sbin, usr/bin, usr/sbin), payload.dirs.lib (default lib, lib64, usr/lib, usr/lib64, lib/*-linux-*, usr/lib/*-linux-*) and payload.dirs.man (default usr/share/man, share/man). Directory parameters are glob patterns matched against a destination's directory.

[split] #

Empty directories owned by a filesystem skeleton are not development files. The split check applies to the files and symlinks that provide the interface.

[elf] #

All payload rules, checked for every ELF program or shared library in every package. Relocatable objects, kernel modules and anything under usr/lib/debug/ or usr/src/ are skipped.

What lint does not check #

Whether a package's role is documented, whether its split is sensible, whether a service runs under the right identity, and whether its files sit in the places a particular distribution mandates. The first three are review judgement; the last is pack-time validation in the package format, not a lint rule.

What CET validation establishes #

elf.cet checks the runtime payload's machine code, using exported function symbols, the main callback passed to libc, and relocated pointers to known functions in loaded data. It supports x86 REL, RELA and packed RELR relocations. For stripped objects it obtains symbols from a debug file shipped by this recipe at usr/lib/debug/.build-id/xx/yyyy.debug, and verifies the build ID, machine and ELF class before using its addresses. The instruction bytes always come from the runtime payload. Missing symbols, unreadable evidence and objects with no supported targets produce findings rather than a reduced-coverage pass.

Functions reached only by direct calls, jump-table labels and the process entry point do not automatically require ENDBR. This check is bounded static evidence: it cannot enumerate computed or generated targets, prove shadow-stack compatibility, validate all inline assembly, or establish that a running system actually enables CET. Retain upstream tests and runtime enforcement tests where these behaviors matter.

Compile the code with the relevant protection option, including linked runtime and assembly inputs. GNU ld's -z ibt and -z shstk force compatibility markers; they cannot substitute for instrumentation. -z ibtplt generates IBT PLT entries without overriding the input-note merge. On a native toolchain that provides marked inputs, use -z cet-report=error to reject missing properties during linking. Do not combine that check with forced properties: forcing suppresses the corresponding missing-property diagnostic. See the GNU linker options.

Rust uses its own control-flow protection code-generation option. Its linked standard library must also be compatible. Older dependencies may probe unstable features in build scripts: enabling RUSTC_BOOTSTRAP globally can change those probes. A recipe that requires an unstable code-generation option should confine that access to actual compiler code generation and test the resulting executable, as well as the complete linked input set.

If a supported upstream/toolchain combination cannot meet the rule, document a narrow allow_files."elf.cet" exception with the affected payload path, reason and removal condition. Keep the resulting lack of compatibility visible; do not manufacture a note to obtain a passing lint result.

Edit this page