build: upgrade LLGo to LLVM 21

.github/actions/setup-demo-deps/action.yml

@@ -13,24 +13,33 @@ inputs:
 runs:
   using: "composite"
   steps:
-    - name: Set up Python 3.12 on Windows
-      if: runner.os == 'Windows'
+    - name: Set up x64 host Python 3.12 on Windows
+      if: runner.os == 'Windows' && inputs.windows-arch != 'arm64'
       id: windows_python
       uses: actions/setup-python@v6
       with:
-        # LLVM 19.1.3's MSVC LLDB embeds the 3.12.7 hosted-tool-cache prefix.
-        # A newer 3.12 patch is ABI-compatible, but LLDB combines its embedded
-        # stdlib path with that installation and cannot import encodings. Keep
-        # the MinGW demo environment on the normal latest 3.12 patch. This is
-        # the host-tools interpreter: use x64 on Windows ARM, where emulation
-        # retains access to wheels that upstream projects do not publish for
-        # native ARM64 Python. The target interpreter is installed below.
-        python-version: ${{ inputs.windows-abi == 'msvc' && '3.12.7' || '3.12' }}
+        # Demo tools embed Python 3.12. Cross-architecture lanes install their
+        # native target and LLDB interpreters below. Asking an ARM64 runner to
+        # unpack the x64 hosted-tool-cache payload can crash PowerShell's ARM64
+        # CLR before emulation is involved, so that native runner is the sole
+        # exception.
+        python-version: "3.12"
         architecture: x64
         # setup-python otherwise replaces PKG_CONFIG_PATH, hiding the native
         # vcpkg metadata installed by setup-deps from LLGo's runtime build.
         update-environment: false
 
+    - name: Set up LLDB Python 3.10 on Windows amd64
+      if: runner.os == 'Windows' && inputs.windows-abi == 'msvc' && inputs.windows-arch == 'amd64'
+      id: windows_lldb_python_amd64
+      uses: actions/setup-python@v6
+      with:
+        # LLVM's official 21.1.8 x64 release is built against Python 3.10;
+        # installing Python 3.12 cannot satisfy its python310.dll import.
+        python-version: "3.10"
+        architecture: x64
+        update-environment: false
+
     - name: Set up target Python 3.12 on Windows
       if: runner.os == 'Windows' && inputs.windows-arch != 'amd64'
       id: windows_target_python
@@ -48,7 +57,7 @@ runs:
       id: windows_lldb_python_386
       uses: actions/setup-python@v6
       with:
-        # LLVM's official 19.1.7 Win32 LLDB links python310.dll. Keep this
+        # LLVM's official 21.1.8 Win32 LLDB links python310.dll. Keep this
         # debugger runtime separate from the target Python 3.12 demo library.
         python-version: "3.10"
         architecture: x86
@@ -59,7 +68,7 @@ runs:
       id: windows_lldb_python
       uses: actions/setup-python@v6
       with:
-        # LLVM's official 19.1.7 Windows-on-Arm LLDB links python311.dll.
+        # LLVM's official 21.1.8 Windows-on-Arm LLDB links python311.dll.
         # 3.11.9 is the final ARM64 artifact in actions/python-versions.
         python-version: "3.11.9"
         architecture: arm64
@@ -89,6 +98,18 @@ runs:
         }
         Add-Content -Encoding utf8 $env:GITHUB_ENV "LLGO_WINDOWS_LLDB_PYTHON_HOME=$prefix"
 
+    - name: Configure LLDB Python on Windows amd64
+      if: runner.os == 'Windows' && inputs.windows-abi == 'msvc' && inputs.windows-arch == 'amd64'
+      shell: pwsh
+      run: |
+        $ErrorActionPreference = "Stop"
+        $python = "${{ steps.windows_lldb_python_amd64.outputs.python-path }}"
+        $prefix = (& $python -c "import sys; print(sys.base_prefix)").Trim()
+        if (-not (Test-Path (Join-Path $prefix "python310.dll"))) {
+          throw "The native x64 LLDB Python runtime is incomplete: $prefix"
+        }
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "LLGO_WINDOWS_LLDB_PYTHON_HOME=$prefix"
+
     - name: Install cargs demo library on Unix
       if: runner.os != 'Windows'
       shell: bash
@@ -256,7 +277,7 @@ runs:
       run: |
         $ErrorActionPreference = "Stop"
 
-        $hostPython = "${{ steps.windows_python.outputs.python-path }}"
+        $hostPython = "${{ steps.windows_python.outputs.python-path || steps.windows_target_python.outputs.python-path }}"
         $python = "${{ steps.windows_target_python.outputs.python-path || steps.windows_python.outputs.python-path }}"
         $packages = @("numpy")
         if ("${{ inputs.windows-arch }}" -eq "amd64") {

.github/actions/setup-goreleaser/action.yml

@@ -17,6 +17,9 @@ runs:
   steps:
     - name: Set up Go
       uses: ./.github/actions/setup-go
+    - name: Load LLVM payload contract
+      run: go run ./internal/llvmpayload/cmd/llvmpayload >> "$GITHUB_ENV"
+      shell: bash
     - name: Restore Linux sysroot cache
       id: cache-linux-sysroot
       uses: actions/cache/restore@v5
@@ -31,7 +34,7 @@ runs:
       uses: actions/cache/restore@v5
       with:
         path: ${{ inputs.esp-clang-cache-path }}
-        key: esp-clang-${{ hashFiles('.github/workflows/download_esp_clang.sh') }}
+        key: esp-clang-${{ hashFiles('.github/workflows/download_esp_clang.sh', 'internal/llvmpayload/**') }}
     - name: Download ESP Clang (if cache miss)
       if: steps.cache-esp-clang.outputs.cache-hit != 'true'
       run: bash .github/workflows/download_esp_clang.sh
@@ -41,7 +44,7 @@ runs:
       uses: actions/cache/save@v5
       with:
         path: ${{ inputs.esp-clang-cache-path }}
-        key: esp-clang-${{ hashFiles('.github/workflows/download_esp_clang.sh') }}
+        key: esp-clang-${{ hashFiles('.github/workflows/download_esp_clang.sh', 'internal/llvmpayload/**') }}
     - name: Check file
       run: tree .sysroot
       shell: bash

.github/actions/setup-llvm-mingw/action.yml

@@ -7,7 +7,7 @@ inputs:
   llvm-version:
     description: "LLGo host LLVM major version"
     required: false
-    default: "19"
+    default: "21"
 
 runs:
   using: "composite"
@@ -16,8 +16,8 @@ runs:
       if: runner.os == 'Windows'
       shell: pwsh
       run: |
-        if ("${{ inputs.llvm-version }}" -ne "19") {
-          throw "llvm-mingw 20250114 is paired with LLVM 19, not ${{ inputs.llvm-version }}"
+        if ("${{ inputs.llvm-version }}" -ne "21") {
+          throw "llvm-mingw 20251216 is paired with LLVM 21, not ${{ inputs.llvm-version }}"
         }
         if ("${{ inputs.windows-arch }}" -ne "386") {
           throw "The native llvm-mingw target currently qualifies windows/386, not windows/${{ inputs.windows-arch }}"
@@ -28,8 +28,8 @@ runs:
       shell: bash
       run: |
         set -euo pipefail
-        if [[ "${{ inputs.llvm-version }}" != 19 ]]; then
-          echo "llvm-mingw 20250114 is paired with LLVM 19, not ${{ inputs.llvm-version }}" >&2
+        if [[ "${{ inputs.llvm-version }}" != 21 ]]; then
+          echo "llvm-mingw 20251216 is paired with LLVM 21, not ${{ inputs.llvm-version }}" >&2
           exit 1
         fi
         case "${{ inputs.windows-arch }}" in
@@ -45,15 +45,15 @@ runs:
       id: llvm_mingw_cache
       uses: actions/cache/restore@v4
       with:
-        path: ${{ runner.tool_cache }}\llvm-mingw\20250114\ucrt-x86_64
-        key: llvm-mingw-20250114-ucrt-x86_64-9395d95c089611e6cd728c9a07219ffc5ac706e0c719833a2f7e64a706a81541
+        path: ${{ runner.tool_cache }}\llvm-mingw\20251216\ucrt-x86_64
+        key: llvm-mingw-20251216-ucrt-x86_64-2d96a4b758f7f8deaec5065833fe025aa53cfc5f704d0524002510984da0ccf4
 
     - name: Install llvm-mingw
       if: runner.os == 'Windows' && steps.llvm_mingw_cache.outputs.cache-hit != 'true'
       shell: pwsh
       env:
-        LLVM_MINGW_VERSION: "20250114"
-        LLVM_MINGW_SHA256: 9395d95c089611e6cd728c9a07219ffc5ac706e0c719833a2f7e64a706a81541
+        LLVM_MINGW_VERSION: "20251216"
+        LLVM_MINGW_SHA256: 2d96a4b758f7f8deaec5065833fe025aa53cfc5f704d0524002510984da0ccf4
       run: |
         $ErrorActionPreference = "Stop"
         $asset = "llvm-mingw-$env:LLVM_MINGW_VERSION-ucrt-x86_64.zip"
@@ -84,16 +84,16 @@ runs:
       if: runner.os == 'Windows' && steps.llvm_mingw_cache.outputs.cache-hit != 'true'
       uses: actions/cache/save@v4
       with:
-        path: ${{ runner.tool_cache }}\llvm-mingw\20250114\ucrt-x86_64
-        key: llvm-mingw-20250114-ucrt-x86_64-9395d95c089611e6cd728c9a07219ffc5ac706e0c719833a2f7e64a706a81541
+        path: ${{ runner.tool_cache }}\llvm-mingw\20251216\ucrt-x86_64
+        key: llvm-mingw-20251216-ucrt-x86_64-2d96a4b758f7f8deaec5065833fe025aa53cfc5f704d0524002510984da0ccf4
 
     - name: Restore llvm-mingw target dependencies
       if: runner.os == 'Windows'
       id: llvm_mingw_vcpkg_cache
       uses: actions/cache/restore@v4
       with:
         path: ${{ runner.tool_cache }}\llgo-mingw-vcpkg\${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}\386
-        key: llgo-llvm-mingw-20250114-ucrt-386-${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}
+        key: llgo-llvm-mingw-20251216-ucrt-386-${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}
 
     - name: Build llvm-mingw target dependencies
       if: runner.os == 'Windows' && steps.llvm_mingw_vcpkg_cache.outputs.cache-hit != 'true'
@@ -106,7 +106,7 @@ runs:
         $sourceRoot = Join-Path $env:RUNNER_TEMP "llgo-mingw-vcpkg-source"
         $installRoot = Join-Path $env:RUNNER_TOOL_CACHE "llgo-mingw-vcpkg\$env:VCPKG_MANIFEST_HASH\386"
         $manifestRoot = Join-Path $env:GITHUB_WORKSPACE ".github\windows\vcpkg"
-        $llvmMingwRoot = Join-Path $env:RUNNER_TOOL_CACHE "llvm-mingw\20250114\ucrt-x86_64"
+        $llvmMingwRoot = Join-Path $env:RUNNER_TOOL_CACHE "llvm-mingw\20251216\ucrt-x86_64"
         $llvmMingwBin = Join-Path $llvmMingwRoot "bin"
         $env:PATH = "$llvmMingwBin;$env:PATH"
 
@@ -137,7 +137,7 @@ runs:
       uses: actions/cache/save@v4
       with:
         path: ${{ runner.tool_cache }}\llgo-mingw-vcpkg\${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}\386
-        key: llgo-llvm-mingw-20250114-ucrt-386-${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}
+        key: llgo-llvm-mingw-20251216-ucrt-386-${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}
 
     - name: Configure llvm-mingw target
       if: runner.os == 'Windows'
@@ -146,7 +146,7 @@ runs:
         VCPKG_MANIFEST_HASH: ${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}
       run: |
         $ErrorActionPreference = "Stop"
-        $llvmMingwRoot = Join-Path $env:RUNNER_TOOL_CACHE "llvm-mingw\20250114\ucrt-x86_64"
+        $llvmMingwRoot = Join-Path $env:RUNNER_TOOL_CACHE "llvm-mingw\20251216\ucrt-x86_64"
         $llvmMingwBin = Join-Path $llvmMingwRoot "bin"
         $llvmMingwRuntimeBin = Join-Path $llvmMingwRoot "i686-w64-mingw32\bin"
         $compiler = Join-Path $llvmMingwBin "i686-w64-mingw32-clang.exe"
@@ -237,24 +237,24 @@ runs:
       id: cross_host_llvm_mingw_cache
       uses: actions/cache/restore@v4
       with:
-        path: ${{ runner.tool_cache }}/llvm-mingw/20250114/ucrt-${{ runner.os }}-${{ runner.arch }}
-        key: llvm-mingw-20250114-ucrt-${{ runner.os }}-${{ runner.arch }}-${{ runner.os == 'macOS' && '80b2e7ade71ba2dfe9e8d27fe47ae5738b1fb8d34e057faa2beef3070392f2d6' || 'a16f52dee819797248e6c7d63b8b1e50a92119f45767ecd8e9633d1733b896e2' }}
+        path: ${{ runner.tool_cache }}/llvm-mingw/20251216/ucrt-${{ runner.os }}-${{ runner.arch }}
+        key: llvm-mingw-20251216-ucrt-${{ runner.os }}-${{ runner.arch }}-${{ runner.os == 'macOS' && '38bb5e48ec3e0ce95fb901f4efff0bd6ffa966d1b32539a6510af816a959d160' || 'db561734a05eb4a0695d5e901aadd6c1cda74bba4c9e102b677f81c6fd59849a' }}
 
     - name: Install cross-host llvm-mingw
       if: runner.os != 'Windows' && env.LLGO_MINGW_CROSS_ROOT == '' && steps.cross_host_llvm_mingw_cache.outputs.cache-hit != 'true'
       shell: bash
       env:
-        LLVM_MINGW_VERSION: "20250114"
+        LLVM_MINGW_VERSION: "20251216"
       run: |
         set -euo pipefail
         case "$RUNNER_OS/$RUNNER_ARCH" in
           Linux/X64)
-            asset="llvm-mingw-${LLVM_MINGW_VERSION}-ucrt-ubuntu-20.04-x86_64.tar.xz"
-            sha256=a16f52dee819797248e6c7d63b8b1e50a92119f45767ecd8e9633d1733b896e2
+            asset="llvm-mingw-${LLVM_MINGW_VERSION}-ucrt-ubuntu-22.04-x86_64.tar.xz"
+            sha256=db561734a05eb4a0695d5e901aadd6c1cda74bba4c9e102b677f81c6fd59849a
             ;;
           macOS/ARM64|macOS/X64)
             asset="llvm-mingw-${LLVM_MINGW_VERSION}-ucrt-macos-universal.tar.xz"
-            sha256=80b2e7ade71ba2dfe9e8d27fe47ae5738b1fb8d34e057faa2beef3070392f2d6
+            sha256=38bb5e48ec3e0ce95fb901f4efff0bd6ffa966d1b32539a6510af816a959d160
             ;;
           *)
             echo "llvm-mingw has no qualified $RUNNER_OS/$RUNNER_ARCH host archive" >&2
@@ -288,16 +288,16 @@ runs:
       if: runner.os != 'Windows' && env.LLGO_MINGW_CROSS_ROOT == '' && steps.cross_host_llvm_mingw_cache.outputs.cache-hit != 'true'
       uses: actions/cache/save@v4
       with:
-        path: ${{ runner.tool_cache }}/llvm-mingw/20250114/ucrt-${{ runner.os }}-${{ runner.arch }}
-        key: llvm-mingw-20250114-ucrt-${{ runner.os }}-${{ runner.arch }}-${{ runner.os == 'macOS' && '80b2e7ade71ba2dfe9e8d27fe47ae5738b1fb8d34e057faa2beef3070392f2d6' || 'a16f52dee819797248e6c7d63b8b1e50a92119f45767ecd8e9633d1733b896e2' }}
+        path: ${{ runner.tool_cache }}/llvm-mingw/20251216/ucrt-${{ runner.os }}-${{ runner.arch }}
+        key: llvm-mingw-20251216-ucrt-${{ runner.os }}-${{ runner.arch }}-${{ runner.os == 'macOS' && '38bb5e48ec3e0ce95fb901f4efff0bd6ffa966d1b32539a6510af816a959d160' || 'db561734a05eb4a0695d5e901aadd6c1cda74bba4c9e102b677f81c6fd59849a' }}
 
     - name: Restore cross-host target dependencies
       if: runner.os != 'Windows'
       id: cross_host_vcpkg_cache
       uses: actions/cache/restore@v4
       with:
         path: ${{ runner.tool_cache }}/llgo-mingw-vcpkg/${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}/${{ runner.os }}-${{ runner.arch }}/${{ inputs.windows-arch }}
-        key: llgo-llvm-mingw-20250114-ucrt-${{ runner.os }}-${{ runner.arch }}-${{ inputs.windows-arch }}-${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}
+        key: llgo-llvm-mingw-20251216-ucrt-${{ runner.os }}-${{ runner.arch }}-${{ inputs.windows-arch }}-${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}
 
     - name: Build cross-host target dependencies
       if: runner.os != 'Windows' && steps.cross_host_vcpkg_cache.outputs.cache-hit != 'true'
@@ -316,7 +316,7 @@ runs:
         source_root="$RUNNER_TEMP/llgo-mingw-vcpkg-source"
         install_root="$RUNNER_TOOL_CACHE/llgo-mingw-vcpkg/$VCPKG_MANIFEST_HASH/${RUNNER_OS}-${RUNNER_ARCH}/${{ inputs.windows-arch }}"
         manifest_root="$GITHUB_WORKSPACE/.github/windows/vcpkg"
-        llvm_mingw_root="${LLGO_MINGW_CROSS_ROOT:-$RUNNER_TOOL_CACHE/llvm-mingw/20250114/ucrt-${RUNNER_OS}-${RUNNER_ARCH}}"
+        llvm_mingw_root="${LLGO_MINGW_CROSS_ROOT:-$RUNNER_TOOL_CACHE/llvm-mingw/20251216/ucrt-${RUNNER_OS}-${RUNNER_ARCH}}"
         export PATH="$llvm_mingw_root/bin:$PATH"
 
         # Do not let target-specific compiler variables from the invoking job
@@ -347,7 +347,7 @@ runs:
       uses: actions/cache/save@v4
       with:
         path: ${{ runner.tool_cache }}/llgo-mingw-vcpkg/${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}/${{ runner.os }}-${{ runner.arch }}/${{ inputs.windows-arch }}
-        key: llgo-llvm-mingw-20250114-ucrt-${{ runner.os }}-${{ runner.arch }}-${{ inputs.windows-arch }}-${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}
+        key: llgo-llvm-mingw-20251216-ucrt-${{ runner.os }}-${{ runner.arch }}-${{ inputs.windows-arch }}-${{ hashFiles('.github/windows/vcpkg/vcpkg.json') }}
 
     - name: Configure cross-host llvm-mingw target
       if: runner.os != 'Windows'
@@ -374,7 +374,7 @@ runs:
             ;;
         esac
 
-        llvm_mingw_root="${LLGO_MINGW_CROSS_ROOT:-$RUNNER_TOOL_CACHE/llvm-mingw/20250114/ucrt-${RUNNER_OS}-${RUNNER_ARCH}}"
+        llvm_mingw_root="${LLGO_MINGW_CROSS_ROOT:-$RUNNER_TOOL_CACHE/llvm-mingw/20251216/ucrt-${RUNNER_OS}-${RUNNER_ARCH}}"
         target_bin="$llvm_mingw_root/bin"
         runtime_bin="$llvm_mingw_root/$prefix/bin"
         compiler="$target_bin/$prefix-clang"

.github/actions/test-windows-cross/action.yml

@@ -10,7 +10,7 @@ inputs:
   llvm-version:
     description: "LLGo host LLVM major version"
     required: false
-    default: "19"
+    default: "21"
 
 runs:
   using: "composite"

.github/workflows/benchmark.yml

@@ -111,7 +111,7 @@ jobs:
       - name: Install dependencies
         uses: ./.github/actions/setup-deps
         with:
-          llvm-version: 19
+          llvm-version: 21
           windows-abi: ${{ matrix.windows_abi || 'msvc' }}
           windows-arch: ${{ matrix.windows_arch || 'amd64' }}
 
@@ -123,6 +123,11 @@ jobs:
       - name: Build host compilers for a cross-architecture benchmark
         if: runner.os == 'Windows' && matrix.windows_arch != 'amd64'
         shell: bash
+        # The checked-out baseline may still default its Go LLVM binding to an
+        # older major. Build both benchmark compilers against the LLVM 21 host
+        # toolchain installed for this job.
+        env:
+          GOFLAGS: -tags=llvm21
         run: |
           set -euo pipefail
           mkdir -p "$GITHUB_WORKSPACE/.benchmark"
@@ -201,7 +206,9 @@ jobs:
         # base contains Windows support.
         continue-on-error: ${{ startsWith(matrix.id, 'windows-') }}
         shell: bash
+        # Compare both revisions with the same LLVM 21 host toolchain.
         env:
+          GOFLAGS: -tags=llvm21
           LLGO_BENCHMARK_PREBUILT_LLGO: ${{ matrix.windows_arch && matrix.windows_arch != 'amd64' && '.benchmark/base-llgo.exe' || '' }}
         run: |
           benchmark/baseline/run.sh \

.github/workflows/build-cache.yml

@@ -22,14 +22,14 @@ jobs:
       matrix:
         include:
           - os: macos-latest
-            llvm: 19
+            llvm: 21
           - os: ubuntu-latest
-            llvm: 19
+            llvm: 21
           - os: windows-2022
-            llvm: 19
+            llvm: 21
             windows_abi: msvc
           - os: windows-2022
-            llvm: 19
+            llvm: 21
             windows_abi: mingw
     runs-on: ${{matrix.os}}
     steps:

.github/workflows/doc.yml

@@ -153,7 +153,7 @@ jobs:
           set -e
           set -x
           source doc/_readme/scripts/install_ubuntu.sh
-          echo "PATH=/usr/lib/llvm-19/bin:$PATH" >> $GITHUB_ENV
+          echo "PATH=/usr/lib/llvm-21/bin:$PATH" >> $GITHUB_ENV
 
       - name: Set up Python 3.12 on Windows
         if: startsWith(matrix.os, 'windows')