ci.yml

name: CI

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

env:
  # Latest stable release verified on 2026-10-24; keep this pin and
  # .xlings.json/release.yml aligned. Engine sources stay unchanged.
  MCPP_VERSION: "2026.10.24.1"

jobs:
  # ── Platform × toolchain matrix ─────────────────────────────────────────
  # Every leg source-builds the vendored OpenCV 5 (+ compat.ffmpeg) cold:
  # ~2700 TUs. The ~/.mcpp/registry cache carries toolchains and the built
  # compat.ffmpeg across runs; timeout is sized for the COLD path.
  #
  # All five legs are required. Notes on the two that were experimental:
  #   linux-musl  — needed mcpp-index#110 (compat.ffmpeg
  #                 -Wno-error=incompatible-pointer-types for musl's ioctl
  #                 signature); merged as e83ed49, green since.
  #   windows     — per-glob flags live in [target.'cfg(windows)'.build.flags]
  #                 (mcpp#258, landed in 0.0.102), still keyed on the
  #                 generated/windows/tu/w*/ stub paths; removing the stub layer
  #                 itself is tracked in #17.
  test:
    name: ${{ matrix.name }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 150
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - name: linux-gcc
            ort_toolchain: gcc@16.1.0
            os: ubuntu-latest
            suffix: linux-x86_64
            ext: tar.gz
            mcpp: bin/mcpp
            setup: |
              mcpp toolchain install gcc 16.1.0
              mcpp toolchain default gcc@16.1.0
            experimental: false
            features: true
            examples: true
          - name: linux-llvm-22
            ort_toolchain: llvm@22.1.8
            os: ubuntu-latest
            suffix: linux-x86_64
            ext: tar.gz
            mcpp: bin/mcpp
            # gcc first: `mcpp toolchain install llvm` does not pull the
            # xim glibc runtime its binaries are patchelf'd against (their
            # ELF interpreter lives under xim-x-glibc/2.39 → exec 127 on a
            # bare runner); the gcc install brings it.
            # mcpp packaging gap: mcpp-community/mcpp#259.
            setup: |
              mcpp toolchain install gcc 16.1.0
              mcpp toolchain install llvm 22.1.8
              mcpp toolchain default llvm@22.1.8
            experimental: false
            features: false
            examples: false
          - name: linux-musl-static
            os: ubuntu-latest
            suffix: linux-x86_64
            ext: tar.gz
            mcpp: bin/mcpp
            setup: |
              mcpp toolchain install gcc 16 --target x86_64-linux-musl
              mcpp toolchain default gcc@16.1.0 --target x86_64-linux-musl
            experimental: false
            features: false
            examples: false
          - name: macos-llvm
            ort_toolchain: llvm@23.1.3
            os: macos-15
            suffix: macosx-arm64
            ext: tar.gz
            mcpp: bin/mcpp
            setup: ""   # mcpp resolves its macOS default (llvm) itself
            experimental: false
            features: false
            examples: false
          - name: windows-llvm
            ort_toolchain: llvm@23.1.3
            os: windows-latest
            suffix: windows-x86_64
            ext: zip
            mcpp: bin/mcpp.exe
            setup: ""
            experimental: false
            features: false
            examples: false
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Mwrap identity and bilingual README contract
        run: python3 tools/check_mwrap_release.py

      - name: Restore mcpp registry cache
        uses: actions/cache@v4
        with:
          # Holds toolchains AND built deps (compat.ffmpeg, gtest), so a
          # repeat run rebuilds little. Keyed per leg; prefix-restores across
          # manifest changes.
          path: ~/.mcpp/registry
          key: mcpp-registry-${{ matrix.name }}-${{ env.MCPP_VERSION }}-${{ hashFiles('mcpp.toml', '.github/workflows/ci.yml') }}
          restore-keys: |
            mcpp-registry-${{ matrix.name }}-${{ env.MCPP_VERSION }}-

      - name: Download mcpp
        shell: bash
        env:
          MCPP_ARCHIVE: mcpp-${{ env.MCPP_VERSION }}-${{ matrix.suffix }}.${{ matrix.ext }}
          MCPP_ROOT: mcpp-${{ env.MCPP_VERSION }}-${{ matrix.suffix }}
        run: |
          curl -L -fsS -o "$MCPP_ARCHIVE" \
            "https://github.com/mcpp-community/mcpp/releases/download/v${MCPP_VERSION}/${MCPP_ARCHIVE}"
          case "$MCPP_ARCHIVE" in
            *.zip) powershell -NoProfile -Command "Expand-Archive -Force -Path '${MCPP_ARCHIVE}' -DestinationPath '.'" ;;
            *)     tar -xzf "$MCPP_ARCHIVE" ;;
          esac
          root="$PWD/$MCPP_ROOT"
          mkdir -p "$HOME/.mcpp/registry"
          cp -a "$root/registry/." "$HOME/.mcpp/registry/"
          if [[ "$RUNNER_OS" == "Windows" ]]; then
            echo "$(cygpath -m "$root/bin")" >> "$GITHUB_PATH"
          else
            echo "$root/bin" >> "$GITHUB_PATH"
          fi

      - name: Set up toolchain
        if: matrix.setup != ''
        shell: bash
        run: |
          ${{ matrix.setup }}
          mcpp --version

      - name: Template lint
        if: matrix.features
        shell: bash
        # A scaffold ships INSIDE the release tarball and is never compiled by
        # this CI (a path-dep consumer cold-rebuilds all of OpenCV, ~40 min),
        # so two static checks stand in for the missing build:
        #   1. Placeholders: mcpp's renderer knows exactly {{project.name}} /
        #      {{self.name}} / {{self.version}} — anything else ships literally.
        #   2. stdio-macro / import-std footgun: `import std;` does NOT export
        #      the C macros stderr/stdout/stdin (modules never export macros),
        #      so a template TU touching one must also `#include <cstdio>`.
        #      v0.0.7's template used std::println(stderr, …) under a bare
        #      `import std;` and scaffolded non-compiling code; this guards it.
        run: |
          bad=$(grep -rno '{{[^}]*}}' templates/ | grep -v -E '\{\{(project\.name|self\.name|self\.version)\}\}' || true)
          if [ -n "$bad" ]; then echo "unknown template placeholders:"; echo "$bad"; exit 1; fi
          fail=0
          while IFS= read -r tu; do
            grep -qE '\bimport[[:space:]]+std\b' "$tu" || continue
            if grep -qE '\b(stderr|stdout|stdin)\b' "$tu" && ! grep -qE '#[[:space:]]*include[[:space:]]*<cstdio>' "$tu"; then
              echo "::error file=$tu::uses a <cstdio> macro (stderr/stdout/stdin) under 'import std;' without '#include <cstdio>' — modules do not export macros, so the scaffold will not compile"
              fail=1
            fi
          done < <(find templates -name '*.cpp.in' -o -name '*.cc.in' -o -name '*.cpp' -o -name '*.cc')
          exit $fail

      - name: Generated macro mappings match pinned headers
        shell: bash
        run: python3 tools/generate_macros.py --check

      - name: Embedded upstream notices match retained sources
        shell: bash
        run: |
          python3 tools/test_source_notices.py
          python3 tools/generate_source_notices.py --check

      - name: Generated scalar conversions match the pinned SDK
        shell: bash
        run: python3 tools/generate_saturate.py --check

      - name: Generated DNN shape helpers match the pinned SDK
        shell: bash
        run: python3 tools/generate_dnn_shapes.py --check

      - name: Generated persistence helpers match the pinned SDK
        shell: bash
        run: python3 tools/generate_persistence.py --check

      - name: Generated portable helpers and value operators match the pinned SDK
        shell: bash
        run: |
          python3 tools/generate_inline_helpers.py --check
          python3 tools/generate_cuda_helpers.py --check
          python3 tools/generate_simd.py --check
          python3 tools/generate_simd_legacy.py --check
          python3 tools/generate_objdetect_constants.py --check
          python3 tools/generate_type_ops.py --check
          python3 tools/generate_mat_aug_ops.py --check
          python3 tools/test_export_diagnostics.py

      - name: Build
        shell: bash
        run: mcpp build

      - name: Build configuration newline regression
        if: matrix.name == 'linux-gcc'
        shell: bash
        run: python3 tools/test_build_config.py target/.build-mcpp/build.mcpp.bin

      # Guard the module-interface BMIs against non-baseline target features.
      # A src/*.cppm compiled with -msse3/-mavx/-march=… bakes that feature
      # into opencv.<mod>.pcm; a consumer TU compiled at plain baseline then
      # cannot load it (clang -Wmodule-file-config-mismatch → "use of
      # undeclared identifier 'cv'"). The library .cpp legitimately need SSE3
      # (OpenCV's x86_64 baseline), so it is applied per-glob to the library
      # TUs only — this asserts it never leaked back onto an interface unit.
      - name: Module-interface baseline guard
        shell: bash
        run: python3 tools/check_interface_flags.py

      - name: Test
        shell: bash
        run: mcpp test

      - name: Candidate codec and ORT index
        uses: actions/checkout@v4
        with:
          repository: mcpplibs/mcpp-index
          ref: 7e5a54ccee615e2f8b1a32b34dd9cd7d5c2c55cb
          path: .candidate-index

      - name: WebP lossless alpha, animation and metadata
        shell: bash
        run: |
          if [[ "${{ matrix.name }}" == "linux-musl-static" ]]; then
            python3 tools/test_candidate.py --index .candidate-index --toolchain gcc@16.1.0 --target x86_64-linux-musl --features imgcodecs-webp --filter webp_codec
          else
            python3 tools/test_candidate.py --index .candidate-index --toolchain "${{ matrix.ort_toolchain }}" --features imgcodecs-webp --filter webp_codec
          fi

      - name: WebP disabled dependency boundary
        if: matrix.name == 'linux-llvm-22'
        shell: bash
        run: python3 tools/test_candidate.py --index .candidate-index --toolchain llvm@22.1.8 --features imgcodecs --filter webp_codec --absent-dependency compat.libwebp

      - name: Image codec feature tests
        shell: bash
        run: mcpp test --features imgcodecs-png,imgcodecs-jpeg

      - name: All main modules and generated-input algorithm behavior
        shell: bash
        run: |
          mcpp test --features all-modules,simd --strict --timeout 120
          python3 tools/check_interface_flags.py
          python3 tools/check_cpp_contracts.py

      - name: C++ declaration and header coverage inventory
        if: matrix.name == 'linux-llvm-22'
        shell: bash
        run: |
          python3 tools/test_audit_api.py
          python3 tools/check_interface_flags.py
          python3 tools/audit_api.py --verify-exports
          python3 tools/probe_unlisted_api.py
          python3 tools/check_entity_review.py --require-complete
          python3 tools/check_header_review.py

      - name: Preserve C++ inventory for review
        if: matrix.name == 'linux-llvm-22' && always()
        uses: actions/upload-artifact@v4
        with:
          name: opencv-cpp-inventory
          path: |
            target/api-audit/inventory.json
            target/api-audit/includes.log
            target/api-audit/export-consumer.log
            target/api-audit/unlisted-import-probe/
          if-no-files-found: error

      - name: Actual default project template
        if: matrix.name == 'linux-llvm-22'
        shell: bash
        run: python3 tools/test_template.py --toolchain llvm@22.1.8

      - name: Native SDK versus module persistence formats
        shell: bash
        run: python3 tools/check_persistence_format.py

      - name: Native SDK versus module portable helper behavior
        shell: bash
        run: python3 tools/check_utility_helpers.py

      - name: Original SDK versus module Matx and Vec template contracts
        shell: bash
        run: python3 tools/check_matx_templates.py

      - name: Original SDK versus qualified FP state and opaque videoio APIs
        shell: bash
        run: python3 tools/check_fp_state.py

      - name: Original SDK versus Mat augmented assignment signatures and behavior
        shell: bash
        run: python3 tools/check_mat_aug.py

      - name: Original SDK versus DNN equality and unavailable backend contracts
        shell: bash
        run: python3 tools/check_dnn_compat.py

      - name: Native SDK versus module baseline SIMD behavior
        shell: bash
        run: |
          python3 tools/check_simd.py
          python3 tools/check_interface_flags.py

      - name: Original SDK versus module software SIMD behavior
        shell: bash
        run: |
          python3 tools/check_simd.py --emulated
          python3 tools/check_interface_flags.py

      - name: Optimized software SIMD behavior
        if: matrix.name == 'linux-gcc'
        shell: bash
        run: python3 tools/check_simd.py --emulated --profile release

      - name: Features without the optional DNN surface
        if: matrix.name == 'linux-llvm-22'
        shell: bash
        run: mcpp test --features features --strict --timeout 120

      - name: Feature tests (dnn + unifont module interfaces)
        if: matrix.features
        shell: bash
        run: mcpp test --features dnn,unifont

      - name: Linux native GTK3 window and actual window template
        if: matrix.name == 'linux-llvm-22'
        shell: bash
        run: |
          sudo apt-get update
          sudo apt-get install -y xvfb pkg-config
          xvfb-run -a mcpp test --features highgui-native --timeout 60
          xvfb-run -a python3 tools/test_template.py --toolchain llvm@22.1.8 --template window --run-arg=--smoke-test

      - name: Native Win32 or Cocoa window
        if: runner.os == 'Windows' || runner.os == 'macOS'
        shell: bash
        run: mcpp test --features highgui-native --timeout 60

      - name: Native video backend and FFmpeg file roundtrips
        shell: bash
        run: mcpp test --features videoio-native,videoio-ffmpeg --strict --timeout 120

      - name: Actual video project template
        if: matrix.ort_toolchain
        shell: bash
        run: python3 tools/test_template.py --toolchain "${{ matrix.ort_toolchain }}" --template video

      - name: OpenCV ONNX Runtime CPU execution proof and actual project template
        if: matrix.ort_toolchain
        shell: bash
        run: |
          python3 tools/generate_ort_model.py --check
          python3 tools/test_candidate.py --index .candidate-index --toolchain "${{ matrix.ort_toolchain }}"
          python3 tools/test_template.py --index .candidate-index --template onnxruntime --toolchain "${{ matrix.ort_toolchain }}"

      # NOTE examples are exercised locally, not here: each one is a path-dep
      # consumer that cold-rebuilds the whole vendored OpenCV (+ffmpeg) in its
      # own target/ (~40 min per example on a 4-core runner) while adding
      # little over what `mcpp test` already covers. Revisit if mcpp learns
      # to share dep artifacts with path-dep consumers.