build.yml

name: Build

on:
  push:
    branches: [main]
    tags: ['*']
  pull_request:
  workflow_dispatch:

# Read only by default. The publish job asks for the OIDC token it needs itself.
permissions:
  contents: read

# Cancel in-progress runs if a new push lands on the same branch.
concurrency:
  group: build-${{ github.ref }}
  cancel-in-progress: true

env:
  DOTNET_CLI_TELEMETRY_OPTOUT: true
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
  DOTNET_NOLOGO: true

jobs:
  windows:
    name: windows
    runs-on: windows-latest
    timeout-minutes: 30
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up .NET
        uses: actions/setup-dotnet@v6
        with:
          global-json-file: global.json

      # The tag is the version: tag 1.2.3 (or v1.2.3) builds 1.2.3. Other builds use the
      # Version in Directory.Build.props.
      - name: Resolve the version from the tag
        if: startsWith(github.ref, 'refs/tags/')
        shell: bash
        run: echo "VERSION_ARGUMENT=-p:Version=${GITHUB_REF_NAME#v}" >> "$GITHUB_ENV"

      # A plain build is also the pack step: ProjectDefaults sets GeneratePackageOnBuild for every
      # Release package project, so this produces ./nugets as a side effect. Windows is the job
      # that packs, because DiffEngineTray is WinForms and is excluded from Release-NotWindows.
      - name: Build
        run: dotnet build src --configuration Release ${{ env.VERSION_ARGUMENT }}

      - name: Test
        run: dotnet test --solution src/DiffEngine.slnx --configuration Release --no-build --no-restore

      - name: AOT publish
        run: dotnet publish src/DiffEngine.AotTests/DiffEngine.AotTests.csproj --configuration Release

      - name: Upload received on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: received-windows
          path: '**/*.received.*'
          if-no-files-found: ignore
          retention-days: 14

      # The log names a failing test and how long it took, and nothing about what ran beside it.
      # A test that fails on time alone, because the process was stalled for a quarter of a
      # minute, cannot be explained from that. The report has when every test started and ended.
      - name: Upload test reports on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: test-reports-windows
          path: '**/TestResults/*-report.html'
          if-no-files-found: ignore
          retention-days: 14

      # PH0001 warns when a RID has no native renderer. Shipping a package that cannot run on a
      # platform it claims to support is worse than failing the release.
      - name: Verify every RID has a native renderer
        if: startsWith(github.ref, 'refs/tags/')
        shell: bash
        run: |
          missing=0
          check() {
            directory="src/$1/runtimes/$2/native"
            if [ -z "$(ls -A "$directory" 2>/dev/null)" ]; then
              echo "::error::No native renderer for $2. Run the build-native workflow."
              missing=1
            fi
          }
          # No Windows RIDs: that head renders with WinForms and loads no native library.
          check DiffEngineViewer.Linux linux-x64
          check DiffEngineViewer.Linux linux-arm64
          check DiffEngineViewer.Mac osx-x64
          check DiffEngineViewer.Mac osx-arm64
          exit $missing

      - name: Upload packages
        if: success()
        uses: actions/upload-artifact@v7
        with:
          name: nupkgs
          path: nugets/*.nupkg
          if-no-files-found: warn
          retention-days: 30

  unix:
    name: ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        # macOS carries committed pixel baselines, and Core Text rasterisation moves between OS
        # versions, so when macos-latest moves to a new image the OSX baselines may have to be
        # taken again from this job's received-* artifacts.
        os: [ubuntu-latest, macos-latest]
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up .NET
        uses: actions/setup-dotnet@v6
        with:
          global-json-file: global.json

      # raylib links against X11, GL and friends. xvfb plus the Mesa software rasteriser are what
      # the pixel snapshots run against.
      - name: Install native dependencies
        if: runner.os == 'Linux'
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            cmake ninja-build \
            libx11-dev libxrandr-dev libxi-dev libxcursor-dev libxinerama-dev \
            libgl1-mesa-dev libglu1-mesa-dev libwayland-dev libxkbcommon-dev \
            xvfb libgl1-mesa-dri

      # CMake fetches raylib and imgui, so without this every PR re-clones and recompiles them.
      # Keyed on the shim's own sources, which is what actually changes.
      - name: Cache native build
        if: runner.os == 'Linux'
        uses: actions/cache@v6
        with:
          path: native/build
          key: native-linux-x64-${{ hashFiles('native/CMakeLists.txt', 'native/src/**', 'native/include/**') }}

      # Built here rather than taken from the committed binaries, so the Linux job tests the
      # current native source and the pixel baselines track it.
      - name: Build native renderer
        if: runner.os == 'Linux'
        run: |
          cmake -S native -B native/build/linux-x64 -G Ninja -DCMAKE_BUILD_TYPE=Release
          cmake --build native/build/linux-x64
          mkdir -p src/DiffEngineViewer.Linux/runtimes/linux-x64/native
          cp native/build/linux-x64/libdiffengine_viewer.so src/DiffEngineViewer.Linux/runtimes/linux-x64/native/

      # Same reason as the Linux build above, and the same trade. Before it, a change to
      # native/swift did not reach this job at all until build-native had run and its binaries PR
      # had been merged, so the macOS baselines described the previous rebuild and a Swift change
      # could not go red here however wrong it was.
      #
      # Only this runner's own architecture, because this is the only thing that loads it. The
      # committed universal binary is still loaded and still checked, by the native job below —
      # which is the job that exists to prove what actually ships.
      #
      # The tray's library too, which the same package builds, so MacTrayTests hands its menu to
      # the Swift as it is now rather than as it was at the last rebuild.
      #
      # Not cached: this is a handful of Swift files against system frameworks, twenty-odd seconds,
      # and a stale cache here would reintroduce exactly the staleness the step removes.
      - name: Build native renderer
        if: runner.os == 'macOS'
        run: |
          swift build -c release --package-path native/swift
          bin="$(swift build -c release --package-path native/swift --show-bin-path)"
          mkdir -p src/DiffEngineViewer.Mac/runtimes/osx-arm64/native src/DiffEngineTray.Mac/runtimes/osx-arm64/native
          cp "$bin/libdiffengine_viewer.dylib" src/DiffEngineViewer.Mac/runtimes/osx-arm64/native/
          cp "$bin/libdiffengine_tray.dylib" src/DiffEngineTray.Mac/runtimes/osx-arm64/native/

      # Release-NotWindows drops the WinForms tray and its tests from the solution.
      - name: Build
        run: dotnet build src --configuration Release-NotWindows

      - name: Test
        run: dotnet test --solution src/DiffEngine.slnx --configuration Release-NotWindows --no-build --no-restore

      # Pinned to one rasteriser rather than one platform: llvmpipe is pure software and so more
      # reproducible than any GPU driver, and ImGui rasterises glyphs itself.
      - name: Pixel snapshots
        if: runner.os == 'Linux'
        env:
          DIFFENGINE_VIEWER_PIXEL_TESTS: 'true'
          LIBGL_ALWAYS_SOFTWARE: '1'
          GALLIUM_DRIVER: llvmpipe
        # Release, not Release-NotWindows: that is a solution level configuration which the slnx
        # maps to a project configuration of Release, so the output lives in bin/Release. Naming
        # the solution configuration here points at a directory that never exists.
        run: >
          xvfb-run -a --server-args="-screen 0 1920x1080x24"
          dotnet test src/DiffEngineViewer.Tests/DiffEngineViewer.Tests.csproj
          --configuration Release --no-build --no-restore

      # No xvfb and no GL flags: deview_capture on this platform draws into a bitmap context of its
      # own making, so it needs neither a window nor a window server. Determinism is pinned inside
      # that call rather than by the environment.
      - name: Pixel snapshots
        if: runner.os == 'macOS'
        env:
          DIFFENGINE_VIEWER_PIXEL_TESTS: 'true'
        run: >
          dotnet test src/DiffEngineViewer.Tests/DiffEngineViewer.Tests.csproj
          --configuration Release --no-build --no-restore

      - name: Upload received on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: received-${{ matrix.os }}
          path: '**/*.received.*'
          if-no-files-found: ignore
          retention-days: 14

  # A test process inside a WSL distribution can start a diff tool installed on Windows. Every
  # part of that which can be tested without a distribution is, in the jobs above. This job is for
  # the rest: what a distribution's mount table and ps really say, and whether a program on the
  # host can be started from inside one, handed a file by its translated path, found again and
  # ended. Under WSL 1 as well as 2, since the two mount drives and reach the host differently.
  #
  # The tests are built on the runner and run inside the distribution from where they were built,
  # which is a Windows drive mounted into it. That is one build rather than two, and needs only
  # the .NET runtime inside, not the SDK. It also means WslLiveTests is the only class that can be
  # run this way: tests that find their fixtures by the path they were compiled at get a Windows
  # path there.
  #
  # Not among the jobs a release waits for. It is new, and a runner image that stops offering WSL
  # should not be what holds a package back.
  wsl:
    name: wsl ${{ matrix.version }}
    runs-on: windows-latest
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        version: [1, 2]
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up .NET
        uses: actions/setup-dotnet@v6
        with:
          global-json-file: global.json

      # Debug and one framework: Release also packs, and publishes every viewer head to do it.
      - name: Build
        run: dotnet build src/DiffEngine.Tests/DiffEngine.Tests.csproj --configuration Debug --framework net10.0

      # procps for ps, which is how a running tool is found, and curl for the runtime's installer.
      - name: Install a distribution
        uses: Vampire/setup-wsl@v7
        with:
          distribution: Ubuntu-24.04
          wsl-version: ${{ matrix.version }}
          additional-packages: curl ca-certificates procps

      # Build server variables stay on the Windows side, as they do for anyone's build that runs
      # its tests in WSL, so in here this is a developer machine. That is what is being tested.
      #
      # Without ICU, which the distribution does not have and these tests do not need.
      - name: Test
        shell: wsl-bash {0}
        run: |
          if [ -z "${WSL_DISTRO_NAME:-}" ]; then
            echo "::error::WSL_DISTRO_NAME is not set, so every test would be skipped"
            exit 1
          fi
          echo "WSL $(wslinfo --wsl-version 2>/dev/null || echo unknown), kernel $(uname -r)"
          grep -E 'drvfs' /proc/mounts || true

          curl -sSL https://dot.net/v1/dotnet-install.sh -o /tmp/dotnet-install.sh
          bash /tmp/dotnet-install.sh --channel 10.0 --runtime dotnet --install-dir "$HOME/.dotnet"
          export DOTNET_ROOT="$HOME/.dotnet"
          export DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1

          cd "$(wslpath -u '${{ github.workspace }}')/src/DiffEngine.Tests/bin/Debug/net10.0"
          "$DOTNET_ROOT/dotnet" DiffEngine.Tests.dll --treenode-filter "/*/*/WslLiveTests/*"

  # Neither job above loads a committed binary any more: both build the shim from source so their
  # pixel baselines track it. That leaves nothing testing what actually ships, which is this job.
  # It loads the committed binaries as they are, which is what catches a wrong architecture, a file
  # corrupted by a text mode checkout, an unsatisfied runtime dependency, or simply a rebuild that
  # was never merged.
  #
  # It runs DiffEngineViewer.Tests rather than the whole suite: that is where the native smoke test
  # lives, it takes seconds, and it gives the screen and IPC tests some cross architecture coverage
  # for free. On macOS also DiffEngineTray.Core.Tests, whose MacTrayTests loads the tray's library.
  native:
    name: native ${{ matrix.rid }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 20
    strategy:
      fail-fast: false
      matrix:
        include:
          # osx-x64 has no entry: GitHub's Intel macOS runners are being retired and a job
          # targeting one now sits queued indefinitely. Both macOS RIDs ship the same universal
          # dylib, so loading it here covers the arm64 slice and the step below checks that the
          # x86_64 slice is present.
          #
          # linux-x64 is here because it is the RID most people run and nothing else loads its
          # committed binary: the Ubuntu job above overwrites that file with a fresh build before
          # testing, so a linux-x64 rebuild that was never merged would have shipped unnoticed.
          #
          # No Windows entry either, since that head renders with WinForms and loads nothing.
          - rid: osx-arm64
            os: macos-latest
          - rid: linux-x64
            os: ubuntu-24.04
          - rid: linux-arm64
            os: ubuntu-24.04-arm
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up .NET
        uses: actions/setup-dotnet@v6
        with:
          global-json-file: global.json

      # Runtime libraries only, not the -dev packages: the shim links X11 and GL, so loading it
      # needs them present even though nothing here opens a window.
      - name: Install runtime dependencies
        if: runner.os == 'Linux'
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            libx11-6 libxrandr2 libxi6 libxcursor1 libxinerama1 libgl1 libglx-mesa0

      # The runtime load above only exercises the arm64 slice. Assert the x86_64 one is there too,
      # since osx-x64 ships this identical file and cannot be loaded anywhere in CI.
      - name: Check the macOS dylibs are universal
        if: matrix.rid == 'osx-arm64'
        run: |
          for rid in osx-arm64 osx-x64; do
            for dylib in \
              "src/DiffEngineViewer.Mac/runtimes/$rid/native/libdiffengine_viewer.dylib" \
              "src/DiffEngineTray.Mac/runtimes/$rid/native/libdiffengine_tray.dylib"; do
              archs=$(lipo -archs "$dylib")
              echo "$dylib: $archs"
              for arch in x86_64 arm64; do
                case " $archs " in
                  *" $arch "*) ;;
                  *) echo "::error::$dylib is missing the $arch slice"; exit 1 ;;
                esac
              done
            done
          done

      - name: Test
        run: dotnet test src/DiffEngineViewer.Tests/DiffEngineViewer.Tests.csproj --configuration Release

      - name: Test the tray's library
        if: matrix.rid == 'osx-arm64'
        run: dotnet test src/DiffEngineTray.Core.Tests/DiffEngineTray.Core.Tests.csproj --configuration Release

      - name: Upload received on failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: received-${{ matrix.rid }}
          path: '**/*.received.*'
          if-no-files-found: ignore
          retention-days: 14

  # The tray ships as DiffEngineTray, which only names a package for each RID, and those packages.
  # The packaging tests read them; only `dotnet tool install` choosing between them shows the
  # right one is found for a machine, and only starting what it laid out shows that it runs. So
  # this installs the tray from the windows job's packages, on each platform, as someone would
  # from nuget.org, and waits for the installed tray to listen on the piper port.
  #
  # From a source of those packages alone. Until a release, their version is the one in
  # Directory.Build.props, which nuget.org already has as an older tray, and an install that could
  # see nuget.org might take that one.
  tray-install:
    name: tray install ${{ matrix.os }}
    needs: windows
    runs-on: ${{ matrix.os }}
    timeout-minutes: 10
    strategy:
      fail-fast: false
      matrix:
        os: [windows-latest, ubuntu-latest, macos-latest]
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up .NET
        uses: actions/setup-dotnet@v6
        with:
          global-json-file: global.json

      - name: Download packages
        uses: actions/download-artifact@v8
        with:
          name: nupkgs
          path: packages

      # The command is an apphost the CLI writes from the dll, as for a portable tool, so the path
      # the login item names is the same after an update.
      - name: Install and start the tray
        if: runner.os != 'Windows'
        shell: bash
        run: |
          version=$(ls packages | sed -n 's/^DiffEngineTray\.\([0-9].*\)\.nupkg$/\1/p')
          rid=$(dotnet --info | sed -n 's/^ *RID: *//p' | head -1)
          printf '<configuration><packageSources><clear /><add key="built" value="%s" /></packageSources></configuration>' \
            "$PWD/packages" > "$RUNNER_TEMP/nuget.config"
          tray="$RUNNER_TEMP/tray"
          dotnet tool install DiffEngineTray --tool-path "$tray" --configfile "$RUNNER_TEMP/nuget.config" --version "$version"

          tool="$tray/.store/diffenginetray/$version/diffenginetray.$rid/$version/tools/net10.0/$rid"
          test -x "$tool/viewer/$rid/DiffEngineViewer" || { echo "::error::No viewer for $rid at $tool/viewer"; exit 1; }
          test -f "$tool/viewer/documents/DiffEngineViewer.Documents.dll" || { echo "::error::No documents folder at $tool/viewer"; exit 1; }

          "$tray/DiffEngineTray" &
          pid=$!
          listening=
          for i in $(seq 1 30); do
            if (exec 3<>/dev/tcp/127.0.0.1/3492) 2>/dev/null; then
              listening=1
              break
            fi
            sleep 1
          done
          cat "$tool/logs/log.txt" || true
          kill "$pid" || true
          [ -n "$listening" ] || { echo "::error::The installed tray did not listen on 3492"; exit 1; }

      # On Windows the command has to be a GUI apphost as well: a Run key naming a console one, or
      # a .cmd, opens a console at every login.
      - name: Install and start the tray
        if: runner.os == 'Windows'
        shell: pwsh
        run: |
          $pointer = Get-ChildItem packages -Filter 'DiffEngineTray.*.nupkg' | Where-Object { $_.Name -match '^DiffEngineTray\.\d' }
          $version = $pointer.Name -replace '^DiffEngineTray\.(.*)\.nupkg$', '$1'
          $rid = 'win-' + [Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString().ToLowerInvariant()
          Set-Content "$env:RUNNER_TEMP\nuget.config" "<configuration><packageSources><clear /><add key=`"built`" value=`"$PWD\packages`" /></packageSources></configuration>"
          $tray = "$env:RUNNER_TEMP\tray"
          dotnet tool install DiffEngineTray --tool-path $tray --configfile "$env:RUNNER_TEMP\nuget.config" --version $version
          if ($LASTEXITCODE -ne 0) { exit 1 }

          $tool = "$tray\.store\diffenginetray\$version\diffenginetray.$rid\$version\tools\net10.0\$rid"
          if (-not (Test-Path "$tool\viewer\$rid\DiffEngineViewer.exe")) { Write-Output "::error::No viewer for $rid at $tool\viewer"; exit 1 }
          if (-not (Test-Path "$tool\viewer\documents\DiffEngineViewer.Documents.dll")) { Write-Output "::error::No documents folder at $tool\viewer"; exit 1 }

          $shim = "$tray\DiffEngineTray.exe"
          $bytes = [IO.File]::ReadAllBytes($shim)
          $subsystem = [BitConverter]::ToUInt16($bytes, [BitConverter]::ToInt32($bytes, 0x3C) + 0x5C)
          if ($subsystem -ne 2) { Write-Output "::error::$shim is not a GUI apphost (subsystem $subsystem)"; exit 1 }

          $process = Start-Process $shim -PassThru
          $listening = $false
          foreach ($attempt in 1..30) {
            $client = [Net.Sockets.TcpClient]::new()
            try { $client.Connect('127.0.0.1', 3492); $listening = $true } catch { } finally { $client.Dispose() }
            if ($listening) { break }
            Start-Sleep -Seconds 1
          }
          Get-Content "$tool\logs\log.txt" -ErrorAction SilentlyContinue
          Stop-Process -Id $process.Id -ErrorAction SilentlyContinue
          if (-not $listening) { Write-Output "::error::The installed tray did not listen on 3492"; exit 1 }

  # Trusted publishing: no stored API key. nuget.org validates GitHub's OIDC token against the
  # policy naming this repository and this workflow file, and returns a key good for an hour.
  # Waits on every job, so a package only ships once all platforms, the committed native
  # binaries and an install of the tray from its packages have passed.
  publish:
    needs: [windows, unix, native, tray-install]
    environment: nuget
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      id-token: write
    steps:
      - name: Download packages
        uses: actions/download-artifact@v8
        with:
          name: nupkgs
          path: packages

      - name: NuGet login
        id: login
        uses: NuGet/login@v1
        with:
          user: SimonCropp

      - name: Push to nuget.org
        run: >
          dotnet nuget push "packages/**/*.nupkg"
          --api-key ${{ steps.login.outputs.NUGET_API_KEY }}
          --source https://api.nuget.org/v3/index.json
          --skip-duplicate