macos.yml

# Copyright 2025 The Khronos Group Inc.
# SPDX-License-Identifier: Apache-2.0
name: macOS & iOS CI

# Seems no way to avoid duplicating this on logic in each .yml file.
# See https://github.com/actions/starter-workflows/issues/245.
on:
  # Trigger the workflow on a pull request,
  pull_request:

  push:
    # And on pushes to main, which will occur when a PR is merged.
    branches:
      - main
    # Also trigger on push of release tags to any branch. Useful
    # for testing release builds before merging to main.
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'
      - 'v[0-9]+.[0-9]+.[0-9]+-*'
    paths-ignore:
      - .appveyor.yml
      - .github/workflows/android.yml
      - .github/workflows/check-libktx-only.yml
      - .github/workflows/check-mkvk.yml
      - .github/workflows/check-reuse.yml
      - .github/workflows/docs.yml
      - .github/workflows/formatting.yml
      - .github/workflows/linux.yml
      - .github/workflows/mingw.yml
      - .github/workflows/publish-pyktx.yml
      - .github/workflows/manual.yml
      - .github/workflows/web.yml
      - .github/workflows/windows.yml
      - .travis.yml
      - README.md
      - CODE_OF_CONDUCT.md
      - CONTRIBUTING.md
      - LICENSE.md
      - LICENSES
      - RELEASE_NOTES.md
      - REUSE.toml
      - install-gitconfig*
  # Allow manual trigger
  workflow_dispatch:
  workflow_call:

jobs:
  #formatting:
  #  uses: ./.github/workflows/formatting.yml
  macos:
    permissions:
      packages: write
      contents: write
    # Shortcircuit and don't burn CI time when formatting will reject
    #needs: formatting
    strategy:
      matrix:
        os: [ macos-latest ]
        generator: [ Xcode ]
        arch: [ arm64 ]
        vulkan_sdk_version: ['1.4.313.1']
        options: [
          {config: 'Debug,Release', platform: macOS,
           doc: ON, jni: ON, loadtests: OpenGL+Vulkan, py: ON, tools: ON, tools_cts: ON,
           package: YES, sse: ON, opencl: OFF},
          {config: Release, platform: macOS,
           doc: OFF, jni: OFF, loadtests: OFF, py: OFF, tools: OFF, tools_cts: OFF,
           sse: ON, opencl: ON},
          {config: Release, platform: macOS,
           doc: OFF, jni: OFF, loadtests: OFF, py: OFF, tools: OFF, tools_cts: OFF,
           sse: OFF, opencl: ON},
          {config: Release, platform: macOS,
           doc: OFF, jni: OFF, loadtests: OFF, py: OFF, tools: OFF, tools_cts: OFF,
           sse: OFF, opencl: OFF}
        ]
        exclude:
          # Disable this when package: YES because the Python and Java interface
          # libraries built for x86_64 will not run on arm64. Have not investigated
          # why Rosetta does not work in this case.
          - arch: x86_64
            options: { package: YES }
        include:
          - name: Build x86_64 package on Intel runner
            os: macos-15-intel
            arch: x86_64
            options: {
              config: 'Debug,Release', platform: macOS,
               doc: ON, jni: ON, loadtests: OpenGL+Vulkan, py: ON, tools: ON, tools_cts: ON,
               package: YES, sse: ON, opencl: OFF
            }
          - name: Build for iOS
            os: macos-latest
            generator: Xcode
            arch: arm64
            options: {
              config: Release, platform: iOS,
              doc: OFF, jni: OFF, loadtests: OpenGL+Vulkan, py: OFF, tests: OFF, tools: OFF, tools_cts: OFF,
              package: YES, sse: OFF, opencl: OFF
            }

    # ': ' within the format string causes a "mapping values are not
    # allowed in this context" YAML syntax error. Replacement {1} is
    # a workaround.
    name: ${{ matrix.name && matrix.name || format('{0} ({1}) Package,SSE,OpenCL:{2}{3},{4},{5}', matrix.os, matrix.arch, ' ', matrix.options.package && matrix.options.package || 'NO', matrix.options.sse, matrix.options.opencl) }}
    runs-on: ${{ matrix.os }}
    env:
      # To avoid bandwidth charges skip downloading source and golden images
      # for texturetests etc., loadtests and legacy tool tests. They will be
      # pulled later as necessary
      GIT_LFS_SKIP_SMUDGE: 1
      HOMEBREW_NO_AUTO_UPDATE: 1
      APPLE_ID: ${{ secrets.APPLE_ID }}
      DEVELOPMENT_TEAM: ${{ secrets.APPLE_DEVELOPMENT_TEAM }}
      PKG_SIGN_IDENTITY: ${{ secrets.APPLE_PKG_SIGN_IDENTITY }}
      CODE_SIGN_IDENTITY: ${{ secrets.APPLE_CODE_SIGN_IDENTITY }}

      BUILD_DIR: build
      REL_DESC_FILE: "build/rel_desc.md"

      # Map test matrix elements to environmental variables, so that scripts launched from CI scripts may react to them.
      # Some matrix variables have defaults if unspecified by the matrix
      CMAKE_GEN: ${{ matrix.generator }}
      ARCH: ${{ matrix.arch }} # iOS uses ARCH
      ARCHS: ${{ matrix.arch }} # macOS uses ARCHS
      CONFIGURATION: ${{ matrix.options.config }}
      PLATFORM: ${{ matrix.options.platform }}
      FEATURE_DOC: ${{ matrix.options.doc }}
      FEATURE_JNI: ${{ matrix.options.jni }}
      FEATURE_LOADTESTS: ${{ matrix.options.loadtests }}
      FEATURE_PY: ${{ matrix.options.py }}
      FEATURE_TESTS: ${{ matrix.options.tests && matrix.options.tests || 'ON' }}
      FEATURE_TOOLS: ${{ matrix.options.tools }}
      FEATURE_TOOLS_CTS: ${{ matrix.options.tools_cts }}
      PACKAGE: ${{ matrix.options.package && matrix.options.package || 'NO' }}
      SUPPORT_OPENCL: ${{ matrix.options.opencl }}
      SUPPORT_SSE: ${{ matrix.options.sse }}
      WASM_BUILD: ${{ matrix.options.wasm && matrix.options.wasm || 'OFF' }}
      # Virtual env (ON) is needed because pre-installed python is "externally managed."
      PY_USE_VENV: ${{ matrix.options.py.use_venv && matrix.options.py_use_venv || 'ON' }}
      WERROR: ${{ matrix.options.werror && matrix.options.werror || 'ON' }}
      # CC Handled by job step
      # CXX Handled by job step

      PYTHON_DIST_DIR: interface/python_binding/dist

      VCPKG_INSTALL_OPTIONS: ${{ matrix.vcpkg_install_options && matrix.vcpkg_install_options || '' }}

      VULKAN_SDK_VERSION: ${{ matrix.vulkan_sdk_version }}
    # This is just to tell the Vulkan install script where to install.
    # NOTE: Hardcoded $HOME expansion, due to 'env' context being unavailble in env:
      VULKAN_INSTALL_DIR: /Users/runner/VulkanSDK/${{ matrix.vulkan_sdk_version }}
      VULKAN_SDK: /Users/runner/VulkanSDK/${{ matrix.vulkan_sdk_version }}/macOS

    steps:
      - uses: actions/checkout@v4
        with:
          # Fetch all history to make sure tags are
          # included (used for version creation)
          fetch-depth: 0

      - name: Add certificates to macOS keychain
        env:
          MACOS_CERTIFICATES_P12: ${{ secrets.MACOS_CERTIFICATES_P12 }}
          MACOS_CERTIFICATES_PASSWORD: ${{ secrets.MACOS_CERTIFICATES_PASSWORD }}
          ALTOOL_PASSWORD: ${{ secrets.ALTOOL_PASSWORD }}
          ALTOOL_PW_LABEL: ${{ secrets.ALTOOL_PW_LABEL }}
        run: ./scripts/before_build_macos.sh

      - name: Force fetch provoking tag's annotation.
        # Work around https://github.com/actions/checkout/issues/290.
        if: github.ref_type == 'tag' && matrix.check_mkvk != 'ONLY'
        run: git fetch -f origin ${{ github.ref }}:${{ github.ref }}

      - name: before_install
        run: |
          echo -n "Running on the following GitHub Actions CI runner: " && uname -a
          echo -n "CMake version on the runner is " && cmake --version

      - name: Install Doxygen
        if: matrix.options.doc == 'ON'
        uses: ssciwr/doxygen-install@v1

      - name: Install Graphviz
        if: matrix.options.doc == 'ON'
        uses: ts-graphviz/setup-graphviz@v2

      # Should a specific version of Python ever be wanted, use this.
#      - name: Set up Python
#        if: matrix.options.py == 'ON' && matrix.check_mkvk != 'ONLY'
#        uses: actions/setup-python@v5
#        with:
#          python-version: '3.14'

      # If the selected Python does not have virtualenv installed, use this.
      # It is included currently in the runner's pre-installed Pythons.
      #
      # Note that the builds, via sdist and wheel, require a virtual env.
      # regardless of whether the in-use Python is externally managed.
      # Installing the explicit dependencies of pyktx only needs virtualenv
      # and PY_USE_VENV: ON when Python is externally managed.
#      - name: Install Python virtualenv
#        if: matrix.options.py == 'ON' && matrix.check_mkvk != 'ONLY'
#        run: pip install virtualenv

      # A brute-force hack to enable installation of nuget on Intel runners.
      # nuget, installed by Brew, requires Python 3.14 which Brew, naturally,
      # tries to install as the runner has only 3.13 which was not installed
      # by Brew leading to failure when Brew tries to update these links.
      # Apple Silicon runners have Brew-installed 3.14.
      - name: Remove Python links to enable Brew Install of nuget
        if: matrix.options.loadtests != 'OFF' && matrix.os == 'macos-15-intel'
        run: sudo rm -f /usr/local/bin/idle3 /usr/local/bin/idle3.13 /usr/local/bin/pip3 -> /Library/Frameworks/Python.framework/Versions/3.13/bin/pip3 /usr/local/bin/pip3.13 /usr/local/bin/pydoc3 /usr/local/bin/pydoc3.13 /usr/local/bin/python3 /usr/local/bin/python3-config /usr/local/bin/python3.13 /usr/local/bin/python3.13-config

      - name: Install nuget and mono
        # nuget & mono were removed from macos 15 runners because mono is
        # unsupported and nuget needs mono. This will install both.
        if: matrix.options.loadtests != 'OFF'
        run: |
            Echo "Python3 version $(python3 --version) is installed at $(which python3)"
            which nuget || brew install nuget -q

      - name: Run install script
        run: ./scripts/install_macos.sh

      - name: Export environment variables for vcpkg binary caching
        if: matrix.options.loadtests != 'OFF'
        # actions/github-script is used primarily because it is the only
        # way to access VCPKG_INSTALLATION_ROOT outside of the runner's shell.
        # Maintaining cross-platform access is desirable so the code can be
        # easily copied to a multi-platform workflow. NUGET_FEED_URL is set
        # here to keep the vcpkg cache environment variables together.
        uses: actions/github-script@v7
        with:
          # JSON in use here. #<comments> in the script will break it.
          # Pre-installed vcpkg location is indicated by a non-standard env.
          # var.
          script: |
            core.exportVariable('VCPKG_ROOT', process.env.VCPKG_INSTALLATION_ROOT || '');
            core.exportVariable('VCPKG_EXE', process.env.VCPKG_INSTALLATION_ROOT + '/vcpkg' || '');
            core.exportVariable('NUGET_FEED_URL', 'https://nuget.pkg.github.com/KhronosGroup/index.json' || '');

      - name: Add NuGet sources for vcpkg binary caching
        if: matrix.options.loadtests != 'OFF'
        env:
          USERNAME: KhronosGroup
        shell: bash
        run: |
            nuget sources add \
            -Source "${{ env.NUGET_FEED_URL }}" \
            -StorePasswordInClearText \
            -Name GitHubPackages \
            -UserName "${{ env.USERNAME }}" \
            -Password "${{ secrets.GITHUB_TOKEN }}"
            nuget setapikey "${{ secrets.GITHUB_TOKEN }}" \
            -Source "${{ env.NUGET_FEED_URL }}"

      - name: before_script
        run: |
          if [ "$FEATURE_TOOLS_CTS" = "ON" ]; then
            git submodule update --init --recursive tests/cts
          fi
          if [ "$FEATURE_TESTS" = "ON" ]; then
            git lfs pull --include=tests/resources
          fi
          # Make sure embedded dates are correct.
          ./install-gitconfig.sh
          scripts/smudge_date.sh

      - name: script
        env:
          VCPKG_BINARY_SOURCES: clear;nuget,${{ env.NUGET_FEED_URL }},readwrite
        run: |
          set -e # Instead of trying to chain everything together with &&
                 # otherwise subsequent commands will swallow bad exit status.
          if [ "$PLATFORM" = "macOS" ]; then
            ./scripts/build_macos.sh
          else
            ./scripts/build_ios.sh
          fi
          set +e

      # Re. packaging, note that the build script only creates packages for
      # the Release configuration. If this is changed work will be needed
      # here to prevent failures from uploading same-named artifacts from both
      # Release and Debug configs. Only uploading artifacts from macos-latest
      # prevents the same failure with artifacts from builds on older OSes.

      # Notarization can only run if secrets were set (upstream repo)
      - name: Notarize
        env:
          ALTOOL_PASSWORD: ${{ secrets.ALTOOL_PASSWORD }}
          ALTOOL_PW_LABEL: ${{ secrets.ALTOOL_PW_LABEL }}
        if: matrix.options.platform == 'macOS' && matrix.options.package == 'YES' && env.APPLE_ID
        run: ./scripts/notarize.sh $BUILD_DIR/KTX-Software-*.pkg $APPLE_ID $DEVELOPMENT_TEAM $ALTOOL_PASSWORD

      - name: Prepare KTX artifacts
        if: matrix.options.package == 'YES'
        id: ktx-version
        run: |
          KTX_VERSION=`cat $BUILD_DIR/ktx.version`
          echo "PACKAGE_NAME_SUFFIX=${KTX_VERSION}-${{matrix.options.platform}}-${{matrix.arch}}" >> $GITHUB_ENV

      # For these artifact uploads, need to take care that only one CLangCL
      # "package" job for each architecture produces artifacts. A second
      # job would attempt to upload a same-named artifact.
      - name: Upload artifact Install Package
        if: matrix.options.package == 'YES'  && (matrix.os == 'macos-latest' || matrix.os == 'macos-15-intel')
        uses: actions/upload-artifact@v4
        with:
          name: KTX-Software-${{env.PACKAGE_NAME_SUFFIX}}
          path: ${{env.BUILD_DIR}}/KTX-Software-*-*
          compression-level: 0 # Installer already compressed.

      - name: Upload artifact pyktx
        if:  matrix.options.py == 'ON' && matrix.options.package == 'YES' && (matrix.os == 'macos-latest' || matrix.os == 'macos-15-intel')
        uses: actions/upload-artifact@v4
        with:
          name: pyktx-${{env.PACKAGE_NAME_SUFFIX}}
          path: ${{env.BUILD_DIR}}/${{env.PYTHON_DIST_DIR}}

      - name: Upload to Release
        uses: softprops/action-gh-release@v2
        if: github.ref_type == 'tag' && github.event_name == 'push' && matrix.options.package == 'YES' && (matrix.os == 'macos-latest' || matrix.os == 'macos-15-intel')
        with:
          draft: true
          prerelease: true
          files: |
              ${{env.BUILD_DIR}}/KTX-Software-*-*
              ${{env.BUILD_DIR}}/${{env.PYTHON_DIST_DIR}}/pyktx-*
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}