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 withoutdevelopersshows.name-path— a data path names the organization. Write the path withOctoMY, on the data-location page only.robot— the prose or the code saysrobotin any of its forms, and the page apps are[], or one of them has norobot: truein 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.editionsis empty, or names a folder thatintegration/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 leavescontent/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 tocontent/doc/published/. It can hold*and?.check—G2-and the finding, for exampleG2-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.