rtic/.github/workflows/build.yml

name: Build
on:
  merge_group:
  pull_request:
  push:
    branches:
      - master

env:
  CARGO_TERM_COLOR: always
  DEV_VERSION: 2
  STABLE_VERSION: 2
  OLDSTABLE_VERSION: 1
  OLDOLDSTABLE_VERSION: 0.5
  OLDOLDOLDSTABLE_VERSION: 0.4
  QEMU_VERSION: 8.2.0
  QEMU_URL: https://download.qemu.org/qemu-8.2.0.tar.xz

jobs:
  # Run cargo xtask format-check
  formatcheck:
    name: cargo fmt
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Cache Dependencies
        uses: Swatinem/rust-cache@v2

      - name: cargo xtask fmt
        run:  cargo xtask --verbose fmt -c

  # Compilation check (lm3s6965)
  checklm3s6965:
    name: check (lm3s6965)
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        backend:
          - thumbv7
          - thumbv6
          - thumbv8-base
          - thumbv8-main
        toolchain:
          - stable
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Rust ${{ matrix.toolchain }}
        run: |
          rustup override set ${{ matrix.toolchain }}          

      - name: Configure Rust target (v6, v7, v8.b v8.m)
        run: |
          rustup target add thumbv7m-none-eabi
          rustup target add thumbv6m-none-eabi
          rustup target add thumbv8m.base-none-eabi
          rustup target add thumbv8m.main-none-eabi          

      - name: Cache Dependencies
        uses: Swatinem/rust-cache@v2

      - run: cargo xtask --deny-warnings --platform lm3s6965 --backend ${{ matrix.backend }} check

  # Compilation check (hifive1) TODO
  # checkhifive1:

  # Clippy (lm3s6965)
  clippylm3s6965:
    name: clippy (lm3s6965)
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        backend:
          - thumbv7
          - thumbv6
          - thumbv8-base
          - thumbv8-main
        toolchain:
          - stable
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Rust ${{ matrix.toolchain }}
        run: |
          rustup override set ${{ matrix.toolchain }}          

      - name: Configure Rust target (v6, v7, v8.b v8.m)
        run: |
          rustup target add thumbv7m-none-eabi
          rustup target add thumbv6m-none-eabi
          rustup target add thumbv8m.base-none-eabi
          rustup target add thumbv8m.main-none-eabi          

      - name: Add Rust component clippy
        run: rustup component add clippy

      - name: Cache Dependencies
        uses: Swatinem/rust-cache@v2

      - run: cargo xtask --deny-warnings --platform lm3s6965 --backend ${{ matrix.backend }} clippy

  # Clippy (hifive1) TODO
  # clippyhifive1:

  # Platform lm3s6965: verify all examples, checks
  checkexampleslm3s6965:
    name: check examples (lm3s6965)
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        backend:
          - thumbv7
          - thumbv6
          - thumbv8-base
          - thumbv8-main
        toolchain:
          - stable
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Rust ${{ matrix.toolchain }}
        run: |
          rustup override set ${{ matrix.toolchain }}          

      - name: Configure Rust target (v6, v7, v8.b v8.m)
        run: |
          rustup target add thumbv7m-none-eabi
          rustup target add thumbv6m-none-eabi
          rustup target add thumbv8m.base-none-eabi
          rustup target add thumbv8m.main-none-eabi          

      - name: Cache Dependencies
        uses: Swatinem/rust-cache@v2

      - name: Check the examples
        if: ${{ matrix.backend == 'thumbv8-base' }}
        run: cargo xtask --platform lm3s6965 --backend ${{ matrix.backend }} --exampleexclude pool example-check

      - name: Check the examples
        if: ${{ matrix.backend != 'thumbv8-base' }}
        run: cargo xtask --platform lm3s6965 --backend ${{ matrix.backend }} example-check
  
  # Platform hifive1: verify all examples, checks
  checkexampleshifive1:
    name: check examples (hifive1)
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        backend:
          - riscv32-imc-clint
          - riscv32-imac-clint
        toolchain:
          - stable
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Rust ${{ matrix.toolchain }}
        run: |
          rustup override set ${{ matrix.toolchain }}          

      - name: Configure Rust target
        run: |
          rustup target add riscv32imac-unknown-none-elf
          rustup target add riscv32imc-unknown-none-elf          

      - name: Cache Dependencies
        uses: Swatinem/rust-cache@v2
      
      - name: Check the examples
        if: ${{ matrix.backend == 'riscv32-imc-clint' }}
        run: cargo xtask --platform hifive1 --backend ${{ matrix.backend }} --exampleexclude static example-check

      - name: Check the examples
        if: ${{ matrix.backend != 'riscv32-imc-clint' }}
        run: cargo xtask --platform hifive1 --backend ${{ matrix.backend }} example-check

  # Platform esp32c3: verify all examples, checks
  checkexamplesesp32c3:
    name: check examples (esp32c3)
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        backend:
          - riscv-esp32-c3
        toolchain:
          - nightly
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Rust ${{ matrix.toolchain }}
        run: |
          rustup toolchain install nightly-2023-11-14 --component rust-src --target riscv32imc-unknown-none-elf          

      - name: Configure Rust target
        run: |
          rustup target add riscv32imc-unknown-none-elf          

      - name: Cache Dependencies
        uses: Swatinem/rust-cache@v2
      
      - name: Check the examples
        run: cargo xtask --platform esp32-c3 --backend ${{ matrix.backend }} example-check


  buildqemu:
    name: Get modern QEMU, build and store
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Cache QEMU build
        id: cache-qemu
        uses: actions/cache@v4
        with:
          path: qemu-${{ env.QEMU_VERSION }}/build
          key: ${{ runner.OS }}-qemu-${{ env.QEMU_VERSION }}
          restore-keys: |
            ${{ runner.OS }}-qemu-${{ env.QEMU_VERSION }}
            ${{ runner.OS }}-qemu-            

      - name: Install QEMU to get dependencies
        run: |
          sudo apt update
          sudo apt install -y qemu-system-arm qemu-system-riscv32
          sudo apt-get install git libglib2.0-dev libfdt-dev libpixman-1-dev zlib1g-dev ninja-build          

      - if: ${{ steps.cache-qemu.outputs.cache-hit != 'true' }}
        name: Download QEMU
        run: wget "${{ env.QEMU_URL }}" 

      - if: ${{ steps.cache-qemu.outputs.cache-hit != 'true' }}
        name: Extract QEMU
        run: tar xvJf qemu-${{ env.QEMU_VERSION }}.tar.xz

      - if: ${{ steps.cache-qemu.outputs.cache-hit != 'true' }}
        name: Configure QEMU
        run: |
          cd qemu-${{ env.QEMU_VERSION }}
          ./configure --target-list=arm-softmmu,riscv32-softmmu          

      - if: ${{ steps.cache-qemu.outputs.cache-hit != 'true' }}
        name: Build QEMU
        run: |
          cd qemu-${{ env.QEMU_VERSION }}
          make -j$(nproc)
                    
      - name: Archive QEMU build
        run: |
          cd qemu-${{ env.QEMU_VERSION }}/build
          tar -cf $GITHUB_WORKSPACE/qemu.tar *          

      - name: Store QEMU build
        uses: actions/upload-artifact@v4
        with:
          name: qemu
          path: qemu.tar

  # Platform lm3s6965: verify the example output with run-pass tests
  testexampleslm3s6965:
    name: QEMU run (lm3s6965)
    needs: buildqemu
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        backend:
          - thumbv7
          - thumbv6
        toolchain:
          - stable
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Rust ${{ matrix.toolchain }}
        run: |
          rustup set profile minimal
          rustup override set ${{ matrix.toolchain }}          

      - name: Configure Rust target (v6, v7)
        run: |
          rustup target add thumbv7m-none-eabi
          rustup target add thumbv6m-none-eabi          

      - name: Add Rust component llvm-tools-preview
        run: rustup component add llvm-tools-preview

      # Use precompiled binutils
      - name: Install cargo-binutils
        uses: taiki-e/install-action@v2
        with:
          tool: cargo-binutils

      - name: Cache Dependencies
        uses: Swatinem/rust-cache@v2

      - name: Install QEMU to get dependencies
        run: |
          sudo apt update
          sudo apt install -y qemu-system-arm          

      - name: Download built QEMU
        uses: actions/download-artifact@v4
        with:
          name: qemu

      - name: Extract QEMU into local path
        run: tar -xf qemu.tar -C /usr/local/bin

      - name: Check which QEMU is used
        run: |
          which qemu-system-arm
          which qemu-system-riscv32          

      - name: Run-pass tests
        run: cargo xtask --deny-warnings --platform lm3s6965 --backend ${{ matrix.backend }} qemu
  
  # Platform hifive1: verify the example output with run-pass tests
  testexampleshifive1:
    name: QEMU run (hifive1)
    needs: buildqemu
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        backend:
          - riscv32-imc-clint
          - riscv32-imac-clint
        toolchain:
          - stable
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Rust ${{ matrix.toolchain }}
        run: |
          rustup set profile minimal
          rustup override set ${{ matrix.toolchain }}          

      - name: Configure Rust target
        run: |
          rustup target add riscv32imac-unknown-none-elf
          rustup target add riscv32imc-unknown-none-elf          

      - name: Add Rust component llvm-tools-preview
        run: rustup component add llvm-tools-preview

      # Use precompiled binutils
      - name: Install cargo-binutils
        uses: taiki-e/install-action@v2
        with:
          tool: cargo-binutils

      - name: Cache Dependencies
        uses: Swatinem/rust-cache@v2
      
      - name: Install QEMU to get dependencies
        run: |
          sudo apt update
          sudo apt install -y qemu-system-riscv32          

      - name: Download built QEMU
        uses: actions/download-artifact@v4
        with:
          name: qemu
      
      - name: Extract QEMU into local path
        run: tar -xf qemu.tar -C /usr/local/bin

      - name: Check which QEMU is used
        run: |
          which qemu-system-arm
          which qemu-system-riscv32          
      
      - name: Run-pass tests
        if: ${{ matrix.backend == 'riscv32-imc-clint' }}
        run: cargo xtask --deny-warnings --platform hifive1 --backend ${{ matrix.backend }} --exampleexclude static qemu

      - name: Run-pass tests
        if: ${{ matrix.backend != 'riscv32-imc-clint' }}
        run: cargo xtask --deny-warnings --platform hifive1 --backend ${{ matrix.backend }} qemu

  # Run test suite
  tests:
    name: tests
    runs-on: ubuntu-22.04
    strategy:
      fail-fast: false
      matrix:
        backend:
          - thumbv7
          - thumbv6
          - thumbv8-base
          - thumbv8-main
        package:
          - rtic
          - rtic-common
          - rtic-macros
          - rtic-monotonics
          - rtic-sync
          - rtic-time

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

      - name: Cache Dependencies
        uses: Swatinem/rust-cache@v2

      - name: Configure Rust target (v6, v7, v8.b v8.m)
        run: |
          rustup target add thumbv7m-none-eabi
          rustup target add thumbv6m-none-eabi
          rustup target add thumbv8m.base-none-eabi
          rustup target add thumbv8m.main-none-eabi          

      - name: Run cargo test
        run: cargo xtask --deny-warnings --backend ${{ matrix.backend }} test ${{ matrix.package }}

  # Build documentation, check links
  docs:
    name: build docs
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install lychee
        uses: taiki-e/install-action@v2
        with:
          tool: lychee

      - name: Build docs
        run: cargo xtask doc

      - name: Check links
        run: |
          td=$(mktemp -d)
          cp -r target/doc $td/api
          echo rtic
          lychee --offline --format detailed $td/api/rtic/

          echo rtic_common
          lychee --offline --format detailed $td/api/rtic_common/

          echo rtic_macros
          lychee --offline --format detailed $td/api/rtic_macros/

          echo rtic_monotonics
          lychee --offline --format detailed $td/api/rtic_monotonics/

          echo rtic_sync
          lychee --offline --format detailed $td/api/rtic_sync/

          echo rtic_time
          lychee --offline --format detailed $td/api/rtic_time/          


      - name: Archive the API docs
        run: |
          cp -r target/doc apidocs
          tar -cf apidocs.tar apidocs          

      - name: Store the API docs
        uses: actions/upload-artifact@v4
        with:
          name: apidocs
          path: apidocs.tar

  # Build the books
  mdbook:
    name: build mdbook
    needs: docs
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install lychee
        uses: taiki-e/install-action@v2
        with:
          tool: lychee

      - name: Install mdbook
        uses: taiki-e/install-action@v2
        with:
          tool: mdbook

      - name: Install mdbook-mermaid
        uses: taiki-e/install-action@v2
        with:
          tool: mdbook-mermaid

      - name: Build book in English
        run: cargo xtask book

      - name: Download built API docs
        uses: actions/download-artifact@v4
        with:
          name: apidocs

      - name: Extract the API docs
        run: tar -xf apidocs.tar

      - name: Check links
        run: |
          td=$(mktemp -d)
          mkdir $td/book
          cp -r book/en/book $td/book/en
          cp LICENSE-* $td/book/en
          cp -r apidocs/ $td/api

          lychee --offline --format detailed $td/book/en/
          mv $td bookroot          

      - name: Archive the book + API docs
        run: |
          tar -cf book.tar bookroot          

      - name: Store the Book + API docs
        uses: actions/upload-artifact@v4
        with:
          name: book
          path: book.tar

  mdbookold:
    name: build docs and mdbook for older releases
    needs: pushtostablebranch
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install mdbook
        uses: taiki-e/install-action@v2
        with:
          tool: mdbook

      - name: Install mdbook-mermaid
        uses: taiki-e/install-action@v2
        with:
          tool: mdbook-mermaid

      - name: Remove cargo-config
        run: rm -f .cargo/config

      - name: Prepare output folder
        run: mkdir -p mdbookold

      - name: Fetch and build books for older versions
        run: |
          # The latest stable must be the first element in the array
          vers=( "${{ env.STABLE_VERSION }}" "${{ env.OLDSTABLE_VERSION }}" )
          langs=( en )
          root=$(pwd)
          webroot=$(pwd)/mdbookold

          for ver in ${vers[@]}; do

              mkdir -p src/$ver
              src=$root/src/$ver
              curl -L https://github.com/rtic-rs/rtic/archive/release/v${ver}.tar.gz | tar xz --strip-components 1 -C $src

              pushd $src
              rm -f .cargo/config
              # Version 1 and below uses cargo doc directly
              if [[ $ver -gt 1 ]]
                 then
                   # Version 2 and above
                   cargo xtask doc
                 else
                   cargo doc || cargo doc --features timer-queue
              fi
              mkdir -p $webroot/$ver/book
              cp -r target/doc $webroot/$ver/api

              sed 's|URL|rtic/index.html|g' $root/redirect.html > $webroot/$ver/api/index.html
              popd

              for lang in ${langs[@]}; do
                  cargo xtask book build $src/book/$lang

                  cp -r $src/book/$lang/book $webroot/$ver/book/$lang
                  cp LICENSE-* $webroot/$ver/book/$lang/
              done
              # using master branch redirect file
              sed 's|URL|book/en|g' $root/redirect.html > $webroot/$ver/index.html

              rm -rf $src
          done          

      - name: Archive the old books
        run: |
          tar -cf mdbookold.tar mdbookold          

      - name: Store the old API docs
        uses: actions/upload-artifact@v4
        with:
          name: mdbookold
          path: mdbookold.tar

  parseversion:
    name: Parse the master branch RTIC version
    runs-on: ubuntu-22.04
    outputs:
      branch: ${{ steps.parseversion.outputs.branch }}
      versionmajor: ${{ steps.parseversion.outputs.versionmajor }}
      version: ${{ steps.parseversion.outputs.version }}
    steps:
      - uses: actions/checkout@v4

      - name: Get crate version and print output branch release/vX
        id: parseversion
        # Parse metadata for version number, extract the Semver Major
        run: |
          VERSION=$(cargo metadata --format-version 1 --no-deps --offline | jq -r '.packages[] | select(.name =="rtic") | .version')
          VERSIONMAJOR=${VERSION%.*.*}
          echo "branch=release/v$VERSIONMAJOR" >> "$GITHUB_OUTPUT"
          echo "versionmajor=$VERSIONMAJOR" >> "$GITHUB_OUTPUT"
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"          



  # Update stable branch
  #
  # This is only valid when current stable resides in
  # master branch.
  # As master moves on to development, the work on the
  # stable version will happen in release/v"stable_version".
  # Thus, no need to push changes
  #
  # This needs to run before book is built, as bookbuilding fetches from the branch
  pushtostablebranch:
    name: Also push branch into release/vX when pushing to master
    runs-on: ubuntu-22.04
    needs:
      - ci-success
      - parseversion
    env:
      branch: ${{ needs.parseversion.outputs.branch }}
      versionmajor: ${{ needs.parseversion.outputs.versionmajor }}
      version: ${{ needs.parseversion.outputs.version }}

    # Only run this when pushing to master branch
    if: github.ref == 'refs/heads/master'
    steps:
      - uses: actions/checkout@v4

      - name: Push to stable release branch if master contains stable version
        if: ${{ env.versionmajor == env.STABLE_VERSION }}
        run: |
          # Get the full history of the branch leading up to current commit
          git fetch --unshallow
          # Make git aware of the release branch
          git fetch -u origin ${{ env.branch }}
          # Push the full history into the release branch
          git push -u origin master:${{ env.branch }}          

      - name: Else case, master did not contain the stable version
        if: ${{ env.versionmajor != env.STABLE_VERSION }}
        run: echo "Master branch contains a development release, no git push performed"

  # Only runs when pushing to master branch
  # If all tests pass, then deploy stage is run
  deploy:
    name: deploy
    runs-on: ubuntu-22.04
    needs:
      - pushtostablebranch
      - docs
      - mdbookold
      - mdbook

    # Only run this when pushing to master branch
    if: github.ref == 'refs/heads/master'
    steps:
      - uses: actions/checkout@v4

      - name: Install lychee
        uses: taiki-e/install-action@v2
        with:
         tool: lychee

      - name: Install mdbook-mermaid
        uses: taiki-e/install-action@v2
        with:
          tool: mdbook-mermaid

      - name: mdBook Action
        uses: peaceiris/actions-mdbook@v1
        with:
          mdbook-version: 'latest'

      - name: Remove cargo-config
        run: rm -f .cargo/config

      - name: Download built dev-ver book and API docs
        uses: actions/download-artifact@v4
        with:
          name: book

      - name: Extract the dev-version book and API docs
        run: |
          tar -xf book.tar          

      - name: Download built old versions of books and API docs
        uses: actions/download-artifact@v4
        with:
          name: mdbookold

      - name: Extract the old version books and API docs
        run: |
          tar -xf mdbookold.tar          

      - name: Prepare books
        shell: 'script --return --quiet --command "bash {0}"'
        run: |
          langs=( en )
          devver=( dev )
          # The latest stable must be the first element in the array
          vers=( "${{ env.STABLE_VERSION }}" "${{ env.OLDSTABLE_VERSION }}" )

          # All releases start with "v"
          # followed by MAJOR.MINOR.PATCH, see semver.org
          # Store first in array as stable
          stable=${vers}
          crateversion=${{ env.versionmajor }}

          echo "Latest stable version: $stable"
          echo "Current crate version: $crateversion"

          # Create directories
          td=$(mktemp -d)
          mkdir -p $td/$devver/
          cp -r bookroot/* $td/$devver/

          # Redirect rtic.rs/meeting/index.html to hackmd
          mkdir $td/meeting
          sed "s|URL|https://hackmd.io/c_mFUZL-Q2C6614MlrrxOg|g" redirect.html > $td/meeting/index.html
          sed -i "s|Page Redirection|RTIC Meeting|" $td/meeting/index.html
          sed -i "s|If you|Redirecting to RTIC HackMD. If you|" $td/meeting/index.html

          # Redirect the main site to the stable release
          sed "s|URL|$stable|g" redirect.html > $td/index.html

          # Create the redirects for dev-version
          # If the current stable and the version being built differ,
          # then there is a dev-version and the links should point to it.
          if [[ "$stable" != "$crateversion" ]];
          then
            sed 's|URL|rtic/index.html|g' redirect.html > $td/$devver/api/index.html
            sed 's|URL|book/en|g' redirect.html > $td/$devver/index.html
          else
            # If the current stable and the "dev" version in master branch
            # share the same major version, redirect dev/ to stable book
            # This makes sense, preferable to have doc/book updates going live directly to rtic.rs
            sed 's|URL|rtic.rs/$stable/api/rtic|g' redirect.html > $td/$devver/api/index.html
            sed 's|URL|rtic.rs/$stable|g' redirect.html > $td/$devver/index.html
          fi

          # Package older versions, including stable

          # Copy the stable book to the stable alias
          cp -r mdbookold/${{ env.STABLE_VERSION }} $td/stable

          # Copy the stable book to the webroot
          cp -r mdbookold/${{ env.STABLE_VERSION }} $td/
          # Copy the old stable book to the webroot
          cp -r mdbookold/${{ env.OLDSTABLE_VERSION }} $td/

          # Forward CNAME file
          cp CNAME $td/
          mv $td/ bookstodeploy          

      - name: Archive the webroot
        run: |
          tar -cf bookstodeploy.tar bookstodeploy          

      - name: Store the books
        uses: actions/upload-artifact@v4
        with:
          name: bookstodeploy
          path: bookstodeploy.tar

  ghapages:
    name: Publish rtic.rs
    runs-on: ubuntu-22.04
    needs:
      - deploy
    steps:
      - name: Download books
        uses: actions/download-artifact@v4
        with:
          name: bookstodeploy

      - name: Extract the books
        run: |
          tar -xf bookstodeploy.tar          

      - name: Deploy to GH-pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./bookstodeploy
          force_orphan: true

  # ALL THE PREVIOUS JOBS NEEDS TO BE ADDED TO THE `needs` SECTION OF THIS JOB!
  ci-success:
    name: ci
    if: github.event_name == 'push' && success()
    needs:
      - formatcheck
      - checklm3s6965
      # checkhifive1 TODO
      - clippylm3s6965
      # clippyhifive1 TODO
      - checkexampleslm3s6965
      - checkexampleshifive1
      - checkexamplesesp32c3
      - testexampleslm3s6965
      - testexampleshifive1
      - tests
      - docs
      - mdbook
    runs-on: ubuntu-22.04
    steps:
      - name: Mark the job as a success
        run: exit 0