chore: bump LLVM to 77e43ec1 (May 21, 2026)#1241
Conversation
✨ Highlights
🧾 Changes by Scope
🔝 Top Files
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1241 +/- ##
===========================================
- Coverage 83.16% 83.10% -0.06%
===========================================
Files 35 35
Lines 3658 3658
Branches 843 843
===========================================
- Hits 3042 3040 -2
- Misses 409 410 +1
- Partials 207 208 +1
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
An automated preview of the documentation is available at https://1241.mrdocs.prtest2.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-07-07 10:40:47 UTC |
gennaroprota
force-pushed
the
chore/bump_llvm_for_macro_comment_support
branch
4 times, most recently
from
9c7fcf4 to
c7b6850
Compare
The new pin includes llvm/llvm-project#198452, which attaches documentation comments to macro definitions. That is the prerequisite for reading them from Clang directly instead of scanning the source, as we were initially doing in PR cppalliance#1192. The pin was about six months behind, so this also adapts MrDocs to the Clang API changes across that range: - USRGeneration.h moved from clang/Index to clang/UnifiedSymbolResolution; the `clang::index` namespace and signatures are unchanged. - `clang::DiagnosticConsumer::finish()` was removed, so the collecting diagnostic consumer relies on the forwarded `EndSourceFile()` instead. - The driver option table moved to clang/Options/Options.h, with its enumerators now in `clang::options` and `getDriverOptTable()` in `clang`. - `cl::getRegisteredOptions()` now returns a `DenseMap`, so its entries expose `.second` instead of `getValue()`. - `SubstituteConstraintExpressionWithoutSatisfaction` was re-synced with Clang's current implementation. `getRawCommentForDeclNoCache`, the per-declaration comment lookup `getDocumentation` relied on, is no longer public. Its only public replacement, `getRawCommentForAnyRedecl`, follows the redeclaration chain and so cannot return a single declaration's own comment. `getDocumentation` keeps the per-declaration behavior by porting Clang's declaration-path comment search (`getLocsForCommentSearch` and `getRawCommentNoCacheImpl`) as file-local helpers. Parsing the newer libc++ also needs a new vcruntime_new.h stub and C++ guards so stdbool.h, stdalign.h, and threads.h stop redefining `bool`, `alignas`, and `thread_local`, which are keywords, not macros, in C++. The regenerated goldens change only because Clang's output drifted over the six months: constrained templates and destructors get different symbol IDs from USR generation, though their structure is identical (requires-clause, dtor-overloads), and a few declaration locations changed.
MemorySanitizer needs an instrumented libc++. The pinned libc++ no longer compiles with Clang 20, so the MSan job now builds it with the latest Clang. AddressSanitizer works against a normal libc++, as the Apple-Clang ASan job already does, so it never needed an instrumented one - and it can no longer use one anyway: an ASan-instrumented libc++ requires its consumers to compile with ASan, but MrDocs parses libcxx.cpp with normal, non-ASan flags, and libc++'s container-check self-guard (added upstream in llvm/llvm-project#168955) rejects that parse. `needs_libcxx_runtimes` therefore returns true for MSan only. The matrix values that appeared to control this (`use-libcxx`, `libcxx-runtimes`, `llvm-runtimes`) were never consumed, so I dropped them.
The coverage step globs build/ for *.profraw, which after the bump also holds the extracted LLVM source tree. That tree ships llvm-profdata test fixtures in an older raw-profile version that llvm-profdata rejects, failing the merge. Delete build/third-party profraw first; MrDocs' own profraw live elsewhere under build/.
gennaroprota
force-pushed
the
chore/bump_llvm_for_macro_comment_support
branch
from
c7b6850 to
feddc6f
Compare
There was a problem hiding this comment.
Nice bump :)
Reimplementing rawCommentForDecl ourselves ended up a little verbose. We could add the pinned commit (77e43ec1) to the comment on locsForCommentSearch so the next bump can compare the port against the exact revision it came from. We could also check why they removed it in their PRs, issues and git blame (doing that might even reveal a better way of doing things) and we should consider filing an issue upstream asking to re-expose a per-declaration lookup (making getRawCommentNoCache public would do). If Clang takes it, we can delete the port on a later bump.
| # *.profraw. | ||
| - name: Prune third-party profraw | ||
| if: matrix.coverage | ||
| run: find build/third-party -name '*.profraw' -delete |
There was a problem hiding this comment.
What’s this profraw issue? The explanation is more descriptive than explanatory of the motivation of the command. It seems to me like if this is happening and coverage is globing the wrong directory, that’s what should be fixed instead of a second workaround to accommodate the first mistake.
| standards: '23' | ||
| main-entry-factors: | | ||
| clang Coverage | ||
| # MSan builds an instrumented libc++ from the pinned LLVM sources, |
There was a problem hiding this comment.
I don’t like some of the excessive comments that likely come from using AI. The thing with AI is that it doesn’t know how to not say things. For instance, you tell AI to not say “X” and very often it gives you text like “I’m not even going to bring up X”.
Because it’s a text-generating machine. It has no button for not generating text.
For instance, in this particular PR, it’s obvious AI was moving MSan to latest-factors and felt like it just to justify this in a comment. The comment is coherent with what it had in its context but it’s not coherent with the rest of the code. After this is merged, a person reading this file doesn’t know this context. This looks like it’s documentation for latest-factors and makes no sense there. The user wouldn’t even know this option was not in latest-factors before. The user won’t understand why msan and not latest-factors is explained here. They won’t understand why this is the only factor singled-out and so on.
| append-common-cxxflags: | | ||
| clang: -gz=zstd | ||
| extra-values: | | ||
| # libc++ runtimes: clang + (ASan or MSan) needs instrumented libc++ |
There was a problem hiding this comment.
Why are these gone? Weren't they being used? Interesting. I thought we used the custom libc++ whenever we had msan or asan. It it because the logic for this necessity is now being checked in the bootstrap script?
| // Non-allocating placement allocation functions | ||
| void* operator new ( std::size_t count, void* ptr ); | ||
| void* operator new[]( std::size_t count, void* ptr ); | ||
| #include <vcruntime_new.h> |
There was a problem hiding this comment.
Interesting. Is this something being fixed in passing or do we have something about the new version that interacts with the libc stubs? In fact, I would have this question about all other changes to the libc stubs. It's unexpected to me that they interacted in an LLVM bump.
| <source-path>function-template.cpp</source-path> | ||
| <line-number>22</line-number> | ||
| <column-number>6</column-number> | ||
| <column-number>1</column-number> |
There was a problem hiding this comment.
These changes to line numbers and column numbers are curious. Since the fixtures didn't change, we need to check whether they were broken before or whether they're broken now. Or maybe they're referencing a different part of the symbol.
| return False | ||
| san = sanitizer_flag_name(sanitizer.lower()) | ||
| if san not in ("address", "memory"): | ||
| if san != "memory": |
There was a problem hiding this comment.
We could discuss this with Matheus, but I believe the changes to this file are incorrect. At the very least we lose some std lib annotations, and so on. ASan doesn't need sanitized dependencies as much as MSan but it's less effective without sanitized dependencies. And we're building+caching our own libc++ anyway so the cost is low.
| #ifndef MRDOCS_SHARE_HEADERS_LIBC_STUBS_VCRUNTIME_NEW_H | ||
| #define MRDOCS_SHARE_HEADERS_LIBC_STUBS_VCRUNTIME_NEW_H | ||
|
|
||
| // libc++ includes this Microsoft runtime header (through <__new/align_val_t.h>) |
There was a problem hiding this comment.
This whole comment, especially "Provide just enough of it for parsing." seems redundant because this is true for all stubs by definition. They're headers libc++ includes for its own functionality and we provide only enough for parsing.
3 participants
The new pin includes llvm/llvm-project#198452, which attaches documentation comments to macro definitions. That is the prerequisite for reading them from Clang directly instead of scanning the source, as we were initially doing in PR #1192.
Changes
Third-party: Bump LLVM to 77e43ec1 (Associate documentation comments with macro definitions llvm/llvm-project#198452).
CI: Update the hardcoded LLVM hash in the cache key (ci-matrix.yml) and its mirror unit test (test_cache_keys.py) to match the new pin, so the key misses and LLVM builds fresh instead of restoring the old install. Build an instrumented libc++ for MSan only (the newer libc++ needs the latest Clang, and ASan works with the normal libc++), and prune the LLVM source tree's stray .profraw fixtures.
Source: The pin was about six months behind, so this also adapts MrDocs to the Clang API changes across that range:
clang::indexnamespace and signatures are unchanged.clang::DiagnosticConsumer::finish()was removed, so the collecting diagnostic consumer relies on the forwardedEndSourceFile()instead.clang::optionsandgetDriverOptTable()inclang.cl::getRegisteredOptions()now returns aDenseMap, so its entries expose.secondinstead ofgetValue().SubstituteConstraintExpressionWithoutSatisfactionwas re-synced with Clang's current implementation.getRawCommentForDeclNoCache, the per-declaration comment lookupgetDocumentationrelied on, is no longer public. Its only public replacement,getRawCommentForAnyRedecl, follows the redeclaration chain and so cannot return a single declaration's own comment.getDocumentationkeeps the per-declaration behavior by porting Clang's declaration-path comment search (getLocsForCommentSearchandgetRawCommentNoCacheImpl) as file-local helpers.Parsing the newer libc++ also needs a new vcruntime_new.h stub and C++ guards so stdbool.h, stdalign.h, and threads.h stop redefining
bool,alignas, andthread_local, which are keywords, not macros, in C++.Golden tests: The regenerated goldens change only because Clang's output drifted over the six months: constrained templates and destructors get different symbol IDs from USR generation, though their structure is identical (requires-clause, dtor-overloads), and a few declaration locations shifted by a line or column (auto, param-types, function-template).
Testing
No new tests are added; this is a toolchain bump. The existing unit and golden suites already cover the affected behavior and run in CI on every build, and the goldens whose output changed have been regenerated as described above.
Documentation
No documentation changes are needed: this is an internal toolchain bump with no user-facing API changes.