build-python.yml

# this file includes 4 stages
# 1. pre-commit - runs pre-commit using `.pre-commit-config.yaml`
# 2. build-scratch - (if pre-commit pass) then we build the project from scratch (single python versions) and pytest
# 3. build-wheels - (if pre-commit pass) then we build all the wheels for all valid versions
# 4. test-wheels - (if build-scratch and build-wheel passes) then we install wheel and run pytest for all python versions

name: CI
on:
  workflow_dispatch:
    inputs:
      debug_enabled:
        type: boolean
        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
        required: false
        default: false
  push:
    paths-ignore:
      - "docs/**"
  pull_request:
    branches:
      - "*"

jobs:
  pre-commit:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-python@v6
      with:
        python-version: '3.12'
    - uses: pre-commit/action@v3.0.1

  build-scratch:
    name: "${{ matrix.runs-on }} • py${{ matrix.python }}"
    needs: pre-commit
    defaults:
      run:
        shell: bash
    strategy:
      fail-fast: false
      matrix:
        include:
          # To minimise the computational resources, we only use a single python version and the final test-wheels for all python versions
          - runs-on: ubuntu-latest
            python: '3.12'
            triplet: x64-linux-mixed

          - runs-on: windows-latest
            python: '3.12'
            triplet: x64-windows-mixed

          - runs-on: macos-latest
            python: '3.12'
            triplet: arm64-osx-mixed

    env:
      VCPKG_DEFAULT_TRIPLET: ${{ matrix.triplet }}
    runs-on: ${{ matrix.runs-on }}

    steps:
    - uses: actions/checkout@v6

    - uses: actions/setup-python@v6
      with:
        python-version: ${{ matrix.python }}

    - name: Install CUDA Toolkit (Linux)
      if: runner.os == 'Linux'
      uses: Jimver/cuda-toolkit@v0.2.30
      with:
        cuda: '12.6.2'
        method: 'network'
        sub-packages: '["nvcc", "cudart"]'

    - name: Install CUDA Toolkit (Windows)
      if: runner.os == 'Windows'
      uses: Jimver/cuda-toolkit@v0.2.30
      with:
        cuda: '12.6.2'
        method: 'network'
        sub-packages: '["nvcc", "cudart", "visual_studio_integration"]'

    - name: Download and unpack ROMs
      run: ./scripts/download_unpack_roms.sh

    - name: Build
      run: python -m pip install --verbose .[test]

    - name: Test
      run: python -m pytest

  build-wheels:
    name: "${{ matrix.runs-on }} • ${{ matrix.arch }}"
    needs: pre-commit
    defaults:
      run:
        shell: bash
    strategy:
      fail-fast: false
      matrix:
        include:
          - runs-on: ubuntu-latest
            arch: x86_64
          - runs-on: ubuntu-24.04-arm
            arch: aarch64
          - runs-on: windows-latest
            arch: AMD64
          - runs-on: macos-latest
            arch: arm64
    runs-on: ${{ matrix.runs-on }}

    steps:
      - uses: actions/checkout@v6

        # For Linux, the CUDA Toolkit is installed the dockerfile
      - name: Install CUDA Toolkit (Windows)
        if: runner.os == 'Windows'
        uses: Jimver/cuda-toolkit@v0.2.30
        with:
          cuda: '12.6.2'
          method: 'network'
          sub-packages: '["nvcc", "cudart", "visual_studio_integration"]'

      - name: Set up Docker Buildx
        if: runner.os == 'linux'
        id: buildx
        uses: docker/setup-buildx-action@v3
        with:
          install: true
      - name: Build Docker image with vcpkg
        if: runner.os == 'linux'
        # using build-push-action (without push) to make use of cache arguments
        uses: docker/build-push-action@v7
        with:
          context: .
          file: ".github/docker/manylinux-${{ matrix.arch }}-vcpkg.Dockerfile"
          tags: "manylinux-${{ matrix.arch }}-vcpkg:latest"
          push: false
          load: true

      - name: Download and unpack ROMs
        run: ./scripts/download_unpack_roms.sh

      - name: Build wheels
        uses: pypa/cibuildwheel@v3.0
        env:
          CIBW_ARCHS: "${{ matrix.arch }}"

      - name: Upload wheels
        uses: actions/upload-artifact@v7
        with:
          name: wheels-${{ runner.os }}-${{ matrix.arch }}
          path: ./wheelhouse/*.whl

  test-wheels:
    name: Test wheels
    needs: [build-wheels, build-scratch]

    strategy:
      fail-fast: false
      matrix:
        include:
          # example wheel names (if the wheel names change, look at the `ls wheels/` for the new names)
          # ale_py-0.x.x-cp310-cp310-macosx_11_0_arm64.whl
          # ale_py-0.x.x-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
          # ale_py-0.x.x-cp310-cp310-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
          # ale_py-0.x.x-cp310-cp310-win_amd64.whl
          - runs-on: ubuntu-latest
            python: '3.10'
            wheel-name: 'cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64'
            arch: 'x86_64'
          - runs-on: ubuntu-latest
            python: '3.11'
            wheel-name: 'cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64'
            arch: 'x86_64'
          - runs-on: ubuntu-latest
            python: '3.12'
            wheel-name: 'cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64'
            arch: 'x86_64'
          - runs-on: ubuntu-latest
            python: '3.13'
            wheel-name: 'cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64'
            arch: 'x86_64'

          - runs-on: ubuntu-24.04-arm
            python: '3.10'
            wheel-name: 'cp310-cp310-manylinux_2_27_aarch64.manylinux_2_28_aarch64'
            arch: 'aarch64'
          - runs-on: ubuntu-24.04-arm
            python: '3.11'
            wheel-name: 'cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64'
            arch: 'aarch64'
          - runs-on: ubuntu-24.04-arm
            python: '3.12'
            wheel-name: 'cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64'
            arch: 'aarch64'
          - runs-on: ubuntu-24.04-arm
            python: '3.13'
            wheel-name: 'cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64'
            arch: 'aarch64'

          - runs-on: windows-latest
            python: '3.10'
            wheel-name: 'cp310-cp310-win_amd64'
            arch: AMD64
          - runs-on: windows-latest
            python: '3.11'
            wheel-name: 'cp311-cp311-win_amd64'
            arch: AMD64
          - runs-on: windows-latest
            python: '3.12'
            wheel-name: 'cp312-cp312-win_amd64'
            arch: AMD64
          - runs-on: windows-latest
            python: '3.13'
            wheel-name: 'cp313-cp313-win_amd64'
            arch: AMD64

          - runs-on: macos-latest
            python: '3.10'
            wheel-name: 'cp310-cp310-macosx_13_0_arm64'
            arch: arm64
          - runs-on: macos-latest
            python: '3.11'
            wheel-name: 'cp311-cp311-macosx_13_0_arm64'
            arch: arm64
          - runs-on: macos-latest
            python: '3.12'
            wheel-name: 'cp312-cp312-macosx_13_0_arm64'
            arch: arm64
          - runs-on: macos-latest
            python: '3.13'
            wheel-name: 'cp313-cp313-macosx_13_0_arm64'
            arch: arm64

    runs-on: ${{ matrix.runs-on }}

    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python }}

      - uses: actions/download-artifact@v8
        with:
          name: wheels-${{ runner.os }}-${{ matrix.arch }}

      - run: ls

      - name: Install ALE wheel
        # wildcarding doesn't work for some reason, therefore, update the project version here
        run: python -m pip install "ale_py-0.11.2-${{ matrix.wheel-name }}.whl[test]"

      - name: Test
        run: python -m pytest

  test-numpy-1-x:
    name: Test NumPy 1.X
    needs: [build-wheels, build-scratch]

    strategy:
      fail-fast: false
      matrix:
        include:
          - runs-on: ubuntu-latest
            wheel-name: 'cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64'
            arch: 'x86_64'
          - runs-on: ubuntu-24.04-arm
            wheel-name: 'cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64'
            arch: 'aarch64'
            # NumPy 1.X is incompatible with Windows
#          - runs-on: windows-latest
#            wheel-name: 'cp313-cp313-win_amd64'
#            arch: AMD64
          - runs-on: macos-latest
            wheel-name: 'cp313-cp313-macosx_13_0_arm64'
            arch: arm64

    runs-on: ${{ matrix.runs-on }}

    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: "3.13"

      - uses: actions/download-artifact@v8
        with:
          name: wheels-${{ runner.os }}-${{ matrix.arch }}

      - run: ls

      - name: Install ALE wheel
        # wildcarding doesn't work for some reason, therefore, update the project version here
        run: python -m pip install "ale_py-0.11.2-${{ matrix.wheel-name }}.whl[test]"

      - name: Install NumPy 1.X
        run: python -m pip install "numpy<2.0"

      - name: Test
        run: python -m pytest --ignore=tests/python/test_atari_vector_xla.py