ci-build.yml

#
# Licensed under the Apache License v2.0 with LLVM Exceptions.
# See https://llvm.org/LICENSE.txt for license information.
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
#
# Copyright (c) 2026 Alan de Freitas (alandefreitas@gmail.com)
#
# Official repository: https://github.com/cppalliance/mrdocs
#

name: Build & Test

on:
  workflow_call:
    inputs:
      matrix:
        description: 'JSON-encoded build matrix from cpp-matrix'
        type: string
        required: true

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJSON(inputs.matrix) }}

    defaults:
      run:
        shell: bash

    name: ${{ matrix.name }}
    runs-on: ${{ matrix.runs-on }}
    container: ${{ matrix.container }}
    env: ${{ matrix.env }}
    steps:
      - name: Container Bootstrap
        uses: alandefreitas/cpp-actions/container-bootstrap@v1.9.5

      - name: Setup C++
        uses: alandefreitas/cpp-actions/setup-cpp@v1.9.5
        id: setup-cpp
        with:
          compiler: ${{ matrix.compiler }}
          version: ${{ matrix.version }}

      - name: Install System Packages
        uses: alandefreitas/cpp-actions/package-install@v1.9.5
        id: package-install
        with:
          packages: ${{ matrix.install }}
          apt-get-source-keys: ${{ matrix.coverage && 'https://apt.llvm.org/llvm-snapshot.gpg.key' || '' }}
          apt-get-sources: ${{ matrix.coverage && 'deb https://apt.llvm.org/noble/ llvm-toolchain-noble-21 main' || '' }}

      - name: Clone MrDocs
        uses: actions/checkout@v6

      - name: Restore LLVM Cache
        id: llvm-cache
        uses: actions/cache/restore@v5
        with:
          path: build/third-party/install/llvm
          key: ${{ matrix.llvm-cache-key }}

      # Install third-party deps (LLVM, JerryScript, Lua, Boost, libxml2).
      # --skip-build: only install deps, the MrDocs build is done by cmake-workflow.
      # --cache-dir: flatten install paths to <dir>/<lib> for stable cache keys.
      # --env-file: write _ROOT paths so we can inject them into GITHUB_ENV.
      # Bootstrap writes BOOTSTRAP_REBUILT=<list> when it rebuilds any recipe.
      - name: Bootstrap Dependencies
        run: |
          python3 bootstrap.py --yes \
            --skip-build --no-run-configs \
            --build-type "${{ matrix.build-type }}" \
            --cc "${{ steps.setup-cpp.outputs.cc || matrix.cc }}" \
            --cxx "${{ steps.setup-cpp.outputs.cxx || matrix.cxx }}" \
            --cache-dir build/third-party/install \
            --env-file "$RUNNER_TEMP/bootstrap-env.txt" \
            ${{ matrix.bootstrap-sanitizer && format('--sanitizer {0}', matrix.bootstrap-sanitizer) || '' }} \
            ${{ matrix.common-ccflags && format('--cflags="{0}" --cxxflags="{0}"', matrix.common-ccflags) || '' }}
          cat "$RUNNER_TEMP/bootstrap-env.txt" >> "$GITHUB_ENV"
          # mrdocs install prefix, reused for the install and the consumer test
          echo "MRDOCS_PREFIX=${GITHUB_WORKSPACE//\\//}/.local" >> "$GITHUB_ENV"

      # Save the LLVM cache when bootstrap rebuilt it (cache miss or
      # stale stamp). BOOTSTRAP_REBUILT lists rebuilt recipes.
      #
      # Only runs on develop do this. GitHub scopes a cache entry to the ref
      # that saved it, and a run can only read entries from its own ref, a
      # PR's base ref, and the default branch. develop is the default branch,
      # so an entry saved here is the one every PR, merge-queue run, master
      # run, and tag run can read. An entry saved from master, a tag, or a
      # PR is visible to that ref alone and only eats cache quota, while a
      # key-wide delete from such a run would remove the shared entry and
      # give nothing back in its place (master is always a fast-forward of
      # develop, so it never has anything develop lacks). `actions/cache/save`
      # cannot overwrite an existing key, hence the explicit delete first;
      # the `ref` filter limits even that to develop's own entry.
      - name: Delete Stale LLVM Cache
        if: |
          contains(env.BOOTSTRAP_REBUILT, 'llvm')
          && steps.llvm-cache.outputs.cache-hit == 'true'
          && github.ref == 'refs/heads/develop'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          code=$(curl -s -o /dev/null -w "%{http_code}" -X DELETE \
            -H "Authorization: Bearer $GH_TOKEN" \
            "$GITHUB_API_URL/repos/$GITHUB_REPOSITORY/actions/caches?key=${{ matrix.llvm-cache-key }}&ref=refs/heads/develop")
          case "$code" in
            200) echo "Deleted old cache for key ${{ matrix.llvm-cache-key }}" ;;
            404) echo "No existing cache for key ${{ matrix.llvm-cache-key }}" ;;
            403) echo "::warning::Skipping cache delete: token lacks actions:write (HTTP 403)" ;;
            *)   echo "::error::Failed to delete cache (HTTP $code)"; exit 1 ;;
          esac

      - name: Save Updated LLVM Cache
        if: |
          contains(env.BOOTSTRAP_REBUILT, 'llvm')
          && github.ref == 'refs/heads/develop'
        uses: actions/cache/save@v5
        with:
          path: build/third-party/install/llvm
          key: ${{ matrix.llvm-cache-key }}

      - name: CMake Workflow
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.9.5
        with:
          cmake-version: '>=3.26'
          cxxstd: ${{ matrix.cxxstd }}
          cc: ${{ steps.setup-cpp.outputs.cc || matrix.cc }}
          ccflags: ${{ matrix.ccflags }}
          cxx: ${{ steps.setup-cpp.outputs.cxx || matrix.cxx }}
          cxxflags: ${{ matrix.cxxflags }} ${{ env.BOOTSTRAP_CXXFLAGS }}
          ldflags: ${{ env.BOOTSTRAP_LDFLAGS }}
          generator: Ninja
          build-dir: build/mrdocs
          build-type: ${{ matrix.build-type }}
          install-prefix: ${{ env.MRDOCS_PREFIX }}
          export-compile-commands: true
          run-tests: true
          install: true
          package: ${{ matrix.is-main }}
          package-dir: ../packages
          package-generators: ${{ matrix.mrdocs-package-generators }}
          package-artifact: false
          ctest-timeout: 9000

      # Consume the freshly installed mrdocs through its exported CMake package,
      # from an out-of-tree project (tests/cmake): find_package(mrdocs), link
      # mrdocs::mrdocs-core, and run the installed binary via MRDOCS_EXECUTABLE.
      # This is the only coverage of mrdocs-as-a-library, so it runs on every
      # normal build, on every platform (the default static library bundles its
      # private toolchain, so this is where we prove a consumer links it with no
      # LLVM/Clang/JerryScript/Lua present). It goes through the same
      # cmake-workflow action as the main build (configure + build + ctest),
      # pointed at tests/cmake, discovering the install through mrdocs_ROOT -- the
      # package-specific find_package hint rather than CMAKE_PREFIX_PATH, so the
      # <PackageName>_ROOT search path is exercised. Only the ABI flags mrdocs was
      # built with are reused (the consumer must match the same standard library),
      # not mrdocs's own -Werror/-static/-WX matrix flags. Coverage/sanitizer
      # builds use instrumented toolchains an out-of-tree consumer would have to
      # mirror exactly, so those are skipped. mrdocs_ROOT gets the MRDOCS_PREFIX
      # resolved above.
      - name: CMake Consumer Test (cmake test)
        if: ${{ !matrix.coverage && !matrix.bootstrap-sanitizer }}
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.9.5
        with:
          cmake-version: '>=3.26'
          source-dir: tests/cmake
          build-dir: build/cmake-consumer
          cxxstd: ${{ matrix.cxxstd }}
          cc: ${{ steps.setup-cpp.outputs.cc || matrix.cc }}
          cxx: ${{ steps.setup-cpp.outputs.cxx || matrix.cxx }}
          cxxflags: ${{ env.BOOTSTRAP_CXXFLAGS }}
          ldflags: ${{ env.BOOTSTRAP_LDFLAGS }}
          generator: Ninja
          build-type: ${{ matrix.build-type }}
          extra-args: -D mrdocs_ROOT=${{ env.MRDOCS_PREFIX }}
          run-tests: true
          install: false

      - name: CMake Consumer Test (library example)
        if: ${{ !matrix.coverage && !matrix.bootstrap-sanitizer }}
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.9.5
        with:
          cmake-version: '>=3.26'
          source-dir: examples/library/breaking-changes
          build-dir: build/example-breaking-changes
          cxxstd: ${{ matrix.cxxstd }}
          cc: ${{ steps.setup-cpp.outputs.cc || matrix.cc }}
          cxx: ${{ steps.setup-cpp.outputs.cxx || matrix.cxx }}
          cxxflags: ${{ env.BOOTSTRAP_CXXFLAGS }}
          ldflags: ${{ env.BOOTSTRAP_LDFLAGS }}
          generator: Ninja
          build-type: ${{ matrix.build-type }}
          extra-args: -D mrdocs_ROOT=${{ env.MRDOCS_PREFIX }}
          run-tests: true
          install: false

      # Upload packages for ci-releases.yml to pick up
      - name: Upload GitHub Release Artifacts
        if: matrix.is-release-build == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: ${{ matrix.mrdocs-release-package-artifact }}
          path: |
            build/packages
            !build/packages/_CPack_Packages
          retention-days: 1

      - name: FlameGraph
        uses: alandefreitas/cpp-actions/flamegraph@v1.9.5
        if: matrix.time-trace
        with:
          build-dir: build/mrdocs
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Process Coverage
        id: process-coverage
        if: matrix.coverage
        uses: alandefreitas/cpp-actions/process-coverage@v1.9.5
        with:
          cxx: ${{ steps.setup-cpp.outputs.cxx || matrix.cxx }}
          build-dir: build/mrdocs
          html-report: true
          codecov-token: ${{ secrets.CODECOV_TOKEN }}
          codecov-flags: cpp

      # Save the produced LCOV report so PRs that don't change source files
      # can replay it to codecov without re-running a Coverage build.
      # `ci-scope-detector.yml` probes this artifact by name and merge-base SHA.
      - name: Save coverage for replay
        if: |
          matrix.coverage &&
          github.event_name == 'push' &&
          github.ref_name == 'develop' &&
          steps.process-coverage.outputs.lcov-file != ''
        uses: actions/upload-artifact@v7
        with:
          name: coverage-develop
          path: ${{ steps.process-coverage.outputs.lcov-file }}
          retention-days: 90
          if-no-files-found: error