Skip to content

clang-tidy: parse against libc++ everywhere, and document the real hook setup - #279

Merged
helly25 merged 4 commits into
mainfrom
compile_db_libcxx
Aug 9, 2026
Merged

clang-tidy: parse against libc++ everywhere, and document the real hook setup#279
helly25 merged 4 commits into
mainfrom
compile_db_libcxx

Conversation

@helly25

@helly25 helly25 commented Aug 8, 2026

Copy link
Copy Markdown
Owner

Two parts of the same story: making clang-tidy behave identically on macOS and Linux, and describing the setup honestly in the README.

1. Parse against libc++ on every platform

compile_commands-update.sh extracts the compile DB from the default build configuration--config=clang never reaches the extractor's aquery; we only substitute the compiler binary afterwards via --bcce-compiler. So the recorded commands carry no -stdlib, and the hermetic clang falls back to each platform's default:

platform standard library
macOS libc++ (the hermetic toolchain's own)
Linux libstdc++

Same clang-tidy, different standard library, therefore different template instantiations and different findings. A finding fixed on a Mac could simply be absent on the Linux CI runner, and the reverse — which makes the finding sweep platform-dependent and would make enforcement flap between local and CI.

Fix: pass --bcce-copt=-stdlib=libc++. The hermetic toolchain ships libc++ on both platforms, so this is a no-op on macOS and the actual switch on Linux.

Test: all 3002 compile DB entries carry the flag; clang-tidy still parses cleanly on macOS with no hard errors. The Linux half is exactly what this changes, and the CI clang-tidy job verifies it.

This treats the symptom

The root cause is that the DB is extracted in the default configuration with only its compiler replaced. Extracting with --config=clang (a refresh_compile_commands target with targets = {"@//...": "--config=clang"}) would make every flag — stdlib, include paths, feature macros, sysroot — match what bazel actually builds, and would let both --bcce-compiler and this flag go away. Worth doing; tracked separately.

2. README: document the dev hook setup that actually exists

The dev-setup paragraph claimed the repo "enables trunk-fmt-pre-commit and trunk-check-pre-push so the hooks run automatically once installed". That has been false for some time: both actions are disabled in .trunk/trunk.yaml, and main.yml's "Trunk must not own git hooks" step fails the build if either is re-enabled. A dev following the README would never run pre-commit install and would end up with no git hooks at all.

It now says what is there: pre-commit owns the git hook and delegates trunk fmt to trunk, trunk's own hook actions stay disabled so the two cannot fight over .git/hooks, and CI runs pre-commit, trunk check and clang-tidy as separate jobs. clang-tidy is one of the pre-commit hooks too — it moved there from trunk, which pinned a version too old to parse this code — opt-in for now and automatic once the finding sweep lands.

This paragraph originates in #183, which proposed it before the CI guard and the clang-tidy job existed. The rest of that PR is superseded and it is being closed.

The extracted commands come from the default build configuration, not
`--config=clang`, so they carry no `-stdlib`. The hermetic clang then
falls back to each platform's default: libc++ on macOS, libstdc++ on
Linux. Same clang-tidy, different standard library, so the same check
could report differently per platform - a finding fixed on a Mac could be
absent on the Linux CI runner, and the reverse.

Pass `--bcce-copt=-stdlib=libc++`, which the hermetic toolchain ships on
both platforms. A no-op on macOS; the actual switch on Linux.

Verified locally: all 3002 compile DB entries carry the flag and
clang-tidy still parses cleanly (no hard errors). The Linux half is what
this change is for and is verified by the CI clang-tidy job.

Note this treats the symptom. The root cause is that the compile DB is
extracted in the default configuration and only has its compiler
substituted afterwards; extracting with `--config=clang` would make every
flag - stdlib, include paths, feature macros, sysroot - match what bazel
actually builds. That is tracked separately.

Signed-off-by: helly25 <6420169+helly25@users.noreply.github.com>
@helly25
helly25 enabled auto-merge (squash) August 9, 2026 08:26
helly25 and others added 2 commits August 9, 2026 09:30
The dev-setup paragraph claimed the repo "enables `trunk-fmt-pre-commit`
and `trunk-check-pre-push` so the hooks run automatically once
installed". That has been false for some time: both actions are disabled
in .trunk/trunk.yaml, and main.yml's "Trunk must not own git hooks" step
fails the build if either is re-enabled. A dev following the README would
never run `pre-commit install` and would end up with no git hooks at all.

Describe what is actually there: pre-commit owns the git hook and
delegates `trunk fmt` to trunk, trunk's own hook actions stay disabled so
the two cannot fight over .git/hooks, and CI runs pre-commit, trunk check
and clang-tidy as separate jobs. clang-tidy is one of the pre-commit
hooks too - it moved there from trunk, which pinned a version too old to
parse this code - opt-in for now and automatic once the finding sweep
lands. STYLE_CPP.md has the details.

The paragraph is taken from #183, which proposed it before the CI guard
and the clang-tidy job existed; the rest of that PR is superseded.

Signed-off-by: helly25 <6420169+helly25@users.noreply.github.com>
@helly25 helly25 changed the title Parse against libc++ on every platform for clang-tidy clang-tidy: parse against libc++ everywhere, and document the real hook setup Aug 9, 2026
@helly25
helly25 requested a review from Fab-Cat August 9, 2026 08:42
@helly25
helly25 merged commit 7807a22 into main Aug 9, 2026
23 checks passed
@helly25
helly25 deleted the compile_db_libcxx branch August 9, 2026 10:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants