build.yml

# The tree is compiled on a pull request (#15). Nothing did until this landed:
# the checks here read documents, workflows, shell and the dependency graph, and
# none of them asked whether the code builds at all.
#
# The check-run name is exactly `build`, which is the string #26 will require on
# main. GitHub takes that name from the job's `name:` and falls back to the job
# id, and a ruleset matches the literal, so a rename here silently detaches the
# requirement from the thing it was requiring. Both are `build` on purpose, so
# neither can drift without the other.
#
# THE JOB HAS NO `if:` AND NO PATH FILTER, AND THAT IS THE POINT RATHER THAN AN
# OMISSION. GitHub creates a check run for a job it started and then skipped, and
# it carries the same name a job that did the work would, so the cheapest thing
# that satisfies "the name appears in the list" is a workflow that compiles
# nothing. This job runs on every pull request and on every push to main, and its
# log carries the compiler it used.
#
# The command is the one README.md gives a contributor, not a variant of it. That
# is #13's third condition, and a gate running something else is how the two come
# apart.
#
# Warnings are errors from the first commit. A warning backlog is only ever paid
# down once, and there is no backlog here yet.
#
# THE JOB COMPILES MORE THAN THE ONE COMMAND, WHICH IS #201 AND IS DELIBERATE.
# The command README.md gives a contributor is unchanged and is still run
# character for character. What follows it compiles the targets that command
# leaves out, because `--all-targets` does not select a target declared with
# `test = false` and a file in one that stops compiling would otherwise leave
# every check here green.
name: build

on:
  pull_request:
    branches: ["**"]
    types: [opened, synchronize, reopened]
  push:
    branches: [main]

# Deny at the workflow level and grant per job, so a job added later starts with
# nothing rather than with what this one needs.
permissions: {}

concurrency:
  # Namespaced on the workflow name rather than on `build` alone: a group string
  # two workflows share means the run created second cancels the other, and the
  # gate that dies that way leaves a green tick beside no verdict. This board has
  # already paid for that once, on #178.
  group: build-workflow-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build:
    name: build
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read # check out the tree that is compiled
    env:
      # Every warning is an error, for the whole job. Set here rather than on the
      # step so that a second step added later cannot quietly compile without it.
      RUSTFLAGS: -D warnings

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          # Nothing here pushes, so do not leave the token in .git/config.
          persist-credentials: false

      # Printed rather than assumed, and now compared as well as printed (#14).
      # `rust-toolchain.toml` names the version, the toolchain manager on this
      # runner reads that file itself, and no step here carries the number: a
      # version string in this file would be the second declaration the pin
      # exists to remove.
      #
      # The comparison is green here by construction, because the manager that
      # reads the pin is the one that resolves `rustc`. It is not green for a
      # contributor whose compiler came from somewhere else, and the message it
      # prints for them names the file and both numbers instead of leaving them
      # with a compile error. The same pin resolves `lint` and `format`, which
      # run the analyser and the formatter that came with this compiler.
      - name: Say which toolchain built this run, and refuse another one
        run: bash .github/toolchain/toolchain.sh check

      - name: Say which cargo built this run
        run: cargo --version

      - name: Build everything
        run: cargo build --locked --all-targets

      # THE STEP ABOVE IS NOT EVERYTHING, WHICH IS #201. `--all-targets` selects
      # the test targets carrying `test = true`, so a target the manifest declares
      # with `test = false` is not compiled by it and a file in one that stops
      # compiling leaves this check green. The script derives that set from
      # `Cargo.toml` rather than holding a copy of it, refuses a disagreement
      # between the names it read and the occurrences of the setting they came
      # from, and compiles each one without running it.
      #
      # It is a step in this job rather than a check of its own on purpose. What
      # both steps answer is the same question - does the tree compile - and a
      # second check-run name for half of that answer is one more string for #26
      # to require and one more place for a rename to detach a requirement.
      #
      # `RUSTFLAGS` is set on the job above, so this step compiles with warnings
      # as errors exactly as the one before it does. That was written into this
      # file before there was a second step, for this case.
      - name: Prove the fixtures, then build the targets that step leaves out
        run: bash .github/excluded-targets/excluded-targets.sh check