Lint
Overview
clice integrates clang-tidy as a built-in linting engine. clice lint runs the checks of your .clang-tidy over the project's translation units with a resident worker pool and prints one merged report.
Usage: clice lint [--workspace <dir>] [--configuration <tag>] [--jobs <n>] [--index] [--json]
Runs clang-tidy over every translation unit of the compilation database that the lint set below admits, prints the merged findings, and exits non-zero when problems are found. --index additionally builds and persists the project index from the same parses, so a follow-up clice index run has nothing left to do. --json prints the report as one JSON object instead: the counts and every finding with its place, check and notes.
Exit codes: 0 for a clean run, 1 when there are findings, 2 when the run could not complete as asked: the arguments do not parse, there is nothing to lint (no project, no compilation database or no unit), a translation unit failed to run or the index could not be persisted. An interrupted run exits with 130.
What is checked
- Every translation unit the compilation database lists, inside the project.
- Every header inside the project that the checked units include, subject to the
.clang-tidyheader filters (HeaderFilterRegex,ExcludeHeaderFilterRegex,SystemHeaders), read exactly as clang-tidy reads them. - Files outside the project are never checked, whether or not the build marks them as system headers. A rule in
clice.tomlwithlint = falsekeeps matching files inside the project out as well, for example a vendored library:
[[rules]]
patterns = ["third_party/**"]
lint = falseEach translation unit takes its configuration from the nearest .clang-tidy, with the inheritance clang-tidy applies. A compiler warning the unit's command enables is a finding under its clang-diagnostic-<flag> name unless Checks turns it off, as in clang-tidy. NOLINT, NOLINTNEXTLINE and NOLINTBEGIN/NOLINTEND comments are honored in every file. A header is checked in every translation unit that includes it, as clang-tidy would; a finding several units report identically, notes included, appears once in the report, which is sorted by file and position and keeps the notes clang-tidy attaches.
A file the compilation database lists under several commands, as a build compiling it for two targets does, is checked under each distinct one. A finding only a later command reports names that command's entry, numbered as clice command <file> lists the file's entries: (entry 2 of main.cpp), and in the JSON report an entry with the unit's file and the index.
Examples
Compiler Warnings
A compiler warning is a finding unless the checks turn it off.
Compiler warnings as findings
A warning the build enables is a finding unless the checks turn it off
The compiler warnings a unit's command enables are findings, reported under their clang-diagnostic-<flag> name, as clang-tidy reports them. A Checks starting with -*, as here, turns them off but for those it names.
Findings
A finding in a shared header is reported once, and NOLINT comments silence findings in every file.
Header findings reported once
A header is checked in every unit that includes it, and its findings are reported once
Each translation unit checks the headers it includes, as clang-tidy does, so a finding in a shared header comes from every unit that includes it. The report merges them into one line and lists every finding by file and position.
Suppression comments
NOLINT comments silence findings in headers as well as in the file being checked
// NOLINT silences its own line, // NOLINTNEXTLINE the next one, and // NOLINTBEGIN and // NOLINTEND everything between them, for every check or for the ones named in parentheses. They count in every file a unit reads, as clang-tidy reads them.
Files Kept Out
A rule keeps files out of the report.
Keep files out of lint
A rule with lint = false keeps its files out of the report, headers and units alike
A vendored library is neither checked as a unit of its own nor reported where the project's units include it.