ci-build.yaml

name: CI

on:
  # Trigger the workflow on push or pull request,
  # but only for the main branch
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

permissions: {}
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
  # Don't cancel in-progress jobs for main branches.
  cancel-in-progress: ${{ github.ref != 'main' }}

env:
  UV_DEFAULT_INDEX: "https://us-python.pkg.dev/ml-oss-artifacts-published/pypi-mirror/simple"
  PIP_INDEX_URL: "https://us-python.pkg.dev/ml-oss-artifacts-published/pypi-mirror/simple"

jobs:
  lint_and_typecheck:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
        with:
          persist-credentials: false
      - name: Set up Python 3.11
        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548  # v6.1.0
        with:
          python-version: 3.11
      - run: python -m pip install pre-commit
      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: ~/.cache/pre-commit
          key: pre-commit-${{ env.pythonLocation }}-${{ hashFiles('.pre-commit-config.yaml', 'setup.py') }}
      - run: pre-commit run --show-diff-on-failure --color=always --all-files

  build:
    # Don't execute in fork due to runner type
    if: github.repository == 'jax-ml/jax'
    name: "build ${{ matrix.name-prefix }} (py ${{ matrix.python-version }} on ubuntu-22.04, x64=${{ matrix.enable-x64}})"
    runs-on: linux-x86-n4-32
    container:
      image: index.docker.io/library/ubuntu@sha256:4e0171b9275e12d375863f2b3ae9ce00a4c53ddda176bd55868df97ac6f21a6e # ratchet:ubuntu:22.04
    timeout-minutes: 60
    strategy:
      matrix:
        # Test the oldest and newest supported Python versions here.
        include:
          - name-prefix: "with 3.11"
            python-version: "3.11"
            enable-x64: 1
            prng-upgrade: 1
            num_generated_cases: 1
          - name-prefix: "with 3.14"
            python-version: "3.14"
            enable-x64: 0
            prng-upgrade: 0
            num_generated_cases: 1
    steps:
    - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
      with:
        persist-credentials: false
    - name: Image Setup
      run: |
        apt update
        apt install -y libssl-dev
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548  # v6.1.0
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        pip install uv~=0.5.30
        uv pip install --system .[minimum-jaxlib] -r build/test-requirements.txt

    - name: Run tests
      env:
        JAX_NUM_GENERATED_CASES: ${{ matrix.num_generated_cases }}
        JAX_ENABLE_X64: ${{ matrix.enable-x64 }}
        JAX_ENABLE_CUSTOM_PRNG: ${{ matrix.prng-upgrade }}
        JAX_THREEFRY_PARTITIONABLE: ${{ matrix.prng-upgrade }}
        JAX_ENABLE_CHECKS: true
        JAX_SKIP_SLOW_TESTS: true
        PY_COLORS: 1
      run: |
        echo "JAX_NUM_GENERATED_CASES=$JAX_NUM_GENERATED_CASES"
        echo "JAX_ENABLE_X64=$JAX_ENABLE_X64"
        echo "JAX_ENABLE_CUSTOM_PRNG=$JAX_ENABLE_CUSTOM_PRNG"
        echo "JAX_THREEFRY_PARTITIONABLE=$JAX_THREEFRY_PARTITIONABLE"
        echo "JAX_ENABLE_CHECKS=$JAX_ENABLE_CHECKS"
        echo "JAX_SKIP_SLOW_TESTS=$JAX_SKIP_SLOW_TESTS"
        pytest -n auto --tb=short --maxfail=20 tests examples


  documentation:
    name: Documentation - test code snippets
    runs-on: ubuntu-latest
    timeout-minutes: 10
    strategy:
      matrix:
        python-version: ['3.12']
    steps:
    - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
      with:
        persist-credentials: false
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548  # v6.1.0
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        pip install uv~=0.5.30
        uv pip install --system -r docs/requirements.txt
    - name: Test documentation
      env:
        XLA_FLAGS: "--xla_force_host_platform_device_count=8"
        JAX_TRACEBACK_FILTERING: "off"
        JAX_ARRAY: 1
        PY_COLORS: 1
      run: |
        pytest -n auto --tb=short --doctest-glob='*.md' --doctest-glob='*.rst' docs --doctest-continue-on-failure --ignore=docs/multi_process.md
        pytest -n auto --tb=short --doctest-modules jax --ignore=jax/config.py --ignore=jax/experimental/jax2tf --ignore=jax/_src/lib/mlir --ignore=jax/_src/lib/triton.py --ignore=jax/_src/lib/mosaic_gpu.py --ignore=jax/interpreters/mlir.py --ignore=jax/experimental/array_serialization --ignore=jax/collect_profile.py --ignore=jax/_src/tpu_custom_call.py --ignore=jax/experimental/mosaic --ignore=jax/experimental/pallas --ignore=jax/_src/pallas --ignore=jax/lib


  documentation_render:
    name: Documentation - render documentation
    runs-on: linux-x86-n4-16
    container:
      image: index.docker.io/library/ubuntu@sha256:4e0171b9275e12d375863f2b3ae9ce00a4c53ddda176bd55868df97ac6f21a6e #  ratchet:ubuntu:22.04
    timeout-minutes: 10
    strategy:
      matrix:
        python-version: ['3.11']
    steps:
    - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
      with:
        persist-credentials: false
    - name: Image Setup
      run: |
        apt update
        apt install -y libssl-dev libsqlite3-dev build-essential
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548  # v6.1.0
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        pip install uv~=0.5.30
        uv pip install --system -r docs/requirements.txt
    - name: Render documentation
      run: |
        sphinx-build -j auto --color -W --keep-going -b html docs docs/build/html

  ffi:
    name: FFI example
    runs-on: linux-x86-g2-16-l4-1gpu
    container:
      image: index.docker.io/tensorflow/build:latest-python3.12@sha256:48e99608fe9434ada5b14e19fdfd8e64f4cfc83aacd328b9c2101b210e984295 # ratchet:index.docker.io/tensorflow/build:latest-python3.12
    timeout-minutes: 30
    steps:
    - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
      with:
        persist-credentials: false
    - name: Set up Python
      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548  # v6.1.0
      with:
        python-version: 3.12
    - name: Install JAX
      run: |
        pip install uv~=0.5.30
        uv pip install --system .[cuda12]
    - name: Build and install example project
      run: uv pip install --system ./examples/ffi[test]
      env:
        # We test building using GCC instead of clang. All other JAX builds use
        # clang, but it is useful to make sure that FFI users can compile using
        # a different toolchain. GCC is the default compiler on the
        # 'ubuntu-latest' runner, but we still set this explicitly just to be
        # clear.
        CMAKE_ARGS: -DCMAKE_CXX_COMPILER=g++ -DJAX_FFI_EXAMPLE_ENABLE_CUDA=ON
    - name: Run CPU tests
      run: python -m pytest examples/ffi/tests
      env:
        JAX_PLATFORM_NAME: cpu
    - name: Run GPU tests
      run: python -m pytest examples/ffi/tests