debug: allow supported targets to retain DWARF

.gitattributes

@@ -0,0 +1,5 @@
+**/expect.txt text eol=lf
+**/out.txt text eol=lf
+*.ll text eol=lf
+*.sh text eol=lf
+_demo/go/export/libexport.h.want text eol=lf

.github/CI.md

@@ -0,0 +1,83 @@
+# Shared CI policy
+
+Workflows call `ci-prepare.yml` as their `prepare` job. Its outputs are job
+outputs, not environment variables: consumers declare `needs: prepare` and use
+`needs.prepare.outputs.run_code_ci == 'true'` or
+`needs.prepare.outputs.run_doc_checks == 'true'`. Existing artifact dependencies
+must stay in `needs` alongside `prepare`.
+
+The implementation is in `scripts/ci_policy.py`. Keep change rules there rather
+than adding path filters or independent diff commands to individual workflows.
+Each workflow executes its own small prepare job; the rule implementation is
+shared. The prepare job needs only Git and Python, not the LLGo toolchain. On a
+PR, it loads both `ci_policy.py` and `ci_changes.py` from the event's base
+commit, so edits to those modules in the PR cannot change this step's skip
+decision. If either base file is unavailable (including before this policy lands
+on main), prepare enables both suites. Main, tags and manual runs execute the
+checked-out policy and enable both suites.
+
+## Execution decisions
+
+- Only `pull_request` runs may skip checks. Pushes to main, tag builds, scheduled
+  runs and manual runs enable both outputs without inspecting a diff. This does
+  not add new triggers to schedule-only workflows or enable tag-only publishing
+  on branches.
+- A PR is compared from the merge base of its event base/head SHAs to its head,
+  including every commit and every changed path. Changes subsequently pushed to
+  the base branch do not alter that comparison.
+- Added/modified, regular non-executable `.md`, `.markdown` and `.rst` files are
+  prose. Other extensions and unknown paths require code CI. `doc/_readme/**`
+  and `testdata` directories are code/test inputs even when named Markdown.
+- Documentation changes, README example inputs and `.github/**` changes enable
+  document checks. The existing check still verifies README embedded sources
+  and README links; this policy does not expand its scanning scope.
+- Deletions, renames and type changes run both suites because they can remove
+  linked files or packaged documents. Unavailable or invalid PR diffs also run
+  both suites, with a warning. An empty diff is handled conservatively.
+- The **Docs** workflow installs LLGo and executes examples, so it consumes
+  `run_code_ci`, not `run_doc_checks`.
+
+Prepare also exports `pr_head_sha` and `pr_merge_base` for benchmark consumers.
+These are empty on non-PR events. If PR Git history cannot be resolved, code CI
+is enabled but benchmark consumers must reject an empty merge base rather than
+silently measuring a different commit.
+
+## Runners and concurrency
+
+`linux_runner` and `linux_large_runner` contain JSON runner labels. The upstream
+`xgo-dev` repository uses its qiniu runners; workflows running in forks use
+GitHub-hosted Ubuntu 24.04. Consume them with `fromJSON(...)`. Public-network
+link checks and release packaging keep their explicitly selected hosted runners.
+Windows and macOS platform matrices remain in their owning workflows.
+
+PR updates share a concurrency group and cancel superseded runs. Main and tag
+runs use `github.run_id` in their group so later commits neither cancel running
+checks nor replace pending checks. Workflow-level concurrency cannot consume
+prepare outputs; `test_ci_workflows.py` enforces the common expression instead.
+The reusable prepare workflow has no concurrency group of its own.
+
+Every workflow that uses prepare has a uniquely named `CI gate (...)` job. It
+runs even if prepare fails and reports that failure. Branch protection should
+require the gates for PR workflows, the relevant code/document checks, and
+**CI policy**. Requiring only downstream jobs does not distinguish a prepare
+failure from an intentional docs-only skip. The gate checks preparation, not
+the result of every downstream job; it does not replace those required checks.
+
+The benchmark publisher checks the triggering run's artifacts separately for
+native and WASM results before invoking either publisher. A successful docs-only
+run has no benchmark artifacts and is a normal no-op. External benchmark
+notifications run for every upstream main push, including documentation changes.
+
+## Validation
+
+The independent **CI policy** workflow runs on every PR and main push. It tests
+Git histories, failure fallbacks, runner selection, output propagation, matrix
+coverage, release dependencies, main concurrency, and missing benchmark artifacts.
+It is deliberately not gated by the code it validates.
+
+Locally, install `scripts/requirements-ci.txt` in a Python environment and run:
+
+```sh
+python -m unittest discover -s .github/scripts -p 'test_*.py' -v
+actionlint -shellcheck= .github/workflows/*.yml
+```

.github/actions/activate-windows-target/action.yml

@@ -0,0 +1,197 @@
+name: "Activate Windows Target"
+description: "Switch a built LLGo host compiler to an architecture-matched Windows target environment"
+inputs:
+  windows-abi:
+    description: "Native Windows toolchain profile"
+    required: false
+    default: "msvc"
+  windows-arch:
+    description: "Windows target GOARCH"
+    required: false
+    default: "amd64"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Record and isolate the host compiler when available
+      if: runner.os == 'Windows'
+      shell: pwsh
+      run: |
+        $ErrorActionPreference = "Stop"
+        # GOROOT exposes its explicitly built compiler through LLGO_TEST_LLGO.
+        # Shared test jobs install llgo on PATH and reuse it whenever a
+        # target-native test launches the compiler as a subprocess.
+        $hostCompiler = Get-Command llgo.exe -ErrorAction SilentlyContinue
+        $hostCompilerPath = if ($env:LLGO_TEST_LLGO -and (Test-Path $env:LLGO_TEST_LLGO)) {
+          (Resolve-Path $env:LLGO_TEST_LLGO).Path
+        } elseif ($null -ne $hostCompiler) {
+          $hostCompiler.Source
+        }
+        if ($hostCompilerPath) {
+          if ("${{ inputs.windows-abi }}" -eq "mingw" -and "${{ inputs.windows-arch }}" -eq "386") {
+            $hostBin = Join-Path $env:LLGO_MINGW_HOST_ROOT "bin"
+            $objdump = Join-Path $hostBin "llvm-objdump.exe"
+            if (-not (Test-Path $objdump)) {
+              throw "The MinGW host llvm-objdump is unavailable: $objdump"
+            }
+
+            # The x86 target DLL directories must precede the x64 host on PATH
+            # when generated programs run. Put the host compiler's DLL closure
+            # beside llgo.exe so Windows resolves it before consulting PATH.
+            $compilerDir = Split-Path $hostCompilerPath
+            $queue = [Collections.Generic.Queue[string]]::new()
+            $queue.Enqueue($hostCompilerPath)
+            $copied = @{}
+            while ($queue.Count -ne 0) {
+              $binary = $queue.Dequeue()
+              foreach ($line in (& $objdump -p $binary)) {
+                if ($line -notmatch '^\s*DLL Name:\s*(\S+)\s*$') {
+                  continue
+                }
+                $name = $Matches[1]
+                if ($copied.ContainsKey($name)) {
+                  continue
+                }
+                $source = Join-Path $hostBin $name
+                if (-not (Test-Path $source)) {
+                  continue
+                }
+                $destination = Join-Path $compilerDir $name
+                Copy-Item -LiteralPath $source -Destination $destination -Force
+                $copied[$name] = $true
+                $queue.Enqueue($destination)
+              }
+            }
+            if ($copied.Count -eq 0) {
+              throw "No MinGW host runtime DLLs were discovered for $hostCompilerPath"
+            }
+          }
+          Add-Content -Encoding utf8 $env:GITHUB_ENV "LLGO_TEST_COMPILER=$hostCompilerPath"
+        }
+
+    - name: Activate Windows MSVC target
+      if: runner.os == 'Windows' && inputs.windows-abi == 'msvc'
+      shell: pwsh
+      run: |
+        $ErrorActionPreference = "Stop"
+        . (Join-Path $env:GITHUB_WORKSPACE ".github\windows\msvc-target.ps1")
+        $target = Enter-LLGoVisualStudio -GoArch "${{ inputs.windows-arch }}"
+
+        if ($env:LLGO_WINDOWS_TARGET_TRIPLE -ne $target.Triple) {
+          throw "Configured target $env:LLGO_WINDOWS_TARGET_TRIPLE does not match $($target.Triple)"
+        }
+        if ($env:LLGO_WINDOWS_VCPKG_TRIPLET -ne $target.VcpkgTriplet) {
+          throw "Configured vcpkg triplet $env:LLGO_WINDOWS_VCPKG_TRIPLET does not match $($target.VcpkgTriplet)"
+        }
+        if (-not (Test-Path (Join-Path $env:LLGO_WINDOWS_VCPKG_ROOT "include\gc\gc.h"))) {
+          throw "The $($target.VcpkgTriplet) dependency installation is incomplete"
+        }
+
+        Export-LLGoVisualStudioEnvironment
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "CC=clang --target=$($target.Triple) -fuse-ld=lld -fms-runtime-lib=dll"
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "CXX=clang++ --target=$($target.Triple) -fuse-ld=lld -fms-runtime-lib=dll -std=c++17"
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "GOOS=windows"
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "GOARCH=$($target.GoArch)"
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "LLGO_WINDOWS_TARGET_ACTIVE=1"
+        Add-Content -Encoding utf8 $env:GITHUB_PATH (Join-Path $env:LLGO_WINDOWS_VCPKG_ROOT "bin")
+
+    - name: Activate Windows GNU target
+      if: runner.os == 'Windows' && inputs.windows-abi == 'mingw'
+      shell: pwsh
+      run: |
+        $ErrorActionPreference = "Stop"
+        $goArch = "${{ inputs.windows-arch }}"
+        $targetArch = switch ($goArch) {
+          "386" { "i686" }
+          "amd64" { "x86_64|amd64" }
+          "arm64" { "aarch64" }
+          default { throw "Unsupported Windows GNU target architecture: $goArch" }
+        }
+        $cc = "clang"
+        $cxx = "clang++"
+
+        if ($goArch -eq "386") {
+          foreach ($name in @("LLGO_MINGW_TARGET_BIN", "LLGO_MINGW_TARGET_RUNTIME_BIN", "LLGO_MINGW_TARGET_TOOLS", "LLGO_MINGW_TARGET_TRIPLE", "LLGO_MINGW_TARGET_VCPKG_ROOT")) {
+            $value = [Environment]::GetEnvironmentVariable($name)
+            if (-not $value) {
+              throw "The standalone llvm-mingw target did not export $name"
+            }
+          }
+          $compiler = Join-Path $env:LLGO_MINGW_TARGET_BIN "i686-w64-mingw32-clang.exe"
+          $compilerXX = Join-Path $env:LLGO_MINGW_TARGET_BIN "i686-w64-mingw32-clang++.exe"
+          foreach ($path in @($compiler, $compilerXX)) {
+            if (-not (Test-Path $path)) {
+              throw "The standalone llvm-mingw target compiler was not found: $path"
+            }
+          }
+          $target = (& $compiler -dumpmachine).Trim()
+          if ($target -notmatch "^$targetArch-.*-(windows-gnu|mingw32)$") {
+            throw "llvm-mingw reports $target, want windows/$goArch GNU"
+          }
+          # GITHUB_PATH prepends entries in reverse write order. Keep the
+          # target-selecting clang/pkg-config wrappers ahead of the bundle's
+          # unqualified x64 host commands for all subsequent steps.
+          Add-Content -Encoding utf8 $env:GITHUB_PATH $env:LLGO_MINGW_TARGET_BIN
+          Add-Content -Encoding utf8 $env:GITHUB_PATH $env:LLGO_MINGW_TARGET_RUNTIME_BIN
+          Add-Content -Encoding utf8 $env:GITHUB_PATH $env:LLGO_MINGW_TARGET_TOOLS
+          Add-Content -Encoding utf8 $env:GITHUB_PATH (Join-Path $env:LLGO_MINGW_TARGET_VCPKG_ROOT "bin")
+          # Keep the wrappers for interactive shells, but let LLGo invoke the
+          # drivers directly. A normal runtime link can exceed cmd.exe's 8191
+          # character limit while remaining below LLGo's 30 KiB response-file
+          # threshold.
+          $cc = $compiler
+          $cxx = $compilerXX
+        } else {
+          $target = (& clang.exe -dumpmachine).Trim()
+          if ($target -notmatch "^$targetArch-.*-(windows-gnu|mingw32)$") {
+            throw "MSYS2 Clang reports $target, want windows/$goArch GNU"
+          }
+        }
+
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "CC=$cc"
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "CXX=$cxx"
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "GOOS=windows"
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "GOARCH=$goArch"
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "LLGO_WINDOWS_TARGET_ACTIVE=1"
+
+    - name: Activate cross-host Windows GNU target
+      if: runner.os != 'Windows' && inputs.windows-abi == 'mingw'
+      shell: bash
+      run: |
+        set -euo pipefail
+        for name in \
+          LLGO_MINGW_TARGET_BIN \
+          LLGO_MINGW_TARGET_RUNTIME_BIN \
+          LLGO_MINGW_TARGET_TOOLS \
+          LLGO_MINGW_TARGET_TRIPLE \
+          LLGO_MINGW_TARGET_VCPKG_ROOT; do
+          if [[ -z "${!name:-}" ]]; then
+            echo "the cross-host llvm-mingw target did not export $name" >&2
+            exit 1
+          fi
+        done
+
+        target="$(${LLGO_MINGW_TARGET_TOOLS}/clang -dumpmachine)"
+        case "${{ inputs.windows-arch }}:$target" in
+          386:i686-*-windows-gnu|386:i686-*-mingw32) ;;
+          amd64:x86_64-*-windows-gnu|amd64:x86_64-*-mingw32) ;;
+          arm64:aarch64-*-windows-gnu|arm64:aarch64-*-mingw32) ;;
+          *)
+            echo "llvm-mingw reports $target for windows/${{ inputs.windows-arch }}" >&2
+            exit 1
+            ;;
+        esac
+
+        # Only expose the target-selecting wrappers. The compiler locates its
+        # own CRT by absolute path, target DLLs cannot run on this Unix host,
+        # and vcpkg contributes link flags through the pkg-config wrapper.
+        # This prevents llvm-mingw's unqualified host tools from shadowing the
+        # LLVM installation used to build the LLGo compiler itself.
+        echo "$LLGO_MINGW_TARGET_TOOLS" >> "$GITHUB_PATH"
+        echo "CC=$LLGO_MINGW_TARGET_TOOLS/clang" >> "$GITHUB_ENV"
+        echo "CXX=$LLGO_MINGW_TARGET_TOOLS/clang++" >> "$GITHUB_ENV"
+        echo "PKG_CONFIG=$LLGO_MINGW_TARGET_TOOLS/pkg-config" >> "$GITHUB_ENV"
+        echo "CGO_ENABLED=1" >> "$GITHUB_ENV"
+        echo "GOOS=windows" >> "$GITHUB_ENV"
+        echo "GOARCH=${{ inputs.windows-arch }}" >> "$GITHUB_ENV"
+        echo "LLGO_WINDOWS_TARGET_ACTIVE=1" >> "$GITHUB_ENV"

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

@@ -0,0 +1,96 @@
+name: "Setup Binaryen"
+description: "Install a pinned Binaryen release"
+inputs:
+  version:
+    description: "LLGo Binaryen release tag; update checksums.txt together"
+    required: false
+    default: "llgo-v132.3"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install Binaryen
+      if: runner.os != 'Windows'
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        version="${{ inputs.version }}"
+        case "$(uname -s):$(uname -m)" in
+          Linux:x86_64) platform="x86_64-linux" ;;
+          Linux:aarch64|Linux:arm64) platform="aarch64-linux" ;;
+          Darwin:x86_64) platform="x86_64-macos" ;;
+          Darwin:arm64) platform="arm64-macos" ;;
+          *)
+            echo "Unsupported Binaryen host: $(uname -s) $(uname -m)" >&2
+            exit 1
+            ;;
+        esac
+
+        archive="binaryen-${version}-${platform}.tar.gz"
+        base_url="https://github.com/xgo-dev/binaryen/releases/download/${version}"
+        expected="$(awk -v platform="$platform" '$1 == platform { print $2 }' "$GITHUB_ACTION_PATH/checksums.txt")"
+        if [[ ! "$expected" =~ ^[0-9a-fA-F]{64}$ ]]; then
+          echo "Missing or invalid pinned Binaryen checksum for $platform" >&2
+          exit 1
+        fi
+        cd "$RUNNER_TEMP"
+        curl --retry 3 --retry-all-errors -fsSLO "${base_url}/${archive}"
+        if command -v sha256sum >/dev/null; then
+          printf '%s  %s\n' "$expected" "$archive" | sha256sum --check -
+        else
+          printf '%s  %s\n' "$expected" "$archive" | shasum -a 256 --check -
+        fi
+        tar -xzf "$archive" -C "$RUNNER_TEMP"
+        binaryen_root="$RUNNER_TEMP/binaryen-${version}"
+        test -x "$binaryen_root/bin/wasm-opt"
+        test -x "$binaryen_root/bin/wasm-emscripten-finalize"
+        echo "Binaryen root: $binaryen_root"
+        "$binaryen_root/bin/wasm-opt" --version
+        "$binaryen_root/bin/wasm-emscripten-finalize" --version
+        echo "EM_BINARYEN_ROOT=$binaryen_root" >> "$GITHUB_ENV"
+        echo "WASMOPT=$binaryen_root/bin/wasm-opt" >> "$GITHUB_ENV"
+        echo "$binaryen_root/bin" >> "$GITHUB_PATH"
+
+    - name: Install Binaryen on Windows
+      if: runner.os == 'Windows'
+      shell: pwsh
+      run: |
+        $ErrorActionPreference = "Stop"
+        $version = "${{ inputs.version }}"
+        $platform = switch ($env:PROCESSOR_ARCHITECTURE) {
+          "AMD64" { "x86_64-windows" }
+          "ARM64" { "arm64-windows" }
+          default { throw "Unsupported Binaryen Windows host: $env:PROCESSOR_ARCHITECTURE" }
+        }
+        $archive = "binaryen-$version-$platform.tar.gz"
+        $baseUrl = "https://github.com/xgo-dev/binaryen/releases/download/$version"
+        $archivePath = Join-Path $env:RUNNER_TEMP $archive
+        $checksumRows = @(Get-Content -LiteralPath (Join-Path $env:GITHUB_ACTION_PATH "checksums.txt") |
+          Where-Object { ($_ -split '\s+')[0] -eq $platform })
+        if ($checksumRows.Count -ne 1) { throw "Missing pinned Binaryen checksum for $platform" }
+        $expected = ($checksumRows[0] -split '\s+')[1]
+        if ($expected -notmatch '^[0-9a-fA-F]{64}$') { throw "Invalid pinned Binaryen checksum for $platform" }
+        & curl.exe --fail --location --retry 3 --retry-all-errors --output $archivePath "$baseUrl/$archive"
+        if ($LASTEXITCODE -ne 0) { throw "Downloading Binaryen failed with exit code $LASTEXITCODE" }
+        $actual = (Get-FileHash -Algorithm SHA256 -LiteralPath $archivePath).Hash
+        if (-not $actual.Equals($expected, [StringComparison]::OrdinalIgnoreCase)) {
+          throw "Binaryen archive SHA-256 is $actual, want $expected"
+        }
+        & tar.exe -xzf $archivePath -C $env:RUNNER_TEMP
+        if ($LASTEXITCODE -ne 0) { throw "Extracting Binaryen failed with exit code $LASTEXITCODE" }
+        $binaryenRoot = Join-Path $env:RUNNER_TEMP "binaryen-$version"
+        $binaryenBin = Join-Path $binaryenRoot "bin"
+        $wasmOpt = Join-Path $binaryenBin "wasm-opt.exe"
+        $finalize = Join-Path $binaryenBin "wasm-emscripten-finalize.exe"
+        if (-not (Test-Path $wasmOpt) -or -not (Test-Path $finalize)) {
+          throw "Binaryen archive is missing wasm-opt or wasm-emscripten-finalize in $binaryenBin"
+        }
+        Write-Host "Binaryen root: $binaryenRoot"
+        & $wasmOpt --version
+        if ($LASTEXITCODE -ne 0) { throw "wasm-opt --version failed with exit code $LASTEXITCODE" }
+        & $finalize --version
+        if ($LASTEXITCODE -ne 0) { throw "wasm-emscripten-finalize --version failed with exit code $LASTEXITCODE" }
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "EM_BINARYEN_ROOT=$binaryenRoot"
+        Add-Content -Encoding utf8 $env:GITHUB_ENV "WASMOPT=$wasmOpt"
+        Add-Content -Encoding utf8 $env:GITHUB_PATH $binaryenBin

.github/actions/setup-binaryen/checksums.txt

@@ -0,0 +1,8 @@
+# SHA-256 of xgo-dev/binaryen llgo-v132.3 release archives.
+# Format: platform SHA-256. Verified against release assets and .sha256 files.
+aarch64-linux d7fe6f6558bd668f5bea3c64fd700885854a4847c023cf7a3ce3286158fd077d
+arm64-macos 06427b4fdd36a97d28ac5d7d1826a1aaa8af5393a3e4d50cf4f8017462f38b73
+arm64-windows 58553d04ab8e67e4b741fb946e444ea11622dda53893054513559f21cbb0c7b8
+x86_64-linux c82c9cbf5f53d17f01ca66b40ddd1f2e87dc34591ca562ef4c411824997e5bf8
+x86_64-macos 0cef8ddc4c59d7819b92c79be01c7655fd5f244494af474a7a31ed29a05a170c
+x86_64-windows b20b4c06fb1ae4da6461f5387958979733c741e6e4a437a31a2821ae6e40bb53