toast.yml

image: ubuntu:24.04
default: build
user: user
command_prefix: |
  # Make not silently ignore errors.
  set -euo pipefail

  # Load the Rust startup file, if it exists.
  if [ -f "$HOME/.cargo/env" ]; then
    . "$HOME/.cargo/env"
  fi

  # Use this wrapper for `cargo` if network access is needed.
  cargo-online () { cargo --locked "$@"; }

  # Use this wrapper for `cargo` unless network access is needed.
  cargo-offline () { cargo --frozen --offline "$@"; }

  # Use this wrapper for formatting code or checking that code is formatted. We use a nightly Rust
  # version for the `trailing_comma` formatting option [tag:rust_fmt_nightly_2024-11-28]. The
  # nightly version was chosen as the latest available release with all components present
  # according to this page:
  #   https://rust-lang.github.io/rustup-components-history/x86_64-unknown-linux-gnu.html
  cargo-fmt () { cargo +nightly-2024-11-28 --frozen --offline fmt --all -- "$@"; }

  # Make Bash log commands.
  set -x
tasks:
  install_packages:
    description: Install system packages.
    user: root
    command: |
      # Install the following packages:
      #
      # - build-essential       - Used to link some crates
      # - ca-certificates       - Used for fetching Docker's GPG key
      # - curl                  - Used for installing Docker, Tagref, and Rust
      # - gcc-aarch64-linux-gnu - Used for linking the binary for AArch64
      # - gcc-x86-64-linux-gnu  - Used for linking the binary for x86-64
      # - gnupg                 - Used to install Docker's GPG key
      # - lsb-release           - Used below to determine the Ubuntu release codename
      # - ripgrep               - Used for various linting tasks
      # - shellcheck            - Used for linting shell scripts
      apt-get update
      apt-get install --yes \
        build-essential \
        ca-certificates \
        curl \
        gcc-aarch64-linux-gnu \
        gcc-x86-64-linux-gnu \
        gnupg \
        lsb-release \
        ripgrep \
        shellcheck

      # Download Docker's official GPG key.
      install -m 0755 -d /etc/apt/keyrings
      curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
        gpg --dearmor -o /etc/apt/keyrings/docker.gpg
      chmod a+r /etc/apt/keyrings/docker.gpg

      # Set up the Docker repository.
      echo \
        "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] \
          https://download.docker.com/linux/ubuntu \
          "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
        tee /etc/apt/sources.list.d/docker.list > /dev/null

      # Install the Docker CLI.
      apt-get update
      apt-get install --yes docker-ce-cli

  install_tagref:
    description: Install Tagref, a reference checking tool.
    dependencies:
      - install_packages
    user: root
    command: |
      # Install Tagref using the official installer script.
      curl https://raw.githubusercontent.com/stepchowfun/tagref/main/install.sh -LSfs | sh

  create_user:
    description: Create a user who doesn't have root privileges.
    user: root
    command: |
      # Create a user named `user` with a home directory and with Bash as the login shell.
      useradd user --create-home --shell /bin/bash

  install_rust:
    description: Install Rust, a systems programming language.
    dependencies:
      - install_packages
      - create_user
    command: |
      # Install stable Rust [tag:rust_1.83.0].
      curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- \
        -y \
        --default-toolchain 1.83.0 \
        --profile minimal \
        --component clippy

      # Add Rust tools to `$PATH`.
      . "$HOME/.cargo/env"

      # Install nightly Rust [ref:rust_fmt_nightly_2024-11-28].
      rustup toolchain install nightly-2024-11-28 --profile minimal --component rustfmt

  install_tools:
    description: Install the tools needed to build and validate the program.
    dependencies:
      - install_rust
      - install_tagref

  fetch_crates:
    description: Download and build Rust packages used by the program.
    dependencies:
      - install_tools
    input_paths:
      - Cargo.lock
      - Cargo.toml
    command: |
      # Create a "hello world" project with the dependencies we want to fetch.
      mv Cargo.lock Cargo.lock.og
      mv Cargo.toml Cargo.toml.og
      cargo-offline init --vcs none
      mv Cargo.lock.og Cargo.lock
      mv Cargo.toml.og Cargo.toml

      # Ask Cargo to build the project in order to fetch the dependencies.
      cargo-online build
      cargo-online build --release
      cargo-online clippy --all-features --all-targets --workspace

      # Delete the build artifacts.
      cargo-offline clean --package toast
      cargo-offline clean --release --package toast

      # Delete the "hello world" code.
      rm -rf src

  build:
    description: Build the binary in non-release mode.
    dependencies:
      - fetch_crates
    input_paths:
      - src
    command: |
      # Build the project with Cargo.
      cargo-offline build

  test:
    description: Run the test suite.
    dependencies:
      - build
    command: |
      # Run the tests with Cargo. The `NO_COLOR` variable is used to disable colored output for
      # tests that make assertions regarding the output [tag:colorless_tests].
      NO_COLOR=true cargo-offline test

  lint:
    description: Run the linters.
    dependencies:
      - build
    input_paths:
      - .
    excluded_input_paths:
      - .git

      # [tag:excluded_input_paths] Keep this in sync with [file:.gitignore].
      - artifacts
      - target
    command: |
      # Check references with Tagref.
      tagref

      # Lint shell files with ShellCheck.
      find . -type f -name '*.sh' | xargs shellcheck

      # Lint the code with Clippy.
      cargo-offline clippy --all-features --all-targets --workspace

      # Check code formatting with Rustfmt. See [ref:format_macros] for an explanation of the `rg`
      # commands.
      rg --type rust --files-with-matches '' src | xargs sed -i 's/!(/_(/g'
      rg --type rust --files-with-matches '' src | xargs sed -i 's/^\([^ (]*\)_(/\1!(/g'
      if ! cargo-fmt --check; then
        echo 'ERROR: Please correct the formatting errors above.' 1>&2
        exit 1
      fi
      rg --type rust --files-with-matches '' src | xargs sed -i 's/_(/!(/g'

      # Forbid unconsolidated `use` declarations.
      if rg --line-number --type rust --multiline '}[[:space]]*;[[:space:]]*\n[[:space:]]*use' src
      then
        echo 'Please consolidate these `use` declarations.' >&2
        exit 1
      fi

      # Enforce that lines span no more than 100 columns.
      if rg --line-number --type rust '.{101}' src; then
        echo 'There are lines spanning more than 100 columns.' >&2
        exit 1
      fi

  run:
    description: Run the program.
    dependencies:
      - build
    command: |
      # Run the program with Cargo.
      cargo-offline run -- --help

  format:
    description: Format the source code.
    dependencies:
      - fetch_crates
    input_paths:
      - src
    output_paths:
      - src
    command: |
      # Format the code with Rustfmt. We temporarily convert macro invocations into function calls
      # so Rustfmt's `trailing_comma` feature applies to macro arguments [tag:format_macros].
      rg --type rust --files-with-matches '' src | xargs sed -i 's/!(/_(/g'
      rg --type rust --files-with-matches '' src | xargs sed -i 's/^\([^ (]*\)_(/\1!(/g'
      cargo-fmt
      rg --type rust --files-with-matches '' src | xargs sed -i 's/_(/!(/g'

  release:
    description: Build and output the release binaries for Linux.
    dependencies:
      - fetch_crates
    input_paths:
      - src
    output_paths:
      - artifacts
    command: |
      # Add the targets.
      rustup target add x86_64-unknown-linux-gnu
      rustup target add x86_64-unknown-linux-musl
      rustup target add aarch64-unknown-linux-gnu
      rustup target add aarch64-unknown-linux-musl

      # Set the linkers.
      export CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER=x86_64-linux-gnu-gcc
      export CARGO_TARGET_X86_64_UNKNOWN_LINUX_MUSL_LINKER=x86_64-linux-gnu-gcc
      export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc
      export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER=aarch64-linux-gnu-gcc

      # Build the project with Cargo for each Linux target.
      cargo-online build --release --target x86_64-unknown-linux-gnu
      cargo-online build --release --target x86_64-unknown-linux-musl
      cargo-online build --release --target aarch64-unknown-linux-gnu
      cargo-online build --release --target aarch64-unknown-linux-musl

      # Move the binaries to a more conveniennt location for exporting.
      mkdir artifacts
      cp \
        target/x86_64-unknown-linux-gnu/release/toast \
        artifacts/toast-x86_64-unknown-linux-gnu
      cp \
        target/x86_64-unknown-linux-musl/release/toast \
        artifacts/toast-x86_64-unknown-linux-musl
      cp \
        target/aarch64-unknown-linux-gnu/release/toast \
        artifacts/toast-aarch64-unknown-linux-gnu
      cp \
        target/aarch64-unknown-linux-musl/release/toast \
        artifacts/toast-aarch64-unknown-linux-musl

  validate_release:
    description: Validate the release.
    dependencies:
      - release
    input_paths:
      - integration-tests
    cache: false
    mount_paths:
      - /var/run/docker.sock
    user: root
    command: |
      # Tell the integration tests where the Toast binary lives.
      export TOAST="$(pwd)/artifacts/toast-x86_64-unknown-linux-gnu"

      # Run the integration tests.
      while IFS= read -d '' -r TEST; do
        # Log which integration test we're about to run.
        echo "Running integration test: $TEST"

        # Go into the test directory and run the test.
        (
          cd "$(dirname "$TEST")" > /dev/null
          ./run.sh
        )
      done < <(find integration-tests -name run.sh -print0)

  publish:
    description: Publish the crate to crates.io.
    dependencies:
      - fetch_crates
    environment:
      CRATES_IO_TOKEN: null
    input_paths:
      - README.md
      - src
    command: |
      # Fetch the program version.
      VERSION="$(cargo-offline pkgid | grep --extended-regexp --only-matching '[0-9.]+$')"

      # If this version of the package already exists on crates.io, there's nothing more to do.
      if cargo-online search toast | grep "toast = \"$VERSION\"" > /dev/null; then
        echo "Version $VERSION of crate already exists."
        exit
      fi

      # Publish to crates.io.
      cargo-online publish --token "$CRATES_IO_TOKEN"