ci.yml

# There are two kinds of continuous integration jobs in this project:
#
# - Every code submission or master push passes continuous integration on the
#   minimal supported Rust version and the current stable Rust version.
# - Two times a month, a scheduled job makes sure that the code remains
#   compatible and lint-free on upcoming Rust toolchains (beta and nightly).

name: Continuous Integration

on:
  push:
  pull_request:
  schedule:
    - cron: '0 0 6/15 * *'

# Cancel existing jobs on new pushes to the same branch
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

env:
  CARGO_INCREMENTAL: 0
  RUSTFLAGS: '-D warnings'
  RUSTDOCFLAGS: '-D warnings'
  RUST_LOG: 'info'
  MINIMAL_RUST: '1.75.0'  # Minimal Supported Rust Version
  HWLOC_VERSION: '2.10.0'
  HWLOC_VERSION_SHORT: '2.10'  # Used in URL to official tarball/binaries
  HWLOC_DEBUG_VERBOSE: 0  # Set to 1 when debugging issues inside of hwloc
  HWLOC_HIDE_ERRORS: 0  # Remove if this proves too chatty

jobs:
  # Workaround for github CI dropping env var expansion in matrix strategy
  matrix_vars:
    # Don't run CI twice when a PR is created from a branch internal to the repo
    if: github.event_name == 'push' || github.event_name == 'schedule' || github.event.pull_request.head.repo.full_name != github.repository

    runs-on: ubuntu-latest

    outputs:
      MINIMAL_RUST: ${{ env.MINIMAL_RUST }}

    steps:
      - name: Forward env var to output
        run: echo "MINIMAL_RUST=${{ env.MINIMAL_RUST }}" >> $GITHUB_OUTPUT


  # Formatter output and dependency checking don't depend on cargo features, and
  # only need to be tested on the latest supported release of each CI run.
  #
  # We don't care about warnings on the minimum supported Rust version, only
  # about building and running correctly.
  format-machete:
    # Don't run CI twice when a PR is created from a branch internal to the repo
    if: github.event_name == 'push' || github.event_name == 'schedule' || github.event.pull_request.head.repo.full_name != github.repository

    runs-on: ubuntu-latest

    steps:
      - name: Checkout sources
        uses: actions/checkout@v4

      - name: Set up stable toolchain
        if: github.event_name != 'schedule'
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          components: rustfmt

      - name: Set up nightly toolchain
        if: github.event_name == 'schedule'
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: nightly
          components: rustfmt

      - name: Check format
        run: cargo fmt --all --check

      - name: Set up cargo-binstall
        run: curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash

      - name: Look for unused dependencies with cargo-machete
        run: |
          # FIXME: --force used as a workaround for https://github.com/Swatinem/rust-cache/issues/204
          cargo binstall -y --force cargo-machete
          cargo machete


  # Clippy and rustc lints depend on cfg(), of which we currently use "feature"
  # and "target_os". So far, hwlocality has Linux- and Windows-specific code,
  # but nothing macOS-specific, so we can cover all configurations by testing on
  # Linux and Windows.
  #
  # We don't care about warnings on the minimum supported Rust version, only
  # about building and running correctly.
  lints:
    # Don't run CI twice when a PR is created from a branch internal to the repo
    if: github.event_name == 'push' || github.event_name == 'schedule' || github.event.pull_request.head.repo.full_name != github.repository

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

    strategy:
      matrix:
        os:
          - ubuntu-latest
          - windows-latest
        features:
          - '""'
          - 'hwloc-2_0_4'
          - 'hwloc-2_1_0'
          - 'hwloc-2_2_0'
          - 'hwloc-2_3_0'
          - 'hwloc-2_4_0'
          - 'hwloc-2_5_0'
          - 'hwloc-2_8_0'
          - 'hwloc-2_10_0'
          # Remember to also update scheduled-semver-checks matrix
          - 'hwloc-latest,vendored'
          - 'hwloc-latest,proptest'

    env:
      JOB_FLAGS: '--workspace --features=${{ matrix.features }}'

    steps:
      - name: Checkout sources
        uses: actions/checkout@v4

      - name: Set up stable toolchain
        if: github.event_name != 'schedule'
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          components: clippy

      - name: Set up nightly toolchain
        if: github.event_name == 'schedule'
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: nightly
          components: clippy

      - name: Set up hwloc
        uses: ./.github/actions/setup-hwloc-dependencies
        with:
          hwloc-version: ${{ env.HWLOC_VERSION }}
          hwloc-version-short: ${{ env.HWLOC_VERSION_SHORT }}
        if: contains(matrix.features, 'vendored') == false

      - name: Check clippy lints
        run: cargo clippy ${{ env.JOB_FLAGS }} --all-targets -- -D warnings

      - name: Build docs
        run: cargo doc ${{ env.JOB_FLAGS }}

      - name: Check semver compliance (push/PR version)
        # Not guaranteed to run on nightly, so we use the separate job below
        if: github.event_name != 'schedule'
        uses: obi1kenobi/cargo-semver-checks-action@v2
        with:
          feature-group: default-features
          features: ${{ matrix.features }}
          rust-toolchain: manual

  # Workaround for cargo-semver-checks not guaranteeing nightly support
  scheduled-semver-checks:
    if: github.event_name == 'schedule'

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

    strategy:
      matrix:
        os:
          - ubuntu-latest
          - windows-latest
        features:
          - '""'
          - 'hwloc-2_0_4'
          - 'hwloc-2_1_0'
          - 'hwloc-2_2_0'
          - 'hwloc-2_3_0'
          - 'hwloc-2_4_0'
          - 'hwloc-2_5_0'
          - 'hwloc-2_8_0'
          - 'hwloc-2_10_0'
          # Remember to also update lints matrix
          - 'hwloc-latest,vendored'
          - 'hwloc-latest,proptest'

    steps:
      - name: Checkout sources
        uses: actions/checkout@v4

      - name: Set up stable toolchain
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          components: rustfmt,clippy

      - name: Set up hwloc
        uses: ./.github/actions/setup-hwloc-dependencies
        with:
          hwloc-version: ${{ env.HWLOC_VERSION }}
          hwloc-version-short: ${{ env.HWLOC_VERSION_SHORT }}
        if: contains(matrix.features, 'vendored') == false

      - name: Check semver compliance (scheduled version)
        uses: obi1kenobi/cargo-semver-checks-action@v2
        with:
          feature-group: default-features
          features: ${{ matrix.features }}
          rust-toolchain: manual


  # Run the tests and examples on all supported OSes and Rust versions (main CI)
  #
  # FIXME: In an ideal world, it would be enough to test on the first and last
  #        version of each major hwloc series, as within each series versions
  #        are additive and almost solely (*cough cough* add_distances *cough
  #        cough*) add new features to test without removing any.
  #
  #        Unfortunately, `cargo check` does not currently check doctests
  #        (see https://github.com/rust-lang/cargo/issues/6424 ), so we need to
  #        test each version individually to make sure that doctests for a
  #        feature coming from one hwloc version do not use features from newer
  #        hwloc versions (which would force people to needlessly up their hwloc
  #        version requirements if they want to follow the doc examples).
  test-contrib-debug:
    # Don't run CI twice when a PR is created from a branch internal to the repo
    # Don't run in scheduled jobs, that's what test-scheduled is for
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository

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

    needs: matrix_vars

    strategy:
      matrix:
        os:
          - ubuntu-latest
          - macos-latest
          - windows-latest
        rust:
          - stable
          - ${{ needs.matrix_vars.outputs.MINIMAL_RUST }}
        features:
          - '""'
          - 'hwloc-2_0_4'
          - 'hwloc-2_1_0'
          - 'hwloc-2_2_0'
          - 'hwloc-2_3_0'
          - 'hwloc-2_4_0'
          - 'hwloc-2_5_0'
          - 'hwloc-2_8_0'
          - 'hwloc-2_10_0'
          - 'hwloc-latest,vendored'
          - 'hwloc-latest,proptest'

    env:
      FEATURES_FLAG: '--features=${{ matrix.features }}'

    steps:
      - name: Checkout sources
        uses: actions/checkout@v4

      - name: Set up toolchain
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: ${{ matrix.rust }}

      - name: Set up hwloc
        uses: ./.github/actions/setup-hwloc-dependencies
        with:
          hwloc-version: ${{ env.HWLOC_VERSION }}
          hwloc-version-short: ${{ env.HWLOC_VERSION_SHORT }}
        if: contains(matrix.features, 'vendored') == false

      - name: Set up hwloc build dependencies (macOS)
        run: brew install automake libtool
        if: contains(matrix.features, 'vendored') && startsWith(matrix.os, 'macos')

      - name: Collect system information
        uses: ./.github/actions/system-information
        if: contains(matrix.features, 'vendored') == false

      - name: Run tests
        run: cargo test --workspace ${{ env.FEATURES_FLAG }}

      - name: Install cargo-examples
        uses: baptiste0928/cargo-install@v3
        with:
          crate: cargo-examples

      - name: Run all examples
        run: cargo examples ${{ env.FEATURES_FLAG }}


  # Run the tests and examples on all supported OSes and Rust versions,
  # in release mode
  #
  # Some things like UB or arithmetic overflow differ between debug and release
  # builds, so it's a good idea to run the tests in release mode too.
  #
  # We do not do this in the test-contrib-debug job because switching between
  # debug and release builds trashes the cargo cache.
  #
  # We restrict this to the latest supported hwloc release because the
  # test-contrib-debug job is already testing for basic consistency, so our only
  # goal here is to run as many tests as possible, and running on the latest
  # hwloc release (for all supported compilers and OSes) gives us that.
  test-contrib-release:
    # Don't run CI twice when a PR is created from a branch internal to the repo
    # Don't run in scheduled jobs, that's what test-scheduled is for
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository

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

    needs: matrix_vars

    strategy:
      matrix:
        os:
          - ubuntu-latest
          - macos-latest
          - windows-latest
        rust:
          - stable
          - ${{ needs.matrix_vars.outputs.MINIMAL_RUST }}

    steps:
      - name: Checkout sources
        uses: actions/checkout@v4

      - name: Set up toolchain
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: ${{ matrix.rust }}

      - name: Set up hwloc
        uses: ./.github/actions/setup-hwloc-dependencies
        with:
          hwloc-version: ${{ env.HWLOC_VERSION }}
          hwloc-version-short: ${{ env.HWLOC_VERSION_SHORT }}

      - name: Collect system information
        uses: ./.github/actions/system-information

      - name: Run unit and doc tests
        run: cargo test --workspace --release --features=hwloc-latest

      - name: Install cargo-examples
        uses: baptiste0928/cargo-install@v3
        with:
          crate: cargo-examples

      - name: Run all examples
        run: cargo examples --features=hwloc-latest -- --release


  # Run the tests with extra stdlib checks and the ASAN sanitizer
  #
  # Here, our goal is only code coverage. We noticeably don't need...
  #
  # - Full version coverage (there's test-contrib-debug for that)
  # - Release build coverage (it shouldn't change stdlib usage or turn code with
  #   valid memory accesses into code with invalid ones)
  # - Full OS coverage (we don't test what happens inside of hwloc, so as with
  #   lints, only testing OSes that have specific Rust code associated with them
  #   in the bindings is fine)
  #
  # Also, as a cargo-careful constraint we can only test nightly.
  test-careful:
    # Don't run CI twice when a PR is created from a branch internal to the repo
    if: github.event_name == 'push' || github.event_name == 'schedule' || github.event.pull_request.head.repo.full_name != github.repository

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

    strategy:
      matrix:
        os:
          - ubuntu-latest
          - windows-latest

    env:
      JOB_FLAGS: '--workspace --features=hwloc-latest'
      # cargo-careful uses the nightly compiler, but runs in the stable CI, so
      # we must disable warnings-as-error to avoid breaking submitted PRs when
      # a new lint gets added to nightly rustc
      RUSTFLAGS: ''

    steps:
      - name: Checkout sources
        uses: actions/checkout@v4

      - name: Set up toolchain
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: nightly
          components: rust-src

      - name: Set up hwloc
        uses: ./.github/actions/setup-hwloc-dependencies
        with:
          hwloc-version: ${{ env.HWLOC_VERSION }}
          hwloc-version-short: ${{ env.HWLOC_VERSION_SHORT }}

      - name: Collect system information
        uses: ./.github/actions/system-information

      - name: Install cargo-careful
        uses: baptiste0928/cargo-install@v3
        with:
          crate: cargo-careful

      - name: Run unit and doc tests under cargo careful, with ASAN (Unices)
        run: |
          # By default, cargo-careful disables LeakChecker, but I actually like it
          export ASAN_OPTIONS=''
          cargo careful test -Zcareful-sanitizer=address ${{ env.JOB_FLAGS }}
        if: runner.os != 'Windows'

      - name: Run unit and doc tests under cargo careful, w/o ASAN (Windows)
        run: cargo careful test ${{ env.JOB_FLAGS }}
        if: runner.os == 'Windows'


  # Test current code coverage
  #
  # It is okay to measure coverage for the latest hwloc release only: it is the
  # one with the most features to test, as no hwloc release has removed
  # significant features so far. However, we must test both linux and windows as
  # they each have os-specific code.
  test-coverage:
    # Don't run CI twice when a PR is created from a branch internal to the repo
    # Don't run in scheduled jobs, coverage doesn't change on its own
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository

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

    strategy:
      matrix:
        os:
          - ubuntu-latest
          - windows-latest

    steps:
      - name: Checkout sources
        uses: actions/checkout@v4

      - name: Set up toolchain
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: stable

      - name: Set up hwloc
        uses: ./.github/actions/setup-hwloc-dependencies
        with:
          hwloc-version: ${{ env.HWLOC_VERSION }}
          hwloc-version-short: ${{ env.HWLOC_VERSION_SHORT }}

      - name: Collect system information
        uses: ./.github/actions/system-information

      - name: Install cargo-tarpaulin
        uses: baptiste0928/cargo-install@v3
        with:
          crate: cargo-tarpaulin

      - name: Measure code coverage
        run: cargo tarpaulin --verbose --timeout 120 --out xml

      - name: Upload to codecov.io
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          env_vars: OS
          flags: ${{ matrix.os }}
          fail_ci_if_error: true
          verbose: true


  # Check compatibility with newer Rust/deps versions (scheduled CI)
  #
  # We aren't concerned about trashing the cargo cache here since these jobs
  # only run occasionally, so the extra convenience and maintainability of
  # grouping debug and release tests trumps other considerations.
  #
  # FIXME: There should be a way to use conditional build matrices without
  #        duplicating the whole job recipe...
  #
  test-scheduled:
    if: github.event_name == 'schedule'

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

    needs: matrix_vars

    strategy:
      matrix:
        os:
          - ubuntu-latest
          - macos-latest
          - windows-latest
        rust:
          - beta
          - nightly
          - ${{ needs.matrix_vars.outputs.MINIMAL_RUST }}
        features:
          - '""'
          - 'hwloc-2_0_4'
          - 'hwloc-2_1_0'
          - 'hwloc-2_2_0'
          - 'hwloc-2_3_0'
          - 'hwloc-2_4_0'
          - 'hwloc-2_5_0'
          - 'hwloc-2_8_0'
          - 'hwloc-2_10_0'
          - 'hwloc-latest,vendored'
          - 'hwloc-latest,proptest'

    env:
      FEATURES_FLAG: '--features=${{ matrix.features }}'

    steps:
      - name: Checkout sources
        uses: actions/checkout@v4

      - name: Set up toolchain
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: ${{ matrix.rust }}

      - name: Set up hwloc
        uses: ./.github/actions/setup-hwloc-dependencies
        with:
          hwloc-version: ${{ env.HWLOC_VERSION }}
          hwloc-version-short: ${{ env.HWLOC_VERSION_SHORT }}
        if: contains(matrix.features, 'vendored') == false

      - name: Set up hwloc build dependencies (macOS)
        run: brew install automake libtool
        if: contains(matrix.features, 'vendored') && startsWith(matrix.os, 'macos')

      - name: Collect system information
        uses: ./.github/actions/system-information
        if: contains(matrix.features, 'vendored') == false

      - name: Install cargo-examples
        uses: baptiste0928/cargo-install@v3
        with:
          crate: cargo-examples

      - name: Run basic tests (debug build)
        run: cargo test --workspace ${{ env.FEATURES_FLAG }}

      - name: Run all examples (debug build)
        run: cargo examples ${{ env.FEATURES_FLAG }}

      - name: Run all examples (release build)
        run: cargo examples ${{ env.FEATURES_FLAG }} -- --release

      - name: Run basic tests (release build)
        run: cargo test --workspace --release ${{ env.FEATURES_FLAG }}