build.yml

name: build

# ONE BUILD OF THIS COMMIT'S MCPP PER HOST (rule R1 of
# .agents/docs/2026-10-02-pr-ci-acceleration-and-the-toolchain-specification-design.md).
#
# Called by ci.yml once per host. The binary is uploaded as the artifact
# `mcpp-built-<host>`, and every job of the commit that needs this commit's mcpp
# takes it with .github/actions/use-built-mcpp instead of building its own.
# Measured before this workflow existed (2026-10-01): thirty to thirty-seven
# jobs per commit built mcpp from source, which was 44 to 49 percent of the
# commit's runner minutes, and none of those builds was incremental.
#
# This job is also the ONE WRITER of the host's sandbox and xlings caches (rule
# R3), and it writes them only on a push to main. Before it saves, it installs
# the toolchains its consumers need, so that the cache a pull request restores
# already holds them.

on:
  workflow_call:
    inputs:
      host:
        description: linux-x86_64, linux-aarch64, macos-arm64 or windows-x86_64
        type: string
        required: true
      runs-on:
        description: the runner label
        type: string
        required: true
      prewarm:
        description: >
          Toolchains installed before the caches are saved on main, separated
          by ';', each as `mcpp toolchain install` takes it (`gcc 16.1.0-musl`).
        type: string
        required: false
        default: ''

jobs:
  build:
    name: build mcpp (${{ inputs.host }})
    runs-on: ${{ inputs.runs-on }}
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v4

      - id: boot
        if: ${{ !startsWith(inputs.host, 'macos-') }}
        uses: ./.github/actions/bootstrap-mcpp

      - id: mac
        if: ${{ startsWith(inputs.host, 'macos-') }}
        uses: ./.github/actions/setup-macos-llvm
        with:
          image: ${{ inputs.runs-on }}

      - name: Build mcpp from source (self-host)
        shell: bash
        run: |
          set -euo pipefail
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          "$XLINGS_BIN" config --mirror GLOBAL 2>/dev/null || true
          "$MCPP" self config --mirror GLOBAL 2>/dev/null || true
          "$MCPP" build
          # target/ is not restored from a cache, so the tree holds exactly the
          # binary this build linked.
          case "${{ inputs.host }}" in windows-*) exe=mcpp.exe ;; *) exe=mcpp ;; esac
          built=$(find target -type f -name "$exe" -path '*/bin/*' | grep -v '/dist/' || true)
          [ "$(printf '%s\n' "$built" | grep -c .)" = 1 ] || {
            echo "::error::expected one $exe under target/, found: ${built:-none}"; exit 1; }
          mkdir -p dist
          cp "$built" "dist/$exe"
          "dist/$exe" --version

      - name: Upload this commit's mcpp
        timeout-minutes: 5
        uses: actions/upload-artifact@v4
        with:
          name: mcpp-built-${{ inputs.host }}
          path: dist/${{ startsWith(inputs.host, 'windows-') && 'mcpp.exe' || 'mcpp' }}
          if-no-files-found: error
          retention-days: 3

      # Only on main, and only for the caches this job restored: a pull request
      # reads the main lineage and adds nothing to the store.
      - name: Install the toolchains the consumers use
        if: ${{ github.event_name == 'push' && inputs.prewarm != '' }}
        shell: bash
        run: |
          set -euo pipefail
          IFS=';' read -ra specs <<< "${{ inputs.prewarm }}"
          for spec in "${specs[@]}"; do
            spec="$(echo "$spec" | xargs)"
            [ -n "$spec" ] || continue
            echo "::group::mcpp toolchain install $spec"
            # shellcheck disable=SC2086 -- a spec is `<name> <version>`
            "$MCPP" toolchain install $spec
            echo "::endgroup::"
          done

      - name: Save the sandbox cache
        if: ${{ github.event_name == 'push' && steps.boot.outcome == 'success' && steps.boot.outputs.sandbox-hit != 'true' }}
        uses: actions/cache/save@v4
        with:
          path: ~/.mcpp
          key: ${{ steps.boot.outputs.sandbox-key }}

      - name: Save the xlings cache
        if: ${{ github.event_name == 'push' && steps.boot.outcome == 'success' && steps.boot.outputs.xlings-hit != 'true' }}
        uses: actions/cache/save@v4
        with:
          path: ~/.xlings
          key: ${{ steps.boot.outputs.xlings-key }}

      # macOS keeps no sandbox cache: setup-macos-llvm builds the sandbox from
      # the freshly resolved LLVM on every run, which is what the macOS jobs
      # exist to prove. Its xlings cache has this job as its writer.
      - name: Save the xlings cache (macOS)
        if: ${{ github.event_name == 'push' && steps.mac.outcome == 'success' && steps.mac.outputs.xlings-hit != 'true' }}
        uses: actions/cache/save@v4
        with:
          path: ~/.xlings
          key: ${{ steps.mac.outputs.xlings-key }}