Skip to main content
Documentation menu

Static analysis with clang-tidy (cabin tidy)

cabin tidy is Cabin’s wrapper around run-clang-tidy, the standard LLVM driver that fans clang-tidy invocations out across a Clang JSON compilation database. Cabin walks the selected package(s) for C/C++ source files, generates the compilation database from its build graph, and hands both to run-clang-tidy. Source discovery shares its rules with cabin fmt, so a file cabin fmt would touch is a file cabin tidy will analyze - provided it has a compile entry in the database.

Usage

cabin tidy [--fix] [--exclude <PATH>]... [--no-ignore-vcs] [-j <N>] [SELECTION]

cabin tidy --help lists every flag with its short description.

Default invocation

cabin tidy

Cabin generates build/<profile>/compile_commands.json for the selected packages and runs run-clang-tidy -p build/<profile> -quiet <files> over every recognized C/C++ source. The -quiet argument hides run-clang-tidy’s per-file progress chatter so only real diagnostics reach stderr; pass -v / --verbose to drop -quiet and see the driver’s full progress output.

cabin tidy neither runs build scripts nor applies what they reported: the compilation database lacks the include directories, definitions, and sources a script adds, so a source that includes a generated header fails to compile under clang-tidy. A library that lists no source for the platform, in a package with a build script, is taken as one the script supplies: nothing of it is analyzed, and what depends on it is analyzed without the library’s include-dirs and interface-defines and without what the script would report. An executable, test, or example whose every source a build script generates is refused as having no source.

cabin tidy exits non-zero whenever run-clang-tidy exits non-zero, which is the standard way clang-tidy signals that at least one file produced a diagnostic.

Applying fixes

cabin tidy --fix

--fix enables run-clang-tidy -fix, which applies clang-tidy’s suggested rewrites back to disk. Cabin never enables this implicitly; the rewrites are off unless you pass the flag. run-clang-tidy collects the fixes of every clang-tidy instance and applies them once all have finished, so --jobs applies in fix mode too.

Parallel jobs

cabin tidy -j 8
cabin tidy --jobs 8

-j / --jobs controls how many clang-tidy instances run-clang-tidy runs in parallel. Same precedence chain as cabin build:

  1. -j / --jobs <N> on the command line.
  2. CABIN_BUILD_JOBS=<N> environment variable.
  3. [build] jobs = <N> in a config file.
  4. Default - run-clang-tidy’s own default (today the host CPU count).

<N> must be a positive integer. 0, negatives, and non-numeric values are rejected at parse time, the same way cabin build rejects them.

Excluding paths

cabin tidy --exclude src/generated.cc --exclude vendored/

--exclude may be repeated. Each argument is a file or directory path resolved against the current working directory; a directory entry skips every descendant.

Including VCS-ignored files

cabin tidy --no-ignore-vcs

By default cabin tidy honors .gitignore, .ignore, parent-directory ignore files, and global git excludes. --no-ignore-vcs disables only the VCS ignore layer; Cabin’s built-in build / cache / vendor exclusions still apply.

Workspace selection

cabin tidy accepts Cabin’s standard workspace selection flags:

FlagBehavior
--workspaceAnalyze every workspace member
--package <name>, -p <name>Analyze the named workspace package; repeat for multiple
--default-membersAnalyze [workspace.default-members]

Without any of these flags, cabin tidy operates on the current package.

Compile database generation

cabin tidy always generates (or refreshes) a compile_commands.json before invoking the tidy driver:

  • the file is written to build/<profile>/compile_commands.json using Cabin’s existing build directory and per-profile layout - the same path cabin build produces;
  • the database is generated without invoking Ninja: tidy is read-only analysis and a build is unnecessary;
  • each entry records its compile as an arguments array, one verbatim argument per element, so Clang tooling reads the same arguments on every host.

The build directory honors the same precedence chain as cabin build: --build-dir > CABIN_BUILD_DIR > [paths] build-dir config setting > built-in default build.

Choosing the tidy driver executable

Cabin spawns run-clang-tidy from PATH by default. Override the executable by setting CABIN_TIDY:

CABIN_TIDY=/opt/llvm/bin/run-clang-tidy cabin tidy

CABIN_TIDY is taken verbatim - typically an absolute path, but a bare command name works too (it is then resolved against PATH). When the executable cannot be found Cabin emits an actionable error:

error: run-clang-tidy was not found on PATH.
  install `clang-tidy` (LLVM toolchain) and re-run, or set
  `CABIN_TIDY=/path/to/run-clang-tidy` to a specific binary

.clang-tidy discovery

clang-tidy has its own file-based configuration mechanism called .clang-tidy. Cabin does not generate or modify these files and does not pass any -config=, -checks=, or related flags to the tidy driver: it lets clang-tidy walk upward from each translation unit’s directory to find the nearest .clang-tidy, exactly as it would in any other invocation.

Commit a .clang-tidy to your repository if you want a project-wide configuration. When no .clang-tidy is found anywhere, clang-tidy falls back to its built-in default checks - the same behavior you would see invoking clang-tidy directly.

What gets analyzed

Source discovery applies the same rules as cabin fmt - see fmt.md. cabin tidy then narrows the discovered set to files that have a compile entry in the generated compile_commands.json; headers and undeclared sources are skipped because clang-tidy cannot meaningfully analyze a translation unit it has no compile command for.

The walk skips the same directories cabin fmt skips:

  • VCS-ignored files (unless --no-ignore-vcs is in effect);
  • Cabin’s resolved build directory;
  • target, dist, out, .cabin, node_modules, .venv, __pycache__;
  • VCS metadata (.git, .hg, .svn, .jj, .pijul);
  • the manifest directories of unselected workspace members.

Verbosity

cabin tidy honors Cabin’s standard verbosity flags:

  • -q / --quiet suppresses Cabin-owned status output but does not suppress clang-tidy diagnostics
    • run-clang-tidy inherits stderr directly.
  • -v / --verbose adds a per-invocation summary describing the selected packages, the file count, the compile database path, and the resolved jobs setting; it also drops -quiet from the spawned run-clang-tidy command so the driver’s own progress output appears.
  • -vv (or -v -v) additionally echoes the spawned tidy command line.

Versioned dependencies

cabin tidy does not run Cabin’s artifact pipeline. When the selected package closure declares a versioned registry dependency (dep = "1.2"), Cabin refuses to plan a tidy run and surfaces a clear diagnostic:

error: package `hello` declares versioned registry dependencies; `cabin tidy` does not run
the artifact pipeline, so registry-backed selections are not supported

cabin build and cabin fetch can still materialize those dependencies for build workflows, but they do not make a registry-backed selection usable with cabin tidy.