lint

lint runs the policy checks of the tree: the rules that the code, the build files and the documents must follow, each with the spec section that owns it. It replaces the scripts of integration/lint/, one check at a time.

Usage

lint                               run every check
lint --check <id>[,<id>...]        run the named checks
lint --list [--markdown]           list the checks
lint --self-test                   run the self-test of every check, and nothing else
lint --check <id> --update         rewrite the baseline of a check that has one
lint --check <id> --write          write what a check writes: the evidence blocks of
                                   parity-citations, the leading whitespace of glsl-style
lint --root <folder>               check another checkout
lint --jobs <n>                    cap the worker threads (default: the processor count)
lint --timings                     print the time of each check
lint --strict                      fail on a check that is not judged
lint --with-tests [--kiln <program>] [--compile-db <file>]  after the checks, run the guard suites and the kiln check modes

Build and run it from the repository root:

qbs run -p lint -- --check cpp-policy

Without --root, lint checks the checkout that holds the working folder. It reads the files that git tracks, leaves out the trees that integration/lint/vendored-paths.txt lists, and reads each file once, on all processors, for every check that needs it.

What a run reports

Each check gets a block, then the run ends with a summary:

── cpp-policy
  note: 9410 non-vendored source file(s) scanned; ...
  ✓ clean

════════════════════════════════════════════
files read: 10708 of 10708 selected
passed: 1
   ✓ cpp-policy

A finding names its file and line. A note is good news, such as an allowlist entry that is no longer needed, and never fails the run.

Each check runs its self-test first. The self-test plants a violation and a clean case and checks that the matcher tells them apart. If the self-test fails, the check does not run and the run fails, because a matcher that stopped matching reports the same clean result as a clean tree.

A check that cannot judge, for example because an input file is missing, is listed as not judged. It does not count as passed. The run fails on it only with --strict.

The report goes to standard error. --list writes to standard output.

Exit codes

--with-tests

After the checks, lint --with-tests runs the guard suites with kiln test --prebuilt default --profile gate. It does not build: run qbs build first.

Then it runs the four check modes of kiln, which hold kiln's description of the build to what qbs builds: kiln commands --check, kiln sources --check, kiln keys --check and kiln import-qbs --check. The first two read the compile database that qbs wrote, release/compile_commands.json unless --compile-db names another. A mode that lacks its input is listed as not judged.

By default it runs the kiln program of this checkout's build. A machine that runs one kiln broker for every checkout refuses a kiln of another build, so there name the machine's kiln with --kiln <program>. If the program does not exist, lint exits 4 and says so.

The build step

cpp-policy also runs in the build, as a step of the lint product. A violation of the exception and RTTI policy fails qbs build. The other checks run in the guard suites, so a known violation that someone recorded does not stop a build.

Checks

The table is the output of lint --list --markdown. A test compares the two, so this page cannot drift from the program.

A tree check reads the source tree. A test tree check reads test/ only and also runs in the testTestHygiene suite. A machine check reads the configuration of this computer, so it runs from the command line only.