ci.yml

name: Continuous Integration

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

  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
    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: Checkout
        uses: actions/checkout@v4

      - name: Generate Test Matrix
        uses: alandefreitas/cpp-actions/cpp-matrix@v1.8.12
        id: cpp-matrix
        with:
          compilers: |
            gcc >=14
            clang >=18
            msvc >=14.40
            apple-clang *
          standards: '20'
          latest-factors: |
            msvc Optimized-Debug
            gcc UBSan Coverage
            clang UBSan ASan MSan
            apple-clang UBSan ASan
          factors: ''
          runs-on: |
            apple-clang: macos-15
          containers: |
            clang: ubuntu:24.04
          build-types: |
            gcc: Release
            gcc Coverage: Release
            clang: Release
            apple-clang: Release
            msvc: RelWithDebInfo
            msvc Optimized-Debug: Debug
          ccflags: |
            msvc Optimized-Debug: /Ob1 /O2 /Zi
          cxxflags: |
            msvc Optimized-Debug: /Ob1 /O2 /Zi
          install: |
            gcc: git build-essential pkg-config python3 curl openjdk-11-jdk pkg-config libncurses-dev libxml2-utils libxml2-dev
            gcc Coverage: git build-essential pkg-config python3 curl openjdk-11-jdk pkg-config libncurses-dev libxml2-utils libxml2-dev lcov
            clang: git build-essential pkg-config python3 curl openjdk-11-jdk pkg-config libncurses-dev libxml2-utils libxml2-dev g++-14=14.2.0-4ubuntu2~24.04
            msvc: ''
          extra-values: |
            use-libcxx: {{#if (and (ieq compiler 'clang') (ge major 19)) }}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: 3f797a8342c3dbe4a260b26f948d8776ff490431
            llvm-build-preset-prefix: {{#if optimized-debug}}optimizeddebug{{else}}{{{lowercase build-type}}}{{/if}}
            llvm-build-preset-os: {{#if (ieq os 'windows') }}win{{else}}unix{{/if}}
            llvm-sanitizer: {{#if (eq compiler 'gcc')}}{{else if ubsan}}-UBSan{{else if asan}}-ASan{{else if msan}}-MSan{{/if}}
            llvm-build-preset: {{{ llvm-build-preset-prefix }}}-{{{ llvm-build-preset-os }}}
            llvm-compiler-version: {{#if (or (contains version '*') (contains version '^'))}}{{else}}-{{{ version }}}{{/if}}
            llvm-archive-basename: llvm-{{{ lowercase os }}}-{{{ compiler }}}{{{ llvm-compiler-version }}}-{{{ llvm-build-preset-prefix }}}{{{ llvm-sanitizer }}}-{{{ substr llvm-hash 0 7 }}}
            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 ubsan}}Undefined{{else if asan}}Address{{else if msan}}MemoryWithOrigins{{/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: {{#if (and (eq compiler 'gcc') (not asan)) }}-static{{/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

      # 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:
      # 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.8.12
        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.8.7
        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.8.12
        id: setup-cpp
        with:
          compiler: ${{ matrix.compiler }}
          version: ${{ matrix.version }}

      # 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.8.12
        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

      # 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

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

      - name: Download LLVM Binaries
        id: llvm-download
        if: steps.llvm-cache.outputs.cache-hit != 'true'
        run: |
          set -x
          url=https://mrdocs.com/llvm+clang/${{ matrix.llvm-archive-filename }}
          http_status=$(curl -s -o /dev/null -w "%{http_code}" -I "$url")
          if [ "$http_status" -eq 200 ]; then
              found="true"
              echo "found=$found" >> $GITHUB_OUTPUT
              curl -L -o ${{ matrix.llvm-archive-filename }} "$url"
              install_prefix=${{ steps.rmatrix.outputs.llvm-path }}
              mkdir -p $install_prefix
              if [[ ${{ matrix.llvm-archive-extension }} == '7z' ]]; then
                  7z x ${{ matrix.llvm-archive-filename }} -o$install_prefix
              else
                  tar -xjf ${{ matrix.llvm-archive-filename }} -C $install_prefix
              fi
              if [[ $(ls -1 $install_prefix | wc -l) -eq 1 ]]; then
                  single_dir=$(ls -1 $install_prefix)
                  if [[ -d $install_prefix/$single_dir ]]; then
                      mv $install_prefix/$single_dir/* $install_prefix/
                      rmdir $install_prefix/$single_dir
                  fi
              fi
          else
              found="false"
              echo "found=$found" >> $GITHUB_OUTPUT
          fi

      # 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: Install libc++
        id: install_libcxx
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.8.12
        if: matrix.use-libcxx == 'true' && steps.llvm-cache.outputs.cache-hit != 'true' && steps.llvm-download.outputs.found != 'true'
        with:
          cmake-version: '>=3.26'
          source-dir: ../third-party/llvm-project/runtimes
          git-repository: https://github.com/llvm/llvm-project.git
          git-tag: ${{ matrix.llvm-hash }}
          download-dir: ../third-party/llvm-project
          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.8.12
        if: steps.llvm-cache.outputs.cache-hit != 'true' && steps.llvm-download.outputs.found != 'true'
        with:
          cmake-version: '>=3.26'
          source-dir: ../third-party/llvm-project/llvm
          git-repository: https://github.com/llvm/llvm-project.git
          git-tag: ${{ matrix.llvm-hash }}
          download-dir: ../third-party/llvm-project
          patches: |
            ./third-party/llvm/CMakePresets.json
            ./third-party/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 Duktape
        uses: alandefreitas/cpp-actions/cmake-workflow@v1.8.12
        with:
          source-dir: ../third-party/duktape
          url: https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz
          patches: |
            ./third-party/duktape/CMakeLists.txt
            ./third-party/duktape/duktapeConfig.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.8.12
        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.8.12
        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 duktape_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/duktape/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

      - 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: 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.8.12
        if: matrix.time-trace
        with:
          build-dir: build
          github_token: ${{ secrets.GITHUB_TOKEN }}

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

          # Find gcov
          gcov_tool="gcov"
          for version in "${{steps.setup-cpp.outputs.version-major}}.${{steps.setup-cpp.outputs.version-minor}}" "${{steps.setup-cpp.outputs.version-major}}"; do
            if command -v "gcov-$version" &> /dev/null; then
              gcov_tool="gcov-$version"
              break
            fi
          done

          dir="./build"
          lcov --rc lcov_branch_coverage=0 --gcov-tool "$gcov_tool" --directory "$dir" --capture --output-file "$dir/all.info" --ignore-errors inconsistent
          lcov --rc lcov_branch_coverage=0 --ignore-errors inconsistent --list "$dir/all.info"
          echo "file=$(realpath "$dir/all.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:
      - name: Install packages
        uses: alandefreitas/cpp-actions/package-install@v1.8.12
        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: Download MrDocs package
        uses: actions/download-artifact@v4
        with:
          name: ${{ matrix.mrdocs-release-package-artifact }}
          path: packages

      - name: Install MrDocs from Package
        run: |
          set -x
          
          # Delete packages/_CPack_Packages files from previous runs
          rm -rf packages/_CPack_Packages
          
          # Print tree structure
          find packages -print | sed 's;[^/]*/;|____;g;s;____|; |;g'
          
          if [[ ${{ runner.os }} != 'Windows' ]]; then
              dest_dir="$HOME/local"
              mkdir -p "$dest_dir" 
              find packages -maxdepth 1 -name 'MrDocs-*.tar.gz' -exec tar -vxzf {} -C $dest_dir --strip-components=1 \;              
          else
              dest_dir="$GITHUB_WORKSPACE/usr/local"
              dest_dir=$(echo "$dest_dir" | sed 's/\\/\//g')
              find packages -maxdepth 1 -name "MrDocs-*.7z" -exec 7z x {} -o$dest_dir \;
              if [[ $(ls -1 $dest_dir | wc -l) -eq 1 ]]; then
                  single_dir=$(ls -1 $dest_dir)
                  if [[ -d $dest_dir/$single_dir ]]; then
                      mv $dest_dir/$single_dir/* $dest_dir/
                      rmdir $dest_dir/$single_dir
                  fi
              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.8.12
        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

      - 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"
          
                # 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 -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: github.event_name == 'push' && (contains(fromJSON('["master", "develop"]'), github.ref_name) || startsWith(github.ref, 'refs/tags/')) && runner.os == 'Linux'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: build/website
          force_orphan: true

      - name: Publish website
        if: github.event_name == 'push' && (contains(fromJSON('["master", "develop"]'), github.ref_name) || startsWith(github.ref, 'refs/tags/')) && runner.os == 'Linux'
        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/ $(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.8.12
        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: ${{ github.event_name == 'push' && (contains(fromJSON('["master", "develop"]'), github.ref_name) || startsWith(github.ref, 'refs/tags/')) }}
        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:
      # 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

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

      - name: Check website releases
        id: website-releases
        run: |
          set -x
          archive_url="https://mrdocs.com/llvm+clang/${{ matrix.llvm-archive-filename }}"
          http_status=$(curl -s -o /dev/null -w "%{http_code}" -I "$archive_url")
          if [ "$http_status" -eq 200 ]; then
              exists="true"
          else
              exists="false"
          fi
          echo "exists=$exists" >> $GITHUB_OUTPUT

      - name: LLVM Binaries
        id: llvm-cache
        if: steps.website-releases.outputs.exists != 'true'
        uses: actions/cache@v4
        with:
          path: ${{ steps.rmatrix.outputs.llvm-path }}
          key: ${{ matrix.llvm-archive-basename }}

      - name: Compress LLVM
        id: llvm-upload
        if: steps.llvm-cache.outputs.cache-hit == 'true'
        shell: bash
        run: |
          # LLVM is be installed with the default compiler
          set -x

          # Use 7z on windows
          if [[ ${{ runner.os }} == 'Windows' ]]; then
              7z a -t7z -m0=lzma2 -mx=9 -mfb=64 -md=32m -ms=on "${{ matrix.llvm-archive-filename }}" "${{ steps.rmatrix.outputs.llvm-path }}"
          else
              tar -cjf "${{ matrix.llvm-archive-filename }}" -C "${{ steps.rmatrix.outputs.llvm-path }}/.." llvm
          fi

      - name: Website LLVM Releases
        if: steps.llvm-cache.outputs.cache-hit == 'true' && github.event_name == 'push' && (contains(fromJSON('["master", "develop"]'), github.ref_name) || startsWith(github.ref, 'refs/tags/'))
        run: |
          set -x
          
          # Ensure required commands exist
          for cmd in ssh-keyscan ssh-agent ssh-add scp; do
            if ! command -v $cmd >/dev/null; then
              echo "$cmd not found"
              exit 1
            fi
          done
          
          # Add SSH key
          mkdir -p ~/.ssh
          ssh-keyscan dev-websites.cpp.al >> ~/.ssh/known_hosts
          chmod 600 ~/.ssh/known_hosts
          echo "${{ secrets.DEV_WEBSITES_SSH_KEY }}" > ~/.ssh/github_actions
          chmod 600 ~/.ssh/github_actions

          # Start ssh-agent and add the key
          SSH_AUTH_SOCK="$RUNNER_TEMP/ssh_agent.sock"
          export SSH_AUTH_SOCK
          ssh-agent -a $SSH_AUTH_SOCK > /dev/null
          ssh-add ~/.ssh/github_actions

          # Copy llvm archive: This step will copy the archive to www.mrdocs.com/llvm+clang
          llvm_dir="/var/www/mrdox.com/llvm+clang"
          chmod 755 ${{ matrix.llvm-archive-filename }}
          scp -o StrictHostKeyChecking=no $(pwd)/${{ matrix.llvm-archive-filename }} ubuntu@dev-websites.cpp.al:$llvm_dir/