Upgrade Llvm

Upgrade LLVM to a new version. Accepts the target version as argument (e.g., 22.1.4).

This is the complete workflow for upgrading the LLVM prebuilt packages that clice depends on. Follow each step in order. Steps that involve CI should use polling (check every ~5 minutes) to wait for completion.

Step 1: Trigger LLVM Build

Trigger the build-llvm workflow on GitHub Actions:

gh workflow run build-llvm.yml \
  --field llvm_version="<VERSION>"

• Poll until all 14 matrix builds complete (~2-3 hours), note the workflow run ID

Step 2: Download Local Platform Artifact

Download the artifact matching the development machine:

gh run view <RUN_ID>
gh run download <RUN_ID> -n x86_64-unknown-linux-gnu.releasedbg.tar.xz -D .llvm-download
mkdir -p .llvm
tar -xf .llvm-download/x86_64-unknown-linux-gnu.releasedbg.tar.xz -C .llvm

Configure clice to build against it:

pixi run cmake-config RelWithDebInfo ON -- "-DLLVM_INSTALL_PATH=.llvm"
pixi run cmake-build RelWithDebInfo

An existing build directory caches LLVM_DIR and Clang_DIR from the previous package, and find_package honours them before the PATHS we pass — the new package is silently ignored. Add -ULLVM_DIR -UClang_DIR to the -- arguments, or use a fresh build directory.

Compilation will likely fail — that's what Step 3 addresses.

Step 3: Adapt API Changes

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., createDiagnostics parameter changes
• Type merges/splits: e.g., DependentTemplateSpecializationType → TemplateSpecializationType

Strategy:

1. Fix header/namespace changes first (mechanical)
2. Fix type system and signature changes (requires understanding semantics)
3. Update test expectations (AST structure changes affect test output)
4. Ensure pixi run unit-test RelWithDebInfo passes
5. Port clang/lib/AST/StmtProfile.cpp changes into src/semantic/expr_hash.cpp (a trimmed copy of StmtProfiler with clice's own leaves): do not diff the files — list the upstream commits with git log llvmorg-<old>..llvmorg-<new> -- clang/lib/AST/StmtProfile.cpp, and hand an agent that list with the instruction to apply each commit's C and C++ visitor changes to the port; unit_tests --test-filter=expr_hash (the bit-for-bit fidelity test against Stmt::Profile) must be green afterwards
6. Bump index_format_version in src/index/serialization.h: 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
7. Expect the Debug leg to catch link-list gaps: the Linux and macOS Debug packages are shared-library builds, so every library clice uses directly must be listed in cmake/llvm.cmake — a static link resolves symbols from any archive pulled in transitively and hides a missing entry. To check before Step 5, build Debug against the Step 1 debug-asan artifact for your platform the same way Step 2 uses releasedbg

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.

Step 4: Create PR

git checkout -b chore/upgrade-llvm-XX
git add -A
git commit -m "chore: upgrade LLVM to XX.Y.Z"
git push -u origin chore/upgrade-llvm-XX
gh pr create --title "chore: upgrade LLVM to XX.Y.Z" --body "..."

CI will fail at this point (manifest hashes are stale) — this is expected.

Step 5: Run Release LLVM Workflow

Trigger release-llvm to build pruned packages:

gh workflow run release-llvm.yml \
  --ref <BRANCH> \
  --field source_run_id="<STEP1_RUN_ID>" \
  --field llvm_version="<VERSION>"

This will: discover unused libs → create clice-llvm release → repackage with pruning. Poll until complete.

Step 6: Update Version

Update the version string in cmake/package.cmake:

setup_llvm("<VERSION>")

Commit and push:

git add cmake/package.cmake
git commit -m "chore: update LLVM to <VERSION>"
git push

Poll CI until all platforms pass. CMake downloads the correct artifact automatically based on the version and platform — no manifest file needed. Local build directories keep building against the old package: setup_llvm skips the download while the cached LLVM_INSTALL_PATH still points at an existing install, and find_package keeps the cached LLVM_DIR/Clang_DIR. Reconfigure with -ULLVM_INSTALL_PATH -ULLVM_DIR -UClang_DIR, or use a fresh build directory.

Step 7: Write LLVM Changelog (REQUIRED)

Every LLVM upgrade MUST append to llvm-changelog.md in this skill's directory (.claude/skills/upgrade-llvm/llvm-changelog.md). It is maintainer reference material, deliberately not a docs page.

Add a new H2 section (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:

# If ../llvm-project exists locally:
cd ../llvm-project
git log --oneline llvmorg-<OLD>..llvmorg-<NEW> -- clang/include/clang/AST/

If the LLVM source is not available locally, look up changes on GitHub by searching the LLVM repository commit history.

Group changes by category (Type System, NNS, Driver/Frontend, Other) with a table per category. See the existing LLVM 21 → 22 section as a template.

Step 8: Report to User

Present a summary to the user and wait for confirmation before considering the upgrade complete. The summary should include:

• All API changes that were adapted and how they were resolved
• 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 user decides whether all changes are acceptable or if adjustments are needed. Do NOT push final changes or mark the work as done until the user confirms.

Notes

• Artifact size limit: GitHub Release max 2GB per file. macOS LTO artifacts are largest, currently ~1.7GB with xz -9e.
• Pruning safety: discover phase validates by deleting .a files one by one and rebuilding clice. clang-tidy modules can't be deleted due to force-link.
• Private headers: clice depends on private Clang Sema headers (TreeTransform.h etc.), copied from source during build-llvm.py. Users must use our packaged LLVM.