upgrade-llvm
Read before upgrading xclang/LLVM (arg = the xclang version, e.g. 23.1.2.1), touching MODULE.bazel, .bazelrc, BUILD.bazel or bazel/, or regenerating modules/ — after a library bump, or when clice needs a header or macro it does not export.
- License 许可
- Apache-2.0
- 所属仓库
- clice-io/clice
- 最近更新
- 2026-11-15
- Stars
- ★ 1.4k
- Forks
- 89
01 前言 Front Matter
- name
- upgrade-llvm
- description
- Read before upgrading xclang/LLVM (arg = the xclang version, e.g. 23.1.2.1), touching MODULE.bazel, .bazelrc, BUILD.bazel or bazel/, or regenerating modules/ — after a library bump, or when clice needs a header or macro it does not export.
02 资源文件 2
- 参考文档llvm-changelog.md35.6 KB
- 参考文档toolchain-changelog.md10.2 KB
03 SKILL.md 正文
Upgrade LLVM to a new version. Accepts the xclang version as argument (e.g., 23.1.2.1: LLVM 23.1.2, xclang's first build of it).
The compiler clice builds with and the LLVM/Clang libraries it links both come from one xclang release: xclang's Bazel module (registry https://bazel.clice.io) brings the toolchain and the release's libclang-<version>-<triple>[-asan].tar.xz archives as repositories, and the conda package xclang (channel https://conda.clice.io) the LLVM tools the tests and the packaging run. They always move together: the archives hold ThinLTO bitcode, which only the LLVM that wrote it is sure to read. clice imports libclang's headers, with every other third-party library's, through the generated module in modules/, so an upgrade regenerates it before anything builds. Follow each step in order.
Read toolchain-changelog.md in this directory before touching MODULE.bazel, .bazelrc, BUILD.bazel or bazel/: it records the platform pitfalls that still apply (symptom, cause, fix, how to check). Every new one is added there in the same shape; a toolchain change without an entry is not finished.
The work happens on a branch chore/upgrade-llvm-<major>, created from fresh origin/main (CLAUDE.md) before Step 2, and runs on two boxes (the agent-box skill), leased once and kept for the whole upgrade: a Linux one, which regenerates modules/ for every configuration and cross-builds arm64 Linux and both Windows targets as CI does, and a macOS one, which builds its own and x64 macOS.
Step 1: The xclang Release
The toolchain and the libraries are built in the xclang repository, by its own pipeline; a new LLVM version there is a change of its LLVM_VERSION and sources, and ends with a release tagged <llvm version>.<revision>, the conda packages on conda.clice.io and the Bazel module on bazel.clice.io. Upgrading clice starts once that release exists:
gh release view <VERSION> -R clice-io/xclang --json assets --jq '.assets[].name' | grep libclang
Every target clice builds needs its libclang-<VERSION>-<triple>.tar.xz, and the Debug builds (x86_64 Linux, arm64 macOS) their -asan archives.
Step 2: A clice to Regenerate With
On the Linux box, build clice from this tree before any pin moves, and keep it aside:
pixi run build RelWithDebInfo
rm -rf ~/clice-bin && cp -RL build/RelWithDebInfo/bin ~/clice-bin
The new headers need not build the old modules/ (a name it exports may be gone upstream), and regenerating only reads them. But the clice must carry this tree's own clice modularize: one built from an older tree writes another shape (thousands of extra lines of enum wrappers). main's CI build artifact (build-<triple>-RelWithDebInfo, kept 3 days) serves as well: unpacked into ~/clice-bin, it needs chmod +x ~/clice-bin/bin/* (artifacts drop the executable bit), and a box that skips the build needs pixi run install-tests before Step 4, or npx bazel gets a 404.
Step 3: Pin It
Move every pin in one change:
MODULE.bazel:bazel_dep(name = "xclang", version = "<VERSION>")pixi.toml: everyxclang = "==<VERSION>", and the Windows test environments'llvm-tools = "==<LLVM version>"pixi.lock:pixi lock
Every file of the toolchain and of libclang is an input of the actions that read it, so the new release rebuilds everything; nothing has to be cleaned. A release re-published under the same tag needs a new module version on the registry (its archive digests are recorded there).
Step 4: Regenerate modules/
modules/demand.cpp records what clice takes from the libraries; scripts/modules.py builds it for a configuration, indexes it with clice and wraps the libraries' headers with clice modularize, then merges the eight configurations into modules/. Push the pinned tree to the Linux box, then:
box run $linux 'pixi run python scripts/modules.py --clice ~/clice-bin/bin/clice generate'
box run $linux 'pixi run python scripts/modules.py --clice ~/clice-bin/bin/clice merge'
box cp $linux . modules
Each configuration takes about half a minute. The macOS ones compile against Apple's SDK, which the first of them fetches (MODULE.bazel accepts its license). Nothing under modules/ but demand.cpp, BUILD.bazel and modules.bzl is edited by hand; a wrong result is fixed in its inputs and regenerated:
generatecompilesdemand.cppfirst, so a header that moved or went upstream stops it there: fix the include indemand.cpp, as the API adaptation of Step 5 would in clice's own files.- A warning from
clice modularizestops it too: a header the partition leaves to the program means a library's include directory moved (the partition's globs are inscripts/modules.py). - What only some configurations export lands under their conditions in
third_party.cppmandlibc.cppm; what clice uses on one platform alone is written under that platform's#ifdefindemand.cpp(llvm/Support/WindowsError.hunder_WIN32).
The diff of modules/ is part of the upgrade's review: names the libraries dropped or renamed, and macros that changed.
Step 5: Build and Adapt the API
pixi run build RelWithDebInfo
Fix LLVM API breaking changes based on compilation errors. Common categories:
- Header path changes: e.g.,
clang/Driver/Options.h→clang/Options/Options.h - Namespace migrations: e.g.,
clang::driver::options→clang::options - Type system changes: e.g., ElaboratedType removal, NestedNameSpecifier pointer→value
- Function signature changes: e.g.,
createDiagnosticsparameter changes - Type merges/splits: e.g., DependentTemplateSpecializationType → TemplateSpecializationType
Strategy:
- Fix header/namespace changes first (mechanical). A header, name or macro clice now needs that
modules/does not export goes intodemand.cpp, and Step 4 runs again. - Fix type system and signature changes (requires understanding semantics)
- Update the case outputs upstream changed:
UPDATE_SNAPSHOTS=1, every changed block reviewed like code (the write-tests skill) - Ensure
pixi run -e test-run unit-test RelWithDebInfopasses - Port
clang/lib/AST/StmtProfile.cppchanges intosrc/semantic/expr_hash.cpp(a trimmed copy ofStmtProfilerwith clice's own leaves): do not diff the files — list the upstream commits withgit log llvmorg-<old>..llvmorg-<new> -- clang/lib/AST/StmtProfile.cpp, and hand an Opus subagent that list with the instruction to apply each commit's C and C++ visitor changes to the port;unittests --test-filter=expr_hash(the bit-for-bit fidelity test againstStmt::Profile) must be green afterwards - Bump
index_format_versioninsrc/index/format.cppm: entity hashes (src/semantic/identity.cpp) follow clang's canonicalization rules, so they can change silently across versions and an old index would otherwise keep serving stale symbols - A library clice starts using directly is added to
LLVM_LIBRARIESinbazel/BUILD.bazel. xclang's libclang archives carry only the libraries clice uses: one they lack goes into xclang'stoolchain/cmake/caches/clang.cmake(LLVM_Development_DISTRIBUTION_COMPONENTS) first, and needs a new xclang release
When a fix is not obvious, read the LLVM source code to understand the new API. If ../llvm-project exists locally, use it. Otherwise, look up the upstream commit/PR on GitHub.
Then the unit tests and the cases on the Linux box, and a build of every other configuration on the box that builds it: pixi run build Debug on both boxes (the ASan libclang, built with assertions, declares more than the release one), pixi run build RelWithDebInfo on macOS, and pixi run build RelWithDebInfo -- --platforms=@xclang//platforms:<triple> for the cross ones. CI runs them all, but a configuration that does not build is found faster here.
Step 6: Write the Changelogs (REQUIRED)
Toolchain-level findings on clice's side (MODULE.bazel, .bazelrc, BUILD.bazel, bazel/, CI mechanics; the toolchain itself keeps its own notes in xclang) go to toolchain-changelog.md in this directory, in its symptom / cause / fix / check shape. API changes go to llvm-changelog.md, maintainer reference material, deliberately not a docs page.
Every LLVM upgrade adds a new H2 section to llvm-changelog.md (e.g., ## LLVM 22 → 23) documenting all breaking changes encountered. For each API change, record:
- Change description
- Upstream commit hash
- PR number (link to
https://github.com/llvm/llvm-project/pull/<NUM>) - Impact on clice
To find upstream commits, search the LLVM git history between version tags (git log --oneline llvmorg-<OLD>..llvmorg-<NEW> -- clang/include/clang/AST/ in ../llvm-project, or the GitHub history). Group changes by category with a table per category, as the newest section does.
Step 7: Report and Wait
Present a summary to the maintainer and wait for confirmation before opening the PR. The summary should include:
- All API changes that were adapted and how they were resolved
- What the regenerated
modules/dropped, and whatdemand.cppgained - All test expectation changes (snapshot updates, assertion value changes) and why
- Any unavoidable behavior changes from upstream LLVM (e.g., TypePrinter output differences, type sugar changes) that affect user-visible features like hover
- The LLVM changelog that was written
The maintainer decides whether all changes are acceptable or if adjustments are needed.
Step 8: The PR
The pr skill takes over; the title is chore: upgrade LLVM to <X.Y.Z>.
Notes
- Other libraries: a version bump of kotatsu or any other library
modules/wraps (itsbazel_depinMODULE.bazel) is Steps 2 and 4 alone, then the build; so is clice starting to use a header or macromodules/does not export yet. A new library is added toLIBRARIESinmodules/modules.bzland to the partition inscripts/modules.py. - Private headers: clice includes no private clang headers, and xclang's libclang archives carry none; one clice starts to need goes into xclang's libclang package (
toolchain/in xclang) first. - Debug builds: ASan builds (
bazel/clice.bazelrc's Debug) link the ASan libclang, which xclang builds for x86_64 Linux and arm64 macOS (its@libclangfollows--features=asan); the other targets have no Debug build.
04 同仓库更多 Skills
write-tests
Read before writing or modifying anything under tests/ or unittests/, or the tools' own tests — the case workflow, unit tests, hard rules and known pitfalls.
triage
Use when asked to triage issues — classifies untriaged issues with codex, validates the labels, and returns proposed labels plus an activity digest. Read-only; runs in a forked context.
translate-docs
Read before translating, reviewing or editing any docs/zh page — clice's glossary and page conventions, on top of the shared translation rules of clice-io/docs.
test
Run the clice test suites, on a box unless a local run is truly necessary; also how to test on Windows. Optional args = suite (unit | cases | all, default all) build type (Debug | RelWithDebInfo, default RelWithDebInfo) and the box id the build ran on. Runs in a forked context; only a digest returns.
resolve-comments
Use in each watch round of an open PR — pulls its unresolved review threads, fixes them in the worktree, resolves them, and returns a compact summary.
release
Read before any release work — instant builds, nightlies, stable tags, publishing, release workflows — or symbolizing a user's crash log.