ci.yml

# This workflow uses other callable workflows containing actions that are not
# certified by GitHub. They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support documentation.
#
# This workflow triggers on multiple event sources and is intended as the
# top-level CI for building artifacts during PRs and creation of release tags
# (note the tags format specified below).

name: Build and Upload Artifacts

on:
  push:
    branches:
      - "develop"
      - "main"

    # NOTE:
    # "on tags" is used to trigger the release process instead of
    # "on release" due to current release process requirements.
    tags:
      - v[0-9]+.[0-9]+.[0-9]+
      - v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+

  pull_request:
    branches:
      - "develop"
      - "main"

  # Allow manually triggering of the workflow.
  workflow_dispatch:
    inputs:
      is_release:
        description: "Run as release (for testing purposes)?"
        type: boolean
        required: true
        default: false

env:
  TMP_SOURCES_DIR: ${{ github.workspace }}/tmp/src
  RELEASE_SOURCES_DIR: ${{ github.workspace }}/release/src
  RELEASE_DOCS_DIR: ${{ github.workspace }}/release/docs
  RELEASE_PDF_DOCS_DIR: ${{ github.workspace }}/release/docs/pdf
  XCORE_BUILDER: 'ghcr.io/xmos/xcore_builder:latest'

jobs:
  event_configuration:
    name: Determine event configuration
    runs-on: ubuntu-latest
    outputs:
      is_release: ${{ steps.run_type.outputs.IS_RELEASE }}
      examples_artifact_name: ${{ steps.artifact_names.outputs.EXAMPLES_ARTIFACT_NAME }}
      xcore_iot_src_artifact_name: ${{ steps.artifact_names.outputs.XCORE_IOT_SOURCES_ARTIFACT_NAME }}
      xmath_walkthrough_src_artifact_name: ${{ steps.artifact_names.outputs.XMATH_WALKTHROUGH_SOURCES_ARTIFACT_NAME }}
      docs_artifact_name: ${{ steps.artifact_names.outputs.DOCS_ARTIFACT_NAME }}
    steps:
      - name: Determine workflow run type
        id: run_type
        run: |
          IS_RELEASE=false
          IS_TAGGED=false
          if [ "${{ startsWith(github.ref, 'refs/tags/v') }}" = "true" ]; then
            IS_RELEASE=true
            IS_TAGGED=true
          fi
          if [ "${{ inputs.is_release }}" = "true" ]; then
            IS_RELEASE=true
          fi
          echo "IS_RELEASE=$IS_RELEASE" >> $GITHUB_OUTPUT
          echo "IS_RELEASE=$IS_RELEASE" >> $GITHUB_ENV
          echo "IS_TAGGED=$IS_TAGGED" >> $GITHUB_ENV

      - name: Determine artifact names
        id: artifact_names
        run: |
          if [ "$IS_RELEASE" = "true" ]; then
            if [ "$IS_TAGGED" = "true" ]; then
              version=$(echo "${{ github.ref_name }}" | sed "s/\./_/g")
            else
              version="test"
            fi
            echo "XCORE_IOT_SOURCES_ARTIFACT_NAME=XM-014925-SM_xcore_iot_sources_$version" >> $GITHUB_OUTPUT
            echo "DOCS_ARTIFACT_NAME=XM-014926-PC_xcore_iot_docs_$version" >> $GITHUB_OUTPUT
            echo "XMATH_WALKTHROUGH_SOURCES_ARTIFACT_NAME=XM-014935-SM_xmath_walkthrough_sources_$version" >> $GITHUB_OUTPUT
          else
            echo "XCORE_IOT_SOURCES_ARTIFACT_NAME=xcore_iot_sources" >> $GITHUB_OUTPUT
            echo "XMATH_WALKTHROUGH_SOURCES_ARTIFACT_NAME=xmath_walkthrough_sources" >> $GITHUB_OUTPUT
            echo "DOCS_ARTIFACT_NAME=xcore_iot_docs" >> $GITHUB_OUTPUT
          fi

  build_apps:
    name: Build example applications
    needs: event_configuration
    uses: ./.github/workflows/apps.yml
    with:
      is_release: ${{ needs.event_configuration.outputs.is_release }}
      examples_artifact_name: ${{ needs.event_configuration.outputs.examples_artifact_name }}

  build_docs:
    name: Build documentation
    needs: event_configuration
    uses: ./.github/workflows/docs.yml
    with:
      docs_artifact_name: ${{ needs.event_configuration.outputs.docs_artifact_name }}

  # NOTE:
  # The jobs below only run on releases.

  release_docs:
    name: Release documentation
    needs: [event_configuration, build_docs]
    runs-on: ubuntu-latest
    if: needs.event_configuration.outputs.is_release == 'true'
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: recursive

      - name: Download documentation artifacts
        uses: actions/download-artifact@v4.1.7
        with:
          name: ${{ needs.event_configuration.outputs.docs_artifact_name }}
          path: ${{ env.RELEASE_DOCS_DIR }}

      - name: Rename PDFs
        run: |
          cd ${{ env.RELEASE_PDF_DOCS_DIR }}
          mv programming_guide.pdf xcore_iot_programming_guide.pdf

      - name: Build other modules' PDFs
        run: |
          bash tools/ci/build_pdfs.sh
          docker run --rm -u $(id -u):$(id -g) -w /xcore_iot -v ${{ github.workspace }}:/xcore_iot ${XCORE_BUILDER} bash -l tools/ci/fetch_xmath_walkthrough.sh
          bash tools/ci/build_xmath_walkthrough_pdf.sh
          bash tools/ci/clean_xmath_walkthrough.sh
          cp dist_pdfs/* ${{ env.RELEASE_PDF_DOCS_DIR }}

      - name: Upload documentation
        uses: actions/upload-artifact@v3
        with:
          name: ${{ needs.event_configuration.outputs.docs_artifact_name }}
          path: ${{ env.RELEASE_DOCS_DIR }}

  release_sources:
    name: Release sources
    needs: event_configuration
    runs-on: ubuntu-latest
    if: needs.event_configuration.outputs.is_release == 'true'
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 1
          submodules: recursive
          path: ${{ env.TMP_SOURCES_DIR }}

      # NOTE:
      # Sources must be pre-zipped or added to an archive such as a tarball to
      # prevent loss of file permissions such as the executable bash scripts.
      # The side-effect of this is that the uploaded artifact will be
      # double-zipped. This is a reported limitation (as of 2023-02) in:
      # https://github.com/actions/upload-artifact
      # Also some 3rd party sources contain symlinks thus the --symlinks option
      # specified below.
      - name: Prepare xcore_iot artifact
        run: |
          cd $TMP_SOURCES_DIR
          mkdir -p $RELEASE_SOURCES_DIR
          zip -r --symlinks $RELEASE_SOURCES_DIR/${{ needs.event_configuration.outputs.xcore_iot_src_artifact_name }}.zip .

      - name: Upload xcore_iot sources
        uses: actions/upload-artifact@v3
        with:
          name: ${{ needs.event_configuration.outputs.xcore_iot_src_artifact_name }}
          path: ${{ env.RELEASE_SOURCES_DIR }}

      - name: Prepare xmath_walkthrough artifact
        run: |
          cd $TMP_SOURCES_DIR
          docker run --rm -u $(id -u):$(id -g) -w /xcore_iot -v $TMP_SOURCES_DIR:/xcore_iot ${XCORE_BUILDER} bash -l tools/ci/fetch_xmath_walkthrough.sh
          bash tools/ci/build_xmath_walkthrough_zip.sh
          bash tools/ci/clean_xmath_walkthrough.sh

      - name: Upload xmath_walkthrough sources
        uses: actions/upload-artifact@v3
        with:
          name: ${{ needs.event_configuration.outputs.xmath_walkthrough_src_artifact_name }}
          path: ${{ env.RELEASE_SOURCES_DIR }}