lint

Runs the policy checks of the tree, each file read once, with a self-test before each check

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,
                                   the joined lines of code-wrap
lint --check <id> --write --path <prefix>[,...]  write only below these paths (code-wrap, qdoc-header-class)
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 --count                       also print `<check> <count>` for each check on standard output
lint --json                        also print the findings of each check as JSON on standard output
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 it with kiln, then run it from the repository root. debug/lint/lint is its path with no output.dir (Invoking a tool):

kiln build src/tools/lint
debug/lint/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.

Numbers on standard output

--count and --json give the result of a run to a program: a probe of a recurring spec, or the farm. The report still goes to standard error, and the exit code does not change.

--count prints one line for each check that ran, with the check and the count of its findings. A note is not a finding, so it does not count. The numbers in this example are not the numbers of the tree today:

$ lint --check code-wrap,root-strays --count 2>/dev/null
code-wrap 58966
root-strays 0

--json prints one JSON object on one line. It has one entry in checks for each check that ran. In this example, the message of the first finding is shorter than the real one:

{"checks": [{"id": "root-strays", "count": 1, "passed": false, "findings": [{"path": "notes.md", "line": 0, "message": "tracked entry in the project root that does not belong (1 tracked file(s)). …", "note": false}, {"path": "", "line": 0, "message": "10708 tracked file(s) checked against 11 allowed root entries", "note": true}]}]}
Field Meaning
id The check
count Its findings that are not notes, the number of --count
passed True when the check passed
findings Each finding and each note, with path, line, message and note. note is true for a note
notJudged Why the check could not judge. Only a check that is not judged has it

With both options, lint prints the JSON only.

Exit codes

Code Meaning
0 Every check that ran passed
1 A finding, a failed self-test, an empty run, or, with --strict, a check that is not judged
2 A wrong command line, such as a check name that does not exist
4 No checkout, no vendored-paths.txt, or, with --with-tests, no kiln program in the build

--with-tests

After the checks, lint --with-tests runs the guard suites with kiln test --prebuilt default --profile gate: the suites that a qbs build left in default/. It does not build: run a whole qbs build first. This is one of the runs that still needs the qbs path; kiln test --profile gate runs the same suites from a kiln build, without the rest of lint.

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 qbs 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> (Start here, step 1). If the program does not exist, lint exits 4 and says so.

The build step

cpp-policy also runs in the qbs build, as a step of the lint product. A violation of the exception and RTTI policy fails qbs build. A kiln build has no such step, so with kiln run lint --check cpp-policy, or the whole lint, before you push. 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.

ID Title Owner Scope
banned-identifiers A removed name stays removed: no code names an identifier of banned-identifiers.txt §BSS-P-18 tree
build-class A test reads its build class only through test/BuildClass.hpp, and a skip for a class is not added without the owner's approval §BCL-7 test tree
build-matrix The build-matrix YAML parses, carries its Qt and Windows output schema, and has every leaf §CF-13 tree
ccache-config ccache shares its entries between sibling checkouts on this host §BPC-0 machine
clear-colors A clear that can reach the screen uses placeholderColor(), not a QColor literal §WFD-C4 tree
code-wrap Code never wraps: no statement goes on over a line end, and no shell command in a page §CNW-3 tree
comms-consent Every way to switch a comms channel on, and every raw send in comms, is allowed by name §CC-G1 tree
core-tier A coreTier library's headers include Qt Core and nothing else from Qt §BSS-T-1 tree
cpp-policy Our code uses no exceptions and no RTTI, and a product that enables either records why §EXP-E2 tree
debuginfo-follows-install Each Application wrapper binds installDebugInformation to install §WFR-RC-6.3 tree
disabled-tests A suite is not switched off (excluded category, condition: false, extraCondition: false, requiresCapabilities) without the owner's approval §TL-T-1 test tree
dlopen-declared Each library our code opens at run time by name is in runtime.dlopen, so the packages depend on it §KN-K23 tree
doc-names A published page names no edition unless it is a page of that edition, says "robot" only for robot apps, declares its apps and its known editions, names each figure, links inside the tree and has a title of one form §WLO-A4 tree
edition-urls No code under src/ writes the address of an edition's site; the apps link it through app::site §WLO-A7 tree
facility-ctor An activity that looks up a facility declares the context constructor, and casts the result checked §AC-3 tree
glsl-style GLSL indents with tabs, aligns with spaces and holds no tab inside a line, in all three populations §RRF-C3 tree
header-statics A first-party header declares no mutable static variable at namespace scope §TSR-S-6 tree
headless-contradiction A suite in a built category does not declare headless: false §TSR-S-1 test tree
hivecluster-mkpath libhive makes folders inside a hive with FsUtil::mkpath(), not QDir::mkpath() §FU-6 tree
nice-compliance Every process the build spawns takes its priority from lowpriority.js §BPT-5 tree
no-message-box Our code opens no blocking QMessageBox; a notice goes through toast, a question through a confirm seam §NS-8.8 tree
no-shell Every tracked script is listed in exempt-scripts.txt with the reason it stays a script §BSS-P-17 tree
opal-family-registration Every OPAL task family is declared or called, and the hand-wired set grows only through its baseline §OTR-6 tree
parity-citations Every matrix <ID> citation names one row of one registered matrix, and each generated evidence block is current §CIE-C5 tree
pragma-once A first-party header uses an include guard, not #pragma once, and no two headers share one §APD-M17 tree
qdoc-commands Each command in a QDoc block is one that QDoc knows §APD-P12 tree
qdoc-file-local No QDoc block sits in an anonymous namespace, a function or class body, or above a static declaration or main() §APD-M26 tree
qdoc-header-class A class whose QDoc block sits in a header has its class block in a .cpp or .qdoc file §APD-P13 tree
qdoc-star-lines No line of a QDoc block starts with an asterisk, which QDoc reads as text §APD-M30 tree
qdoc-namespace The scope of each documented class and namespace has a QDoc page §APD-P12 tree
product-boundary A product compiles only its own files: no files: or prefix: reaches into another product §KN-K9 tree
real-platform-tests A suite that skips for want of Vulkan declares requiresRealPlatform: true §TSR-S-3 test tree
rhi-first-policy Backend-specific graphics code stays in librhi, and libconstruct guards float targets and SSBOs §RFC-4 tree
root-strays The project root holds only its fixed set of tracked entries §BSS-M-2 tree
script-env An exempt script uses the environment only where §NEV-A10 allows it, and says so §NEV-A10 tree
section-numbers A §-number in a markdown heading addresses one section per file §BSS-M-2 tree
service-level-names A ServiceLevel member list names its services with ->name(), never with a string literal §NCL-C1 tree
settings-write-paths An apply, push or fallback path never persists a setting §CIE-C4 tree
shared-members A suite with shared: true obeys the member rules of SharedTestProbe.qbs §TSR-B-6 test tree
shell-stubs A test stubs a program with a program, not a shell script, and names no /tmp/ §WFD-C5 test tree
shortcut-callbacks Every id a shortcut callback binds is registered somewhere in the tree §CFGU-8 tree
shutdown-rules A QFutureWatcher that libstore makes is parented to qApp §SL-RS-8 tree
signal-id-discipline A handler for an id-carrying signal uses the id, or says why it does not §UC-T5 tree
stream-discipline Shipped code writes to stdout only where the allowlist records it as data §SD-V-3 tree
test-condition A Test binds extraCondition, never a condition that replaces the template's §KN-F25 test tree
test-main Every suite enters through OC_TEST_MAIN*, never a raw QTEST_*_MAIN §TSR-S-2 test tree
tick-discipline SceneWorkerWidget ticks the worker through the gate, or says why not §IQD-3 tree
unmarked-capture Only a test takes a capture without the marking; every image for a reader is marked §WLO-A11 tree
unique-connection-lambda No connect that names Qt::UniqueConnection carries a lambda §CIE-T4 tree
viewport-after-pipeline Every draw follows a viewport set after its pipeline, which gives the draw its scissor §VWV-1 tree

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.

code-wrap

Code never wraps: a viewer scrolls sideways instead. The check reads the C++ and GLSL files under src/ and test/, and the shell fences of the pages under content/doc/. A line wraps when it ends inside a parenthesis, when it ends with a binary operator, when the next line starts with a continuation such as :, ,, && or <<, or, in a shell fence, when it ends with \. A line that holds only string literals, a row of a table or a matrix, a preprocessor line and a comment do not count.

The tree held about 47 000 wrapped lines when the rule came, so the check reads a baseline, integration/lint/code-wrap.baseline: the count of wrapped lines of each file. A file whose count grows fails, and so does a file that is not in the baseline and holds a wrap. The baseline only shrinks:

lint --check code-wrap --write
lint --check code-wrap --update

--write joins each wrapped statement that joins safely into one line and says each join. --path src/libs/libfoo/ limits it to one library, as the sweep goes. A blank line inside a statement goes, and a comment at the end of the statement's last line ends the joined line. It does not join a statement with a line comment before its end, a line that is only a comment, a preprocessor line or a literal over several lines inside it: a person joins those. --update then lowers the counts that dropped. It never raises a count and never adds a file.

doc-names

One source of pages serves the site and the help of every edition. A page that writes the name of one edition shows that name in every other edition. The check finds these faults in the source, before an export. It reads every tracked page and sidecar under content/doc/published/, the app list integration/editions/apps.json and each edition under integration/editions/.

The page apps are the global.apps of the page's sidecar. A page with no global.apps reads as [], the strictest value. Each finding names the file, the line and the rule of the writing policy that it breaks:

  • name — prose holds a name of an edition. A code span, a fence, a link target, an address and template syntax are not prose.
  • name-code — a name of an edition is in the text that is not prose, on a page that an edition without developers shows.
  • name-path — a data path names the organization. Write the path with OctoMY, on the data-location page only.
  • robot — the prose or the code says robot in any of its forms, and the page apps are [], or one of them has no robot: true in the app list.
  • apps-missing, apps-unknown — the page declares no apps, or an app that the app list does not hold.
  • apps-neutral-names-app — a page for every app names one app.
  • editions-unknown — global.editions is empty, or names a folder that integration/editions/ does not hold.
  • image-name — an image has no alt text. The alt text is the figure name.
  • link-out — a link is root-absolute, or leaves content/doc/published. A link to /images/ is correct.
  • root-page — a page sits at the root of the published tree.
  • title — the page title breaks the title rule: sentence case, six words or fewer, no subtitle.
  • link-across — a note, never a failure. A link leads to a page that some edition hides where it shows the page that links.

A finding that must stay goes in the allow-list, integration/lint/doc-names.allow.yaml, with a reason. A wire constant that holds a name is an example. Each entry has these fields:

  • page — the page path, relative to content/doc/published/. It can hold * and ?.
  • check — G2- and the finding, for example G2-name-code.
  • text — the text of the finding, as the report shows it.
  • context — optional, a part of the line of the finding.
  • reason — why the finding stays.

An entry with no reason fails the check. An entry that matches no finding fails the check too. A note needs no entry.

The check also reads a baseline, integration/lint/doc-names.baseline, if the file exists. The tree has no finding, so the file does not exist. Do not make one to pass the check. Fix the page, or add an allow-list entry with a reason.

qdoc-header-class

QDoc reads documentation from .cpp and .qdoc files only. A /*! block above a class in its header is read by nothing, so the class gets no page in the API reference, and QDoc gives no warning. The check finds each /*! block at namespace scope in a header under src/ that sits directly above the definition of a class or a struct, when no \class or \struct block in a .cpp or .qdoc file documents that class.

Move the block into the class's .cpp file and give it a \class command. A class that has no .cpp file gets a .qdoc file beside its header.

The tree held 813 such blocks when the rule came, so the check reads a baseline, integration/lint/qdoc-header-class.baseline: the count of blocks of each header. It works as the baseline of code-wrap: a count that grows fails, a header that is not listed may hold none, and the baseline only shrinks:

lint --check qdoc-header-class --write --path src/libs/libfoo/
lint --check qdoc-header-class --update

--write moves each such block to the top of the class's .cpp file, above its first #include, and gives it a \class or \struct command with the name that the namespaces around the class make. A header with no .cpp file gets a .qdoc file beside it, which needs git add. A class in a namespace with no page then needs a \namespace block: lint --check qdoc-namespace names it. --update then lowers the counts.

qdoc-star-lines

Doxygen strips a * at the start of each line of a comment. QDoc does not: it reads the asterisk as text. A line of * is then no blank line, so a \brief runs on into the next paragraph, and the page shows the asterisks. The check finds each /*! block in a .cpp or .qdoc file whose lines start with *. Indent the lines of a QDoc block with a tab.

In this section
Topics
reference tools lint policy build
See also