ci.yml

name: Continuous Integration

on:
  push:
    branches:
      - develop
      - master
      - '*'
    tags:
      - "v*.*.*"

  # pull_request runs the matrix/build on the PR head with the fork-scoped token
  # (no comment perms on base repo).
  pull_request:
    branches:
      - develop


concurrency:
  group: ${{format('{0}:{1}', github.repository, github.ref)}}
  cancel-in-progress: true

jobs:
  cpp-matrix:
    runs-on: ubuntu-24.04
    container:
      image: ubuntu:24.04
    name: Generate Test Matrix
    outputs:
      matrix: ${{ steps.cpp-matrix.outputs.matrix }}
      llvm-matrix: ${{ steps.llvm-matrix.outputs.llvm-matrix }}
      releases-matrix: ${{ steps.releases-matrix.outputs.releases-matrix }}
    steps:
      - name: Install prerequisites
        run: |
          set -e
          apt-get update
          apt-get install -y git ca-certificates curl nodejs npm
          if ! command -v node >/dev/null 2>&1 && command -v nodejs >/dev/null 2>&1; then
            ln -s /usr/bin/nodejs /usr/bin/node
          fi

      - name: Checkout
        uses: actions/checkout@v4

      - name: Generate Test Matrix
        uses: alandefreitas/cpp-actions/cpp-matrix@v1.9.2
        id: cpp-matrix
        with:
          compilers: |
            gcc >=14
            clang >=18
            msvc >=14.40
            apple-clang *
          standards: '20'
          latest-factors: |
            gcc UBSan
            clang UBSan ASan MSan Coverage
            apple-clang UBSan ASan
          factors: ''
          runs-on: |
            apple-clang: macos-15
          containers: |
            clang: ubuntu:24.04
          build-types: |
            gcc: Release
            clang: Release
            apple-clang: Release
            msvc: RelWithDebInfo
          install: |
            gcc: git build-essential pkg-config python3 curl unzip openjdk-11-jdk pkg-config libncurses-dev libxml2-utils libxml2-dev
            clang: git build-essential pkg-config python3 curl unzip openjdk-11-jdk pkg-config libncurses-dev libxml2-utils libxml2-dev g++-14 elfutils
            msvc: ''
          extra-values: |
            use-libcxx: {{#if (and (ieq compiler 'clang') (or msan asan)) }}true{{else}}false{{/if}}
            libcxx-runtimes: libcxx{{#if (ne compiler 'msvc')}};libcxxabi{{/if}}
            llvm-runtimes: {{#if (ine use-libcxx 'true') }}{{{ libcxx-runtimes }}}{{/if}}
            llvm-hash: dc4cef81d47c7bc4a3c4d58fbacf8a6359683fae
            llvm-build-preset-prefix: {{{lowercase build-type}}}
            llvm-build-preset-os: {{#if (ieq os 'windows') }}win{{else}}unix{{/if}}
            llvm-build-preset: {{{ llvm-build-preset-prefix }}}-{{{ llvm-build-preset-os }}}
            llvm-os-key: {{#if container}}{{{ container }}}{{else}}{{{ runs-on }}}{{/if}}
            llvm-archive-sanitizer-str: {{#if (ieq compiler 'clang')}}{{#if ubsan}}UBSan{{else if asan}}ASan{{/if}}{{/if}}
            llvm-archive-basename: llvm-{{{ substr llvm-hash 0 7 }}}-{{{ llvm-build-preset-prefix }}}-{{{ llvm-os-key }}}{{#if (and (ieq compiler 'clang') (or msan asan)) }}-{{{ compiler }}}-{{{ version }}}-{{{ llvm-archive-sanitizer-str }}}{{/if}}
            llvm-archive-extension: {{#if (ieq os 'windows') }}7z{{else}}tar.bz2{{/if}}
            llvm-archive-filename: {{{ llvm-archive-basename }}}.{{{ llvm-archive-extension }}}
            llvm-sanitizer-config: {{#if (and (ne compiler 'clang') (ne compiler 'apple-clang'))}}{{else if asan}}Address{{else if msan}}MemoryWithOrigins{{/if}}
            warning-flags: {{#if (eq compiler 'msvc') }}/WX /W4 {{else}}-Werror -Wall {{/if}}
            common-flags-base: {{#if (ieq compiler 'clang')}}-gz=zstd {{/if}}
            common-flags: {{{ common-flags-base }}}{{#if msan }}-fsanitize-memory-track-origins {{/if}}
            common-ccflags: {{{ ccflags }}} {{{ common-flags }}}
            mrdocs-flags: {{{ warning-flags }}}{{#if (and (eq compiler 'gcc') (not asan)) }}-static {{/if}}{{#if (and (ieq compiler 'clang') coverage)}}-fprofile-instr-generate -fcoverage-mapping {{/if}}
            mrdocs-ccflags: {{{ common-ccflags }}} {{{ mrdocs-flags }}}
            mrdocs-package-generators: {{#if (ieq os 'windows') }}7Z ZIP WIX{{else}}TGZ TXZ{{/if}}
            mrdocs-release-package-artifact: release-packages-{{{ lowercase os }}}
          output-file: matrix.json
          trace-commands: true
          github-token: ${{ secrets.GITHUB_TOKEN }}

      # Set up the version as expected by the LLVM matrix script and @actions/core
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Generate LLVM Test Matrix
        id: llvm-matrix
        run: |
          set -x
          cd .github
          npm ci
          cd ..
          node .github/llvm-matrix.js

      - name: Generate Releases Test Matrix
        id: releases-matrix
        run: |
          set -x
          cd .github
          npm ci
          cd ..
          node .github/releases-matrix.js

  build:
    needs: cpp-matrix

    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJSON(needs.cpp-matrix.outputs.matrix) }}

    defaults:
      run:
        shell: bash

    name: ${{ matrix.name }}
    runs-on: ${{ matrix.runs-on }}
    container: ${{ matrix.container }}
    env: ${{ matrix.env }}
    permissions:
      contents: write

    steps:
      - name: Ensure Node
        if: matrix.container != '' && env.ACT == 'true'
        run: |
          set -e
          apt-get update
          apt-get install -y nodejs npm
          if ! command -v node >/dev/null 2>&1 && command -v nodejs >/dev/null 2>&1; then
            ln -s /usr/bin/nodejs /usr/bin/node
          fi

      # We install git if we are using a container because
      # containers don't always include git.
      # We need git to ensure actions/checkout@v4 will use git and
      # for the next steps that need to clone repositories
      - name: Install Git
        uses: alandefreitas/cpp-actions/package-install@v1.9.2
        if: matrix.container != ''
        env:
          DEBIAN_FRONTEND: 'noninteractive'
          TZ: 'Etc/UTC'
        with:
          apt-get: git

      # Set up the repository ownership to avoid issues with git commands
      - name: Configure Git Safe Directory
        if: matrix.container != ''
        run: git config --global --add safe.directory "$(pwd)"

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

      - name: Setup CMake
        uses: alandefreitas/cpp-actions/setup-cmake@v1.9.2
        id: setup-cmake
        with:
          version: '>=3.26'
          check-latest: 'true'
          update-environment: 'true'
          trace-commands: 'true'

      - name: Setup Ninja
        uses: seanmiddleditch/gha-setup-ninja@v5

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

      - name: Configure symbolizer paths
        if: matrix.compiler != 'msvc'
        shell: bash
        run: |
          set -e
          candidates=()
          # 1) Anything on PATH
          if command -v llvm-symbolizer >/dev/null 2>&1; then
            candidates+=("$(command -v llvm-symbolizer)")
          fi
          uname_out="$(uname -s || true)"
          # 2) Platform-specific common locations
          case "$uname_out" in
            Darwin)
              if xcrun --find llvm-symbolizer >/dev/null 2>&1; then
                candidates+=("$(xcrun --find llvm-symbolizer)")
              fi
              candidates+=("/opt/homebrew/opt/llvm/bin/llvm-symbolizer")
              ;;
            Linux)
              for dir in /usr/lib/llvm-* /usr/lib/llvm; do
                if [ -x "$dir/bin/llvm-symbolizer" ]; then
                  candidates+=("$dir/bin/llvm-symbolizer")
                fi
              done
              ;;
            MINGW*|MSYS*|CYGWIN*)
              for dir in "/c/Program Files/LLVM/bin" "/c/ProgramData/chocolatey/lib/llvm/tools/llvm/bin"; do
                if [ -x "$dir/llvm-symbolizer.exe" ]; then
                  candidates+=("$dir/llvm-symbolizer.exe")
                fi
              done
              ;;
          esac
          sym=""
          for c in "${candidates[@]}"; do
            if [ -n "$c" ] && [ -x "$c" ]; then
              sym="$c"
              break
            fi
          done
          if [ -n "$sym" ]; then
            echo "Using llvm-symbolizer at: $sym"
            echo "LLVM_SYMBOLIZER_PATH=$sym" >> "$GITHUB_ENV"
            echo "ASAN_SYMBOLIZER_PATH=$sym" >> "$GITHUB_ENV"
          else
            echo "Warning: llvm-symbolizer not found; ASan stacks may be unsymbolized." >&2
          fi

      # If apple-clang on macos, select the newest Xcode.
      - name: Select Xcode 16.4
        if: matrix.compiler == 'apple-clang'
        run: |
          sudo ls -1 /Applications | grep Xcode
          xcode-select --version
          sudo xcode-select -s /Applications/Xcode_16.4.app/Contents/Developer
          ${{ steps.setup-cpp.outputs.cxx }} -v

      # If apple-clang on macos, we run `clang -print-targets` to
      # get the list of targets supported by the compiler.
      - name: Print Clang Targets
        if: matrix.compiler == 'apple-clang'
        run: |
          set -x
          ${{ steps.setup-cpp.outputs.cxx }} --print-targets
          ${{ steps.setup-cpp.outputs.cxx }} --print-target-triple

      - name: Install System Packages
        uses: alandefreitas/cpp-actions/package-install@v1.9.2
        if: matrix.compiler != 'msvc'
        id: package-install
        env:
          DEBIAN_FRONTEND: 'noninteractive'
          TZ: 'Etc/UTC'
        with:
          apt-get: ${{ matrix.install }}

      - name: Install LLVM packages
        if: matrix.compiler == 'clang'
        env:
          DEBIAN_FRONTEND: 'noninteractive'
          TZ: 'Etc/UTC'
        run: |
          echo "deb http://apt.llvm.org/noble/ llvm-toolchain-noble-21 main" >> /etc/apt/sources.list
          apt-get update
          apt-get install -y libclang-${{ matrix.major }}-dev llvm-${{ matrix.major }}-tools

      # This calculates a bunch of variables, which would normally go in to the regular matrix extra-values
      # section, but which depend on paths not known at that point.
      - name: Resolved Matrix
        id: rmatrix
        run: |
          set -euvx

          third_party_dir="$(realpath $(pwd)/..)/third-party"
          if [[ "${{ runner.os }}" == 'Windows' ]]; then
              third_party_dir="$(echo "$third_party_dir" | sed 's/\\/\//g; s|^/d/|D:/|')"
          fi
          echo "third-party-dir=$third_party_dir" >> $GITHUB_OUTPUT

          llvm_path="$third_party_dir/llvm"
          echo "llvm-path=$llvm_path" >> $GITHUB_OUTPUT

          common_cxxflags_base=""
          if [[ "${{ matrix.use-libcxx }}" == 'true' ]]; then
            common_cxxflags_base="-nostdinc++ -nostdlib++ -isystem$llvm_path/include/c++/v1"
          fi
          echo "common-cxxflags-base=$common_cxxflags_base" >> $GITHUB_OUTPUT

          common_cxxflags="$common_cxxflags_base ${{ matrix.cxxflags }} ${{ matrix.common-flags }}"
          echo "common-cxxflags=$common_cxxflags" >> $GITHUB_OUTPUT

          echo "mrdocs-cxxflags=$common_cxxflags ${{ matrix.mrdocs-flags }}" >> $GITHUB_OUTPUT

          common_ldflags="${{ matrix.ldflags }}"
          if [[ "${{ matrix.use-libcxx }}" == 'true' ]]; then
            common_ldflags="$common_ldflags -L$llvm_path/lib -lc++abi -lc++ -Wl,-rpath,$llvm_path/lib"
          fi
          if [[ "${{ matrix.ubsan }}" == 'true' ]]; then
            common_ldflags="$common_ldflags -fsanitize=undefined"
          fi
          if [[ "${{ matrix.asan }}" == 'true' ]]; then
            common_ldflags="$common_ldflags -fsanitize=address"
          fi
          if [[ "${{ matrix.msan }}" == 'true' ]]; then
            common_ldflags="$common_ldflags -fsanitize=memory"
          fi
          echo "common-ldflags=$common_ldflags" >> $GITHUB_OUTPUT

          llvm_cache_key="${{ matrix.llvm-archive-basename }}"
          llvm_cache_key="${llvm_cache_key//:/-}"
          echo "llvm-cache-key=$llvm_cache_key" >> $GITHUB_OUTPUT

      - name: Cached LLVM Binaries
        id: llvm-cache
        uses: actions/cache@v4
        with:
          path: ${{ steps.rmatrix.outputs.llvm-path }}
          key: ${{ steps.rmatrix.outputs.llvm-cache-key }}

      # Installs libc++ separately, using the LLVM standalone runtimes build.
      # The libc++ built here will be built using the host compiler, so this is
      # limited by what libc++ at the current LLVM revision supports.
      # This will be only built for configurations where 'use-libcxx' is true,
      # and in which case libc++ will **not** be built again later using the
      # bootstrapping runtimes build.
      # This should be built at least for all of the sanitizer builds, as it
      # is required for some, and increases their effectiveness otherwise.
      # This should not be built for any of the release builds, as they wouldn't
      # otherwise be independent of this particular libc++.
      # FIXME: Build this for the GCC and MacOS sanitizer jobs.
      # Currently GCC fails linking it, and for MacOS there are compiler-rt
      # requirements not satisfied.
      - name: Fetch LLVM source archive
        if: steps.llvm-cache.outputs.cache-hit != 'true'
        run: |
          set -eux
          mkdir -p ../third-party
          cd ../third-party
          archive="llvm-${{ matrix.llvm-hash }}.zip"
          if [ ! -d llvm-project ]; then
            curl -L -o "$archive" "https://github.com/llvm/llvm-project/archive/${{ matrix.llvm-hash }}.zip"
            unzip -q "$archive"
            mv "llvm-project-${{ matrix.llvm-hash }}" llvm-project
            rm "$archive"
          fi

      - name: Install libc++
        id: install_libcxx
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.9.2
        if: matrix.use-libcxx == 'true' && steps.llvm-cache.outputs.cache-hit != 'true'
        with:
          cmake-version: '>=3.26'
          source-dir: ../third-party/llvm-project/runtimes
          build-dir: ${sourceDir}/build
          build-type: ${{ matrix.build-type }}
          extra-args: |
            -D LLVM_USE_SANITIZER=${{ matrix.llvm-sanitizer-config }}
            -D LLVM_OPTIMIZED_TABLEGEN=ON
            -D LLVM_ENABLE_LIBCXX=OFF
            -D LLVM_ENABLE_PROJECT=""
            -D LLVM_ENABLE_RUNTIMES="${{ matrix.libcxx-runtimes }}"
            -D LIBCXXABI_USE_LLVM_UNWINDER=OFF
            -D CMAKE_C_FLAGS="${{ matrix.common-flags-base }}"
            -D CMAKE_CXX_FLAGS="${{ matrix.common-flags-base }}"

          cc: ${{ steps.setup-cpp.outputs.cc }}
          cxx: ${{ steps.setup-cpp.outputs.cxx }}
          generator: Ninja
          install: true
          install-prefix: ${{ steps.rmatrix.outputs.llvm-path }}
          run-tests: false
          trace-commands: true

      - name: Remove libcxx build-dir
        if: steps.install_libcxx.outcome == 'success'
        run: |
          rm -r ../third-party/llvm-project/runtimes/build

      # If libc++ was built in the steps above, we won't build it again here.
      # This is controlled by the llvm-runtimes matrix variable.
      - name: Install LLVM
        id: install_llvm
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.9.2
        if: steps.llvm-cache.outputs.cache-hit != 'true'
        with:
          cmake-version: '>=3.26'
          source-dir: ../third-party/llvm-project/llvm
          patches: |
            ./third-party/patches/llvm/llvm/CMakePresets.json
            ./third-party/patches/llvm/llvm/CMakeUserPresets.json
          build-dir: ${sourceDir}/build
          preset: ${{ matrix.llvm-build-preset }}
          build-type: ${{ matrix.build-type }}
          extra-args: |
            -D LLVM_ENABLE_ASSERTIONS=ON
            -D LLVM_USE_SANITIZER="${{ matrix.llvm-sanitizer-config }}"
            -D LLVM_OPTIMIZED_TABLEGEN=ON
            -D LLVM_COMPILER_CHECKED=ON
            -D LLVM_BUILD_TOOLS=OFF
            -D CLANG_BUILD_TOOLS=OFF
            -D LLVM_ENABLE_RUNTIMES="${{ matrix.llvm-runtimes }}"
            -D LIBCXXABI_USE_LLVM_UNWINDER=OFF
            -D CMAKE_C_FLAGS="${{ matrix.common-flags-base }}"
            -D CMAKE_CXX_FLAGS="${{ matrix.common-flags-base }} ${{ steps.rmatrix.outputs.common-cxxflags-base }}"
            -D CMAKE_SHARED_LINKER_FLAGS="${{ steps.rmatrix.outputs.common-ldflags }}"
            -D CMAKE_EXE_LINKER_FLAGS="${{ steps.rmatrix.outputs.common-ldflags }}"
          cc: ${{ steps.setup-cpp.outputs.cc }}
          cxx: ${{ steps.setup-cpp.outputs.cxx }}
          generator: Ninja
          install: true
          install-prefix: ${{ steps.rmatrix.outputs.llvm-path }}
          run-tests: false
          trace-commands: true

      - name: Remove LLVM build-dir
        if: steps.install_llvm.outcome == 'success'
        run: |
          rm -r ../third-party/llvm-project

      - name: Install Boost.Mp11
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.8.12
        with:
          source-dir: ../third-party/boost_mp11
          git-repository: https://github.com/boostorg/mp11
          git-tag: boost-1.90.0
          patches: |
            ./third-party/patches/boost_mp11/CMakeLists.txt
            ./third-party/patches/boost_mp11/boost_mp11-config.cmake.in
          build-dir: ${sourceDir}/build
          cc: ${{ steps.setup-cpp.outputs.cc }}
          cxx: ${{ steps.setup-cpp.outputs.cxx }}
          build-type: Release
          shared: false
          install: true
          install-prefix: ${sourceDir}/install
          run-tests: false
          trace-commands: true

      - name: Install Boost.Describe
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.8.12
        with:
          source-dir: ../third-party/boost_describe
          git-repository: https://github.com/boostorg/describe
          git-tag: boost-1.90.0
          patches: |
            ./third-party/patches/boost_describe/CMakeLists.txt
            ./third-party/patches/boost_describe/boost_describe-config.cmake.in
          build-dir: ${sourceDir}/build
          cc: ${{ steps.setup-cpp.outputs.cc }}
          cxx: ${{ steps.setup-cpp.outputs.cxx }}
          build-type: Release
          shared: false
          install: true
          install-prefix: ${sourceDir}/install
          run-tests: false
          trace-commands: true

      - name: Install JerryScript
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.9.2
        with:
          source-dir: ../third-party/jerryscript
          url: https://github.com/jerryscript-project/jerryscript/archive/refs/tags/v3.0.0.tar.gz
          patches: |
            ./third-party/patches/jerryscript/CMakeLists.txt
            ./third-party/patches/jerryscript/jerryscriptConfig.cmake.in
          build-dir: ${sourceDir}/build
          cc: ${{ steps.setup-cpp.outputs.cc }}
          cxx: ${{ steps.setup-cpp.outputs.cxx }}
          ccflags: ${{ matrix.common-ccflags }}
          cxxflags: ${{ steps.rmatrix.outputs.common-cxxflags }}
          build-type: ${{ matrix.build-type }}
          shared: false
          install: true
          install-prefix: ${sourceDir}/install
          run-tests: false
          trace-commands: true
          extra-args: |
            -D JERRY_PROFILE=es.next
            -D JERRY_EXTERNAL_CONTEXT=ON
            -D JERRY_PORT=ON
            -D JERRY_DEBUGGER=OFF
            -D JERRY_SNAPSHOT_SAVE=OFF
            -D JERRY_SNAPSHOT_EXEC=OFF
            -D JERRY_CMDLINE=OFF
            -D JERRY_TESTS=OFF
            -D JERRY_MEM_STATS=OFF
            -D JERRY_PARSER_STATS=OFF
            -D JERRY_LINE_INFO=OFF
            -D JERRY_LTO=OFF
            -D JERRY_LIBC=OFF

      - name: Install Lua
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.9.2
        with:
          source-dir: ../third-party/lua
          url: https://github.com/lua/lua/archive/refs/tags/v5.4.8.tar.gz
          patches: |
            ./third-party/patches/lua/CMakeLists.txt
            ./third-party/patches/lua/LuaConfig.cmake.in
          build-dir: ${sourceDir}/build
          cc: ${{ steps.setup-cpp.outputs.cc }}
          cxx: ${{ steps.setup-cpp.outputs.cxx }}
          ccflags: ${{ matrix.common-ccflags }}
          cxxflags: ${{ steps.rmatrix.outputs.common-cxxflags }}
          build-type: ${{ matrix.build-type }}
          shared: false
          install: true
          install-prefix: ${sourceDir}/install
          run-tests: false
          trace-commands: true

      - name: Install Libxml2
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.9.2
        if: matrix.compiler == 'msvc'
        with:
          source-dir: ../third-party/libxml2
          git-repository: https://github.com/GNOME/libxml2
          git-tag: v2.12.6
          build-dir: ${sourceDir}/build
          cc: ${{ steps.setup-cpp.outputs.cc }}
          cxx: ${{ steps.setup-cpp.outputs.cxx }}
          ccflags: ${{ matrix.common-ccflags }}
          cxxflags: ${{ steps.rmatrix.outputs.common-cxxflags }}
          build-type: Release
          shared: false
          extra-args: |
            -D CMAKE_SHARED_LINKER_FLAGS="${{ steps.rmatrix.outputs.common-ldflags }}"
            -D LIBXML2_WITH_PROGRAMS=ON
            -D LIBXML2_WITH_FTP=OFF 
            -D LIBXML2_WITH_HTTP=OFF
            -D LIBXML2_WITH_ICONV=OFF 
            -D LIBXML2_WITH_LEGACY=OFF
            -D LIBXML2_WITH_LZMA=OFF 
            -D LIBXML2_WITH_ZLIB=OFF 
            -D LIBXML2_WITH_ICU=OFF
            -D LIBXML2_WITH_TESTS=OFF 
            -D LIBXML2_WITH_HTML=ON 
            -D LIBXML2_WITH_C14N=ON
            -D LIBXML2_WITH_CATALOG=ON 
            -D LIBXML2_WITH_DEBUG=ON 
            -D LIBXML2_WITH_ISO8859X=ON 
            -D LIBXML2_WITH_MEM_DEBUG=OFF
            -D LIBXML2_WITH_MODULES=ON
            -D LIBXML2_WITH_OUTPUT=ON
            -D LIBXML2_WITH_PATTERN=ON
            -D LIBXML2_WITH_PUSH=ON
            -D LIBXML2_WITH_PYTHON=OFF
            -D LIBXML2_WITH_READER=ON
            -D LIBXML2_WITH_REGEXPS=ON
            -D LIBXML2_WITH_SAX1=ON
            -D LIBXML2_WITH_SCHEMAS=ON
            -D LIBXML2_WITH_SCHEMATRON=ON
            -D LIBXML2_WITH_THREADS=ON
            -D LIBXML2_WITH_THREAD_ALLOC=OFF
            -D LIBXML2_WITH_TREE=ON
            -D LIBXML2_WITH_VALID=ON
            -D LIBXML2_WITH_WRITER=ON
            -D LIBXML2_WITH_XINCLUDE=ON
            -D LIBXML2_WITH_XPATH=ON
            -D LIBXML2_WITH_XPTR=ON
          install: true
          install-prefix: ${sourceDir}/install
          run-tests: false
          trace-commands: true

      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: CMake Workflow
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.9.2
        env:
          LLVM_PROFILE_FILE: mrdocs-%b-%m.profraw
        with:
          cmake-version: '>=3.26'
          cxxstd: ${{ matrix.cxxstd }}
          cc: ${{ steps.setup-cpp.outputs.cc || matrix.cc }}
          ccflags: ${{ matrix.mrdocs-ccflags }}
          cxx: ${{ steps.setup-cpp.outputs.cxx || matrix.cxx }}
          cxxflags: ${{ steps.rmatrix.outputs.mrdocs-cxxflags }}
          generator: Ninja
          toolchain: ${{ steps.package-install.outputs.vcpkg_toolchain || steps.package-install.outputs.vcpkg-toolchain }}
          build-type: ${{ matrix.build-type }}
          install-prefix: .local
          extra-args: |
            -D MRDOCS_BUILD_DOCS=OFF
            -D CMAKE_EXE_LINKER_FLAGS="${{ steps.rmatrix.outputs.common-ldflags }}"
            -D LLVM_ROOT="${{ steps.rmatrix.outputs.llvm-path }}"
            -D jerryscript_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/jerryscript/install"
            -D LUA_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/lua/install"
            -D Lua_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/lua/install"
            -D lua_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/lua/install"
            -D boost_mp11_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/boost_mp11/install"
            -D boost_describe_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/boost_describe/install"
            ${{ runner.os == 'Windows' && '-D LibXml2_ROOT=../third-party/libxml2/install' || '' }}
          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

      - name: Check YAML schema
        run: |
          # Find python
          python=$(command -v python3 || command -v python)
          # The schema in this branch is up to date 
          "$python" ./util/generate-yaml-schema.py --check
          # The schema in the docs folder is valid
          npx -y -p ajv-cli -- ajv compile -s docs/mrdocs.schema.json

      - name: Verify snippet .cpp files match golden tests (bash)
        shell: bash
        run: |
          set -euo pipefail
          shopt -s nullglob
          
          SRC="docs/website/snippets"
          DST="test-files/golden-tests/snippets"
          
          [[ -d "$SRC" ]] || { echo "Source directory not found: $SRC"; exit 2; }
          [[ -d "$DST" ]] || { echo "Destination directory not found: $DST"; exit 2; }
          
          missing=()
          mismatched=()
          
          # Walk all .cpp files under SRC
          while IFS= read -r -d '' src; do
            rel="${src#$SRC/}"
            dst="$DST/$rel"
          
            if [[ ! -f "$dst" ]]; then
              missing+=("$rel")
              continue
            fi
          
            if [[ "${STRICT_EOL:-0}" == "1" ]]; then
              # strict byte-for-byte comparison
              if ! cmp -s -- "$src" "$dst"; then
                mismatched+=("$rel")
              fi
            else
              # ignore CRLF/LF differences using git diff (available on all runners)
              if ! git diff --no-index --ignore-cr-at-eol --quiet -- "$src" "$dst"; then
                mismatched+=("$rel")
              fi
            fi
          done < <(find "$SRC" -type f -name '*.cpp' -print0)
          
          if (( ${#missing[@]} || ${#mismatched[@]} )); then
            if (( ${#missing[@]} )); then
              echo "Missing corresponding golden files:"
              printf '  %s\n' "${missing[@]}"
            fi
            if (( ${#mismatched[@]} )); then
              echo "Content mismatches:"
              printf '  %s\n' "${mismatched[@]}"
            fi
            exit 1
          fi
          
          echo "All snippet .cpp files are present and match."
        env:
          # Set to "1" to enforce byte-for-byte equality (do not ignore CRLF/LF)
          STRICT_EOL: "0"


      - name: Check landing page snippets
        run: |
          # Find python
          python=$(command -v python3 || command -v python)
          # The schema in this branch is up to date 
          "$python" ./util/generate-yaml-schema.py --check
          # The schema in the docs folder is valid
          npx -y -p ajv-cli -- ajv compile -s docs/mrdocs.schema.json

      - name: Upload GitHub Release Artifacts
        if: ${{ matrix.is-main && matrix.compiler != 'clang' }}
        uses: actions/upload-artifact@v4
        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.2
        if: matrix.time-trace
        with:
          build-dir: build
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Codecov
        id: codecov
        if: matrix.coverage
        run: |
          set -euvx

          cd build
          build_id=$(eu-readelf -n bin/mrdocs-test | awk '/Build ID:/{print $NF}')
          llvm-profdata-${{ matrix.major }} merge -sparse mrdocs-${build_id}-*.profraw -o default.profdata
          llvm-cov-${{ matrix.major }} export -format=lcov -instr-profile=default.profdata bin/mrdocs-test > "mrdocs-test.info"
          echo "file=$(realpath "mrdocs-test.info")" >> $GITHUB_OUTPUT

      - name: Upload Coverage as Artifact
        if: matrix.coverage
        uses: actions/upload-artifact@v4
        with:
          name: Coverage
          path: ${{ steps.codecov.outputs.file }}
          retention-days: 30

      - name: Codecov Upload
        uses: codecov/codecov-action@v5
        if: matrix.coverage
        with:
          fail_ci_if_error: true
          files: ${{ steps.codecov.outputs.file }}
          disable_search: true
          token: ${{ secrets.CODECOV_TOKEN }}
          verbose: true


  releases:
    needs: [ cpp-matrix, build ]
    if: ${{ needs.cpp-matrix.outputs.releases-matrix != '[]' && needs.cpp-matrix.outputs.releases-matrix != '' }}
    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJSON(needs.cpp-matrix.outputs.releases-matrix) }}

    defaults:
      run:
        shell: bash

    name: ${{ matrix.os }} MrDocs Releases
    runs-on: ${{ matrix.runs-on }}
    container: ${{ matrix.container }}
    permissions:
      contents: write

    steps:
      # This calculates a bunch of variables, which would normally go in to the regular matrix extra-values
      # section, but which depend on paths not known at that point.
      - name: Resolved Matrix
        id: rmatrix
        run: |
          set -euvx

          third_party_dir="$(realpath $(pwd)/..)/third-party"
          if [[ "${{ runner.os }}" == 'Windows' ]]; then
              third_party_dir="$(echo "$third_party_dir" | sed 's/\\/\//g; s|^/d/|D:/|')"
          fi
          echo "third-party-dir=$third_party_dir" >> $GITHUB_OUTPUT

          llvm_path="$third_party_dir/llvm"
          echo "llvm-path=$llvm_path" >> $GITHUB_OUTPUT

          llvm_cache_key="${{ matrix.llvm-archive-basename }}"
          llvm_cache_key="${llvm_cache_key//:/-}"
          echo "llvm-cache-key=$llvm_cache_key" >> $GITHUB_OUTPUT

      - name: Ensure Node
        if: matrix.container != '' && env.ACT == 'true'
        run: |
          set -e
          apt-get update
          apt-get install -y nodejs npm
          if ! command -v node >/dev/null 2>&1 && command -v nodejs >/dev/null 2>&1; then
            ln -s /usr/bin/nodejs /usr/bin/node
          fi

      - name: Install packages
        uses: alandefreitas/cpp-actions/package-install@v1.9.2
        id: package-install
        with:
          apt-get: build-essential asciidoctor cmake bzip2 git rsync

      - name: Clone MrDocs
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          fetch-tags: true

      - name: Set Repository Ownership
        run: |
          git config --global --add safe.directory "$(pwd)"

      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Setup Ninja
        uses: seanmiddleditch/gha-setup-ninja@v5
        if: ${{ runner.os == 'Windows' }}

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

      - name: Cached LLVM Binaries
        id: llvm-cache
        uses: actions/cache@v4
        with:
          path: ${{ steps.rmatrix.outputs.llvm-path }}
          key: ${{ steps.rmatrix.outputs.llvm-cache-key }}
          fail-on-cache-miss: true

      - name: Download MrDocs package
        uses: actions/download-artifact@v4
        with:
          name: ${{ matrix.mrdocs-release-package-artifact }}
          path: packages

      - name: Install MrDocs from Package
        run: |
          set -euvx

          # Delete packages/_CPack_Packages files from previous runs
          rm -rf packages/_CPack_Packages

          # Print tree structure
          find packages -print | sed 's;[^/]*/;|____;g;s;____|; |;g'

          dest_dir="${{ steps.rmatrix.outputs.llvm-path }}"

          if [[ ${{ runner.os }} != 'Windows' ]]; then
              find packages -maxdepth 1 -name 'MrDocs-*.tar.gz' -exec tar -vxzf {} -C $dest_dir --strip-components=1 \;              
          else
              package=$(find packages -maxdepth 1 -name "MrDocs-*.7z" -print -quit)
              filename=$(basename "$package")
              name="${filename%.*}"
              7z x "${package}" -o${dest_dir}
              set +e
              robocopy "${dest_dir}/${name}" "${dest_dir}" //move //e //np //nfl
              exit_code=$?
              set -e
              if (( exit_code >= 8 )); then
                exit 1
              fi
          fi
          MRDOCS_ROOT="$dest_dir"
          echo -e "MRDOCS_ROOT=$MRDOCS_ROOT" >> $GITHUB_ENV
          echo -e "$MRDOCS_ROOT/bin" >> $GITHUB_PATH 
          $MRDOCS_ROOT/bin/mrdocs --version

      - name: Clone Boost.URL
        uses: alandefreitas/cpp-actions/boost-clone@v1.9.2
        id: boost-url-clone
        with:
          branch: develop
          modules: url
          boost-dir: boost
          modules-scan-paths: '"test example"'
          modules-exclude-paths: ''
          trace-commands: true

      - name: Set up llvm-symbolizer
        if: ${{ runner.os != 'Windows' }}
        run: |
          set -x
          
          if [[ $RUNNER_OS == 'macOS' ]]; then
            # Step 1: Check if llvm-symbolizer is installed
            if ! command -v llvm-symbolizer &> /dev/null; then
                echo "llvm-symbolizer is not installed. Installing via Homebrew..."
                # Step 2: Install llvm if not installed
                if command -v brew &> /dev/null; then
                    brew install llvm
                else
                    echo "Homebrew is not installed. Please install Homebrew first: https://brew.sh/"
                    exit 1
                fi
            fi
          
            # Step 3: Ensure llvm-symbolizer is in your PATH
            llvm_bin_path=$(brew --prefix)/opt/llvm/bin
            PATH="$PATH:$llvm_bin_path"
            LLVM_SYMBOLIZER_PATH=$(which llvm-symbolizer)
            if [ -z "$LLVM_SYMBOLIZER_PATH" ]; then
                echo "llvm-symbolizer installation failed or it's not in the PATH."
                exit 1
            else
                echo "llvm-symbolizer found at: $LLVM_SYMBOLIZER_PATH"
            fi
          elif [[ $RUNNER_OS == 'Linux' ]]; then
            # Step 1: Check if llvm-symbolizer is installed
            if ! command -v llvm-symbolizer &> /dev/null; then
                echo "llvm-symbolizer is not installed. Installing via apt-get..."
                apt-get update
                apt-get install -y llvm
            fi
          
            # Step 2: Ensure llvm-symbolizer is in your PATH
            LLVM_SYMBOLIZER_PATH=$(which llvm-symbolizer)
            if [ -z "$LLVM_SYMBOLIZER_PATH" ]; then
                echo "llvm-symbolizer installation failed or it's not in the PATH."
                exit 1
            else
                echo "llvm-symbolizer found at: $LLVM_SYMBOLIZER_PATH"
            fi
          else
            echo "Unsupported OS: $RUNNER_OS"
            exit 1
          fi
          
          # Step 4: Export LLVM_SYMBOLIZER_PATH environment variable
          export LLVM_SYMBOLIZER_PATH="$LLVM_SYMBOLIZER_PATH"
          echo -e "LLVM_SYMBOLIZER_PATH=$LLVM_SYMBOLIZER_PATH" >> $GITHUB_ENV
          echo "Environment variable LLVM_SYMBOLIZER_PATH set to: $LLVM_SYMBOLIZER_PATH"

      - name: Generate Landing Page
        working-directory: docs/website
        run: |
          npm ci
          node render.js
          mkdir -p ../../build/website
          cp index.html ../../build/website/index.html
          cp robots.txt ../../build/website/robots.txt
          cp styles.css ../../build/website/styles.css
          cp -r assets ../../build/website/assets

      - name: Generate Antora UI
        working-directory: docs/ui
        run: |
          # This playbook renders the documentation 
          # content for the website. It includes
          # master, develop, and tags.
          GH_TOKEN="${{ secrets.GITHUB_TOKEN }}"
          export GH_TOKEN
          npm ci
          npx gulp lint
          npx gulp

      # Website publishing gate:
      # - Only publish on pushes to master/develop and on tags
      # - Only on Linux runners (the publish steps assume GNU tooling)
      #
      # Use `if: env.PUBLISH_WEBSITE == 'true'` for all steps that
      # write into `build/website/` and get deployed to the website.
      - name: Set website publish gate
        run: |
          is_publish_ref='false'
          if [[ "${{ github.event_name }}" == 'push' ]]; then
            if [[ "${{ github.ref_name }}" == 'master' || "${{ github.ref_name }}" == 'develop' ]]; then
              is_publish_ref='true'
            fi
            if [[ "${{ github.ref }}" == refs/tags/* ]]; then
              is_publish_ref='true'
            fi
          fi

          publish_website="$is_publish_ref"
          if [[ "${{ runner.os }}" != 'Linux' ]]; then
            publish_website='false'
          fi

          {
            echo "IS_PUBLISH_REF=$is_publish_ref"
            echo "PUBLISH_WEBSITE=$publish_website"
          } >> "$GITHUB_ENV"

      - name: Ensure all refs for Antora
        if: env.PUBLISH_WEBSITE == 'true'
        run: |
          set -euo pipefail
          # Make sure Antora sees every branch and tag from the upstream repo,
          # regardless of who triggered the workflow.
          git remote set-url origin https://github.com/cppalliance/mrdocs.git
          git fetch --prune --prune-tags origin \
            '+refs/heads/*:refs/remotes/origin/*' \
            '+refs/tags/*:refs/tags/*'

      - name: Generate Remote Documentation
        working-directory: docs
        run: |
          # This playbook renders the documentation 
          # content for the website. It includes
          # master, develop, and tags.
          GH_TOKEN="${{ secrets.GITHUB_TOKEN }}"
          export GH_TOKEN
          set -x
          npm ci
          npx antora --clean --fetch antora-playbook.yml --log-level=debug
          mkdir -p ../build/website/docs
          cp -vr build/site/* ../build/website/docs

      - name: Upload Website as Artifact
        uses: actions/upload-artifact@v4
        with:
          name: Website ${{ runner.os }}
          path: build/website
          retention-days: 30

      - name: Generate Local Documentation
        working-directory: docs
        run: |
          # This playbook allows us to render the 
          # documentation content and visualize it
          # before a workflow that pushes to the
          # website is triggered.
          GH_TOKEN="${{ secrets.GITHUB_TOKEN }}"
          export GH_TOKEN
          set -x
          npx antora antora-playbook.yml --attribute branchesarray=HEAD --stacktrace --log-level=debug
          mkdir -p ../build/docs-local
          cp -vr build/site/* ../build/docs-local

      - name: Clone Beman.Optional
        uses: actions/checkout@v4
        with:
          repository: steve-downey/optional
          ref: main
          path: beman-optional

      - name: Clone Fmt
        uses: actions/checkout@v4
        with:
          repository: fmtlib/fmt
          ref: master
          path: fmt

      - name: Clone Nlohmann.Json
        uses: actions/checkout@v4
        with:
          repository: nlohmann/json
          ref: develop
          path: nlohmann-json

      - name: Clone MpUnits
        uses: actions/checkout@v4
        with:
          repository: mpusz/mp-units
          ref: master
          path: mp-units

      - name: Patch Demo Projects
        shell: bash
        run: |
          set -euo pipefail
          set -x
          
          for project in beman-optional fmt nlohmann-json mp-units; do
            src="./examples/third-party/$project"
            dst="./$project"
          
            [ -d "$src" ] || { echo "Source not found: $src" >&2; exit 1; }
            mkdir -p "$dst"
          
            # Mirror contents of $src into $dst, overwriting existing files
            tar -C "$src" -cf - . | tar -C "$dst" -xpf -
          done


      - name: Generate Demos
        run: |
          set -x

          declare -a generators=(
            "adoc"
            "xml"
            "html"
          )
          
          # Generate the demos for each variant and generator
          for variant in single multi; do
            for generator in "${generators[@]}"; do
              [[ $generator = xml && $variant = multi ]] && continue
              [[ $variant = multi ]] && multipage="true" || multipage="false"
              # boost.url demo
              mrdocs --config="$(pwd)/boost/libs/url/doc/mrdocs.yml" "../CMakeLists.txt" --output="$(pwd)/demos/boost-url/$variant/$generator" --multipage=$multipage --generator="$generator" --log-level=debug
              echo "Number of files in demos/boost-url/$variant/$generator: $(find demos/boost-url/$variant/$generator -type f | wc -l)"
              # beman.optional demo
              mrdocs --config="$(pwd)/beman-optional/docs/mrdocs.yml" --output="$(pwd)/demos/beman-optional/$variant/$generator" --multipage=$multipage --generator="$generator" --log-level=debug
              # nlohmann-json demo
              mrdocs --config="$(pwd)/nlohmann-json/docs/mrdocs.yml" --output="$(pwd)/demos/nlohmann-json/$variant/$generator" --multipage=$multipage --generator="$generator" --log-level=debug
              # mp-units demo
              mrdocs --config="$(pwd)/mp-units/docs/mrdocs.yml" --output="$(pwd)/demos/mp-units/$variant/$generator" --multipage=$multipage --generator="$generator" --log-level=debug
              # fmt demo
              mrdocs --config="$(pwd)/fmt/doc/mrdocs.yml" --output="$(pwd)/demos/fmt/$variant/$generator" --multipage=$multipage --generator="$generator" --log-level=debug
              # mrdocs documenting mrdocs demo
              mrdocs --config="$(pwd)/docs/mrdocs.yml" "$(pwd)/CMakeLists.txt" --output="$(pwd)/demos/mrdocs/$variant/$generator" --multipage=$multipage --generator="$generator" --log-level=debug
            done
          
            # Render the asciidoc files to html using asciidoctor
            if [[ ${{ runner.os }} == 'Linux' ]]; then
              for project in boost-url beman-optional mrdocs fmt nlohmann-json mp-units; do
                root="$(pwd)/demos/$project/$variant"
                src="$root/adoc"
                dst="$root/adoc-asciidoc"
                stylesheet="$(pwd)/share/mrdocs/addons/generator/common/layouts/style.css"
          
                # Create the top-level output dir
                mkdir -p "$dst"
          
                # Find every .adoc (recursively), mirror the directory structure, and render
                find "$src" -type f -name '*.adoc' -print0 |
                while IFS= read -r -d '' f; do
                  rel="${f#"$src/"}"                 # path relative to $src
                  outdir="$dst/$(dirname "$rel")"    # mirror subdir inside $dst
                  mkdir -p "$outdir"
                  asciidoctor -a stylesheet="${stylesheet}" -D "$outdir" "$f"
                done
              done
            fi
          done
          
          # Compress demos for the artifact
          tar -cjf $(pwd)/demos.tar.gz -C $(pwd)/demos --strip-components 1 .
          echo "demos_path=$(pwd)/demos.tar.gz" >> $GITHUB_ENV

      - name: Upload Demos as Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: demos${{ (contains(fromJSON('["master", "develop"]'), github.ref_name ) && format('-{0}', github.ref_name)) || '' }}-${{ runner.os }}
          path: demos.tar.gz
          # develop and master are retained for longer so that they can be compared
          retention-days: ${{ contains(fromJSON('["master", "develop"]'), github.ref_name) && '30' || '1' }}

      - name: Download Previous Demos
        if: startsWith(github.ref, 'refs/tags/') && runner.os == 'Linux'
        id: download-prev-demos
        uses: actions/download-artifact@v4
        continue-on-error: true
        with:
          name: demos-develop-${{ runner.os }}
          path: demos-previous

      - name: Compare demos
        if: startsWith(github.ref, 'refs/tags/') && steps.download-prev-demos.outputs.cache-hit == 'true' && runner.os == 'Linux'
        id: compare-demos
        run: |
          set -x

          # Define URLs and directories
          LOCAL_DEMOS_DIR="./demos/"
          PREV_DEMOS_DIR="./demos-previous/"
          DIFF_DIR="./demos-diff/"
          
          # Check if PREV_DEMOS_DIR exists and is not empty
          if [[ ! -d $PREV_DEMOS_DIR || -z $(ls -A $PREV_DEMOS_DIR) ]]; then
              echo "No previous demos found."
              echo "diff=false" >> $GITHUB_OUTPUT
              exit 0
          fi

          # Create directories if they don't exist
          mkdir -p $PREV_DEMOS_DIR $DIFF_DIR

          # Iterate over the previous files and compare them with the corresponding local files
          find $PREV_DEMOS_DIR -type f | while read previous_file; do
              # Derive the corresponding local file path
              local_file="${LOCAL_DEMOS_DIR}${previous_file#$PREV_DEMOS_DIR}"
              diff_output="$DIFF_DIR${previous_file#$PREV_DEMOS_DIR}"
              if [[ -f $local_file ]]; then
                  mkdir -p "$(dirname "$diff_output")"
                  diff "$previous_file" "$local_file" > "$diff_output"
                  if [[ ! -s $diff_output ]]; then
                      rm "$diff_output"
                  fi
              else
                  echo "LOCAL FILE $local_file DOES NOT EXITS." > "$diff_output"
                  echo "PREVIOUS CONTENT OF THE FILE WAS:" >> "$diff_output"
                  cat "$previous_file" >> "$diff_output"
              fi
          done

          # Iterate over the local files to find new files
          find $LOCAL_DEMOS_DIR -type f | while read local_file; do
              previous_file="${PREV_DEMOS_DIR}${local_file#$LOCAL_DEMOS_DIR}"
              diff_output="$DIFF_DIR${local_file#$LOCAL_DEMOS_DIR}"
              if [[ ! -f $previous_file ]]; then
                  echo "PREVIOUS $previous_file DOES NOT EXIST." > "$diff_output"
                  echo "IT HAS BEEN INCLUDED IN THIS VERSION." >> "$diff_output"
                  echo "NEW CONTENT OF THE FILE IS:" >> "$diff_output"
              fi
          done

          # Check if the diff directory is empty
          if [[ -z $(ls -A $DIFF_DIR) ]]; then
              echo "No differences found."
              # Store this as an output for the next step
              echo "diff=false" >> $GITHUB_OUTPUT
          else
              # Calculate number of files in the diff directory
              N_FILES=$(find $DIFF_DIR -type f | wc -l)
              echo "Differences found in $N_FILES output files."
              echo "diff=true" >> $GITHUB_OUTPUT
          fi

      - name: Upload Demo Diff as Artifacts
        if: startsWith(github.ref, 'refs/tags/') && steps.download-prev-demos.outputs.cache-hit == 'true' && steps.compare-demos.outputs.diff == 'true' && runner.os == 'Linux'
        uses: actions/upload-artifact@v4
        with:
          name: demos-diff
          path: demos-diff
          retention-days: 30

      - name: Publish Website to GitHub Pages
        if: env.PUBLISH_WEBSITE == 'true'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: build/website
          force_orphan: true

      - name: Publish website
        if: env.PUBLISH_WEBSITE == 'true'
        env:
          SSH_AUTH_SOCK: /tmp/ssh_agent.sock
        run: |
          set -euvx
          # Add SSH key
          mkdir -p /home/runner/.ssh
          ssh-keyscan dev-websites.cpp.al >> /home/runner/.ssh/known_hosts
          chmod 600 /home/runner/.ssh/known_hosts
          echo "${{ secrets.DEV_WEBSITES_SSH_KEY }}" > /home/runner/.ssh/github_actions
          chmod 600 /home/runner/.ssh/github_actions
          ssh-agent -a $SSH_AUTH_SOCK > /dev/null
          ssh-add /home/runner/.ssh/github_actions

          rsyncopts=(--recursive --delete --links --times --chmod=D0755,F0755 --compress --compress-choice=zstd --rsh="ssh -o StrictHostKeyChecking=no" --human-readable)
          website_dir="ubuntu@dev-websites.cpp.al:/var/www/mrdox.com"
          demo_dir="$website_dir/demos/${{ github.ref_name }}"

          # Copy files: This step will copy the landing page and the documentation to www.mrdocs.com
          time rsync "${rsyncopts[@]}" --exclude=llvm+clang/ --exclude=demos/ --exclude=roadmap/ $(pwd)/build/website/ "$website_dir"/

          # Copy demos: This step will copy the demos to www.mrdocs.com/demos
          time rsync "${rsyncopts[@]}" $(pwd)/demos/ "$demo_dir"/

      - name: Create changelog
        uses: alandefreitas/cpp-actions/create-changelog@v1.9.2
        with:
          output-path: CHANGELOG.md
          thank-non-regular: ${{ startsWith(github.ref, 'refs/tags/') }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          limit: 150
          update-summary: ${{ runner.os == 'Linux' && 'true' || 'false' }}

      - name: Create GitHub Package Release
        if: env.IS_PUBLISH_REF == 'true'
        uses: softprops/action-gh-release@v2
        with:
          files: packages/MrDocs-*.*.*-*.*
          fail_on_unmatched_files: true
          name: ${{ github.ref_name || github.ref }}
          tag_name: ${{ github.ref_name || github.ref }}${{ ((!startsWith(github.ref, 'refs/tags/')) && '-release') || '' }}
          body_path: CHANGELOG.md
          prerelease: false
          draft: false
          token: ${{ github.token }}

  llvm-releases:
    needs: [ cpp-matrix, build ]
    if: ${{ needs.cpp-matrix.outputs.llvm-matrix != '[]' && needs.cpp-matrix.outputs.llvm-matrix != '' }}
    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJSON(needs.cpp-matrix.outputs.llvm-matrix) }}

    defaults:
      run:
        shell: bash

    name: ${{ matrix.name }} LLVM Release
    runs-on: ${{ matrix.runs-on }}
    container: ${{ matrix.container }}
    env: ${{ matrix.env }}
    permissions:
      contents: write

    steps:
      - name: Ensure Node
        if: matrix.container != '' && env.ACT == 'true'
        run: |
          set -e
          apt-get update
          apt-get install -y nodejs npm
          if ! command -v node >/dev/null 2>&1 && command -v nodejs >/dev/null 2>&1; then
            ln -s /usr/bin/nodejs /usr/bin/node
          fi

      # This calculates a couple of variables, which would normally go in to the regular matrix extra-values
      # section, but which depend on paths not known at that point.
      - name: Resolved Matrix
        id: rmatrix
        run: |
          set -euvx

          third_party_dir=$(realpath $(pwd)/..)/third-party
          if [[ "${{ runner.os }}" == 'Windows' ]]; then
              third_party_dir=$(echo "$third_party_dir" | sed 's/\\/\//g; s|^/d/|D:/|')
          fi
          echo "third-party-dir=$third_party_dir" >> $GITHUB_OUTPUT

          llvm_path=$third_party_dir/llvm
          echo "llvm-path=$llvm_path" >> $GITHUB_OUTPUT

          llvm_cache_key="${{ matrix.llvm-archive-basename }}"
          llvm_cache_key="${llvm_cache_key//:/-}"
          echo "llvm-cache-key=$llvm_cache_key" >> $GITHUB_OUTPUT

      - name: Install packages
        uses: alandefreitas/cpp-actions/package-install@v1.9.2
        id: package-install
        with:
          apt-get: ${{ matrix.install }}

      - name: LLVM Binaries
        id: llvm-cache
        uses: actions/cache@v4
        with:
          path: ${{ steps.rmatrix.outputs.llvm-path }}
          key: ${{ steps.rmatrix.outputs.llvm-cache-key }}