Reproduce ns-3 CI pipelines (push, MR) (#141)

.github/actions/build/action.yml

@@ -0,0 +1,44 @@
+name: "build"
+description: "Defines the central steps in building ns-3"
+
+inputs:
+  save-ccache:
+    description: "Whether to update build ccache after building"
+    default: "true"
+  store-artifacts:
+    description: "Whether to upload build artifacts after building"
+    default: "true"
+
+runs:
+  using: "composite"
+  steps:
+    # Pre-configuration steps
+    - if: env.MODE != 'optimized' && ( ! contains(env.EXTRA_OPTIONS, '--disable-precompiled-headers') )
+      name: "Restore build cache of this job"
+      uses: hendrikmuhs/[email protected]
+      with:
+        key: ${{ env.BUILD_ID }}
+        save: ${{ inputs.save-ccache }}
+    # Configuration steps
+    - name: "Configure ns-3 CMake"
+      shell: bash
+      run: >
+        CXX=$COMPILER ./ns3 configure -d $MODE -GNinja 
+        --enable-examples --enable-tests --enable-asserts --enable-werror 
+        --enable-modules "lorawan;applications" $EXTRA_OPTIONS
+    # Build steps
+    - name: "Build ns-3"
+      shell: bash
+      run: ./ns3 build
+    # Post-build steps
+    - if: inputs.store-artifacts == 'true'
+      name: "Tar files to preserve permissions"
+      shell: bash
+      run: tar -cf build.tzst --exclude build.tzst -P -C $GITHUB_WORKSPACE --use-compress-program zstdmt build/ .lock-*
+    - if: inputs.store-artifacts == 'true'
+      name: "Upload build artifacts"
+      uses: actions/[email protected]
+      with:
+        name: ${{ env.BUILD_ID }}
+        path: build.tzst
+        retention-days: 2

.github/actions/checkout-in-ns3/action.yml

@@ -0,0 +1,18 @@
+name: "checkout-in-ns3"
+description: "Checkout this repository as ns-3 module"
+
+# Requires wget!
+
+runs:
+  using: "composite"
+  steps:
+    - name: "Checkout this repository as ns-3 module"
+      uses: actions/checkout@v4
+      with:
+        path: "src/lorawan"
+    - name: "Download ns-3-dev working tree with Gitlab API"
+      run: |
+        tag=$(< src/lorawan/NS3-VERSION) && tag=${tag#release }
+        wget -nv -O ns-3-dev.tar https://gitlab.com/api/v4/projects/nsnam%2Fns-3-dev/repository/archive.tar?sha=$tag
+        tar -xf ns-3-dev.tar && cp -a ns-3-dev-$tag-*/. . && rm -R ns-3-dev.tar ns-3-dev-$tag*
+      shell: bash

.github/actions/install-analysis/action.yml

@@ -0,0 +1,21 @@
+# Note: this action requires an ubuntu container and access to the repos's actions!
+# (see analysis.yml)
+name: "install-analysis"
+description: "Installs required ubuntu packages and checks-out the repo in ns-3"
+
+runs:
+  using: "composite"
+  steps:
+    - name: "Install required system packages"
+      shell: bash
+      run: >
+        sudo apt update && DEBIAN_FRONTEND=noninteractive sudo apt install -y
+        apt-utils
+        git gcc g++ cmake python3 make ninja-build
+        tcpdump libgsl-dev libxml2-dev
+        curl unzip tar
+        ccache
+        lcov
+        wget
+    - name: "Checkout this repository as ns-3 module"
+      uses: ./.github/actions/checkout-in-ns3

.github/actions/install-doc/action.yml

@@ -0,0 +1,28 @@
+# Note: this action requires an archlinux container and access to the repos's actions!
+# (see .doc.yml)
+name: "install-doc"
+description: "Installs required archlinux packages and checks-out the repo in ns-3"
+
+runs:
+  using: "composite"
+  steps:
+    - name: "Install required system packages"
+      shell: bash
+      run: >
+        pacman-key --init && pacman -Syu --noconfirm
+        base-devel ninja cmake python ccache gsl gtk3 boost openssh
+        graphviz imagemagick texlive-basic texlive-bin texlive-binextra texlive-latexextra
+        texlive-fontutils texlive-fontsrecommended python-sphinx 
+        wget &&
+        pacman --noconfirm -U https://archive.archlinux.org/packages/d/dia/dia-0.97.3-9-x86_64.pkg.tar.zst &&
+        pacman --noconfirm -U https://archive.archlinux.org/packages/d/doxygen/doxygen-1.9.6-1-x86_64.pkg.tar.zst &&
+        mv /etc/ImageMagick-7/policy.xml /etc/ImageMagick-7/policy.xml.bak
+    - name: "Checkout this repository as ns-3 module"
+      uses: ./.github/actions/checkout-in-ns3
+    - name: "Add lorawan module to docs"
+      shell: bash
+      working-directory: doc/models
+      run: |
+        sed -i '/lr-wpan\/doc\/lr-wpan.rst/a\\t\$(SRC)\/lorawan\/doc\/lorawan.rst \\' Makefile
+        sed -i '/lr-wpan\/doc\/lr-wpan-arch.dia/i\\t\$(SRC)\/lorawan\/doc\/figures\/LoRaWANTopology.pdf \\' Makefile
+        sed -i '/lr-wpan/i\   lorawan' source/index.rst

.github/actions/install-linting/action.yml

@@ -0,0 +1,21 @@
+# Note: this action requires an ubuntu container and access to the repos's actions!
+# (see .linting.yml)
+name: "install-linting"
+description: "Installs required ubuntu packages and checks-out the repo in ns-3"
+
+runs:
+  using: "composite"
+  steps:
+    - name: "Install required system packages"
+      shell: bash
+      run: >
+        apt update && DEBIAN_FRONTEND=noninteractive apt install -y
+        clang cmake
+        clang-tidy clang-tidy-16
+        python3 python3-pip
+        libboost-all-dev libeigen3-dev libgtk-3-dev libsqlite3-dev
+        gsl-bin libgsl-dev libgsl27
+        git ssh
+        wget
+    - name: "Checkout this repository as ns-3 module"
+      uses: ./.github/actions/checkout-in-ns3

.github/actions/install-per-commit/action.yml

@@ -0,0 +1,24 @@
+# Note: this action requires an archlinux container, specific inputs and access to the repos's actions!
+# (see .base-per-commit.yml)
+name: "install-per-commit"
+description: "Installs required archlinux packages and checks-out the repo in ns-3"
+
+runs:
+  using: "composite"
+  steps:
+    - name: "Install required system packages"
+      shell: bash
+      run: >
+        pacman-key --init && pacman -Syu --noconfirm
+        base-devel gcc clang cmake ninja ccache
+        boost gsl gtk3
+        openssh
+        python
+        wget
+    - name: "Checkout this repository as ns-3 module"
+      uses: ./.github/actions/checkout-in-ns3
+    - name: "Format a string id for the build conf. of this job"
+      shell: bash
+      run: |
+        EXTRA_ID=`echo $EXTRA_OPTIONS | sed 's/--/-/g' | sed 's/ //g'`
+        echo "BUILD_ID=per-commit-$COMPILER-$MODE$EXTRA_ID" >> $GITHUB_ENV

.github/actions/test/action.yml

@@ -0,0 +1,14 @@
+name: "test"
+description: "Defines the central steps in testing ns-3"
+
+runs:
+  using: "composite"
+  steps:
+    # Test steps
+    - name: "Store ccache miss rate"
+      shell: bash
+      run: echo "CACHE_MISS=`./utils/ccache-miss-rate.py`" >> $GITHUB_ENV
+    - if: env.CACHE_MISS != '0' && env.MODE != 'debug'
+      name: "Test ns-3"
+      shell: bash
+      run: ./test.py -n

.github/workflows/.doc.yml

@@ -0,0 +1,61 @@
+# Base ns-3 CI job template for per-commit jobs involving building and testing
+
+on: workflow_call
+
+jobs:
+  doxygen:
+    runs-on: ubuntu-latest
+    container:
+      image: archlinux
+    timeout-minutes: 120
+    continue-on-error: true
+    steps:
+      # The following step is required in all jobs that use this repo's actions
+      - name: "Retrieve actions from repository"
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: .github/actions
+      - name: "Install dependencies and checkout repo in ns-3"
+        uses: ./.github/actions/install-doc
+      - name: "Build ns-3"
+        env:
+          BUILD_ID: per-commit-g++-debug
+          COMPILER: g++
+          MODE: debug
+        uses: ./.github/actions/build
+        with:
+          save-ccache: "false"
+          store-artifacts: "false"
+      - name: "Build ns-3 assemble-introspected-command-line"
+        run: ./ns3 build assemble-introspected-command-line
+      - name: "Check documentation coverage and formatting"
+        run: |
+          doc/doxygen.warnings.report.sh -i -m lorawan
+          python3 utils/check-style-clang-format.py --no-formatting --no-tabs doc/introspected-doxygen.h
+          python3 utils/check-style-clang-format.py --no-formatting --no-tabs doc/introspected-command-line.h
+          ./ns3 clean
+      - name: "Upload doxygen warnings as artifact"
+        if: always()
+        uses: actions/[email protected]
+        with:
+          name: doxygen.warnings.log
+          path: doc/doxygen.warnings.log
+
+  models:
+    runs-on: ubuntu-latest
+    container:
+      image: archlinux
+    timeout-minutes: 120
+    steps:
+      # The following step is required in all jobs that use this repo's actions
+      - name: "Retrieve actions from repository"
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: .github/actions
+      - name: "Install dependencies and checkout repo in ns-3"
+        uses: ./.github/actions/install-doc
+      - name: "Make html and latexpdf"
+        working-directory: doc/models
+        run: |
+          make html
+          make latexpdf

.github/workflows/.formatting.yml

@@ -0,0 +1,68 @@
+# ns-3 CI/CD script with the pre-build stage
+#
+# Contains jobs to check the ns-3 code formatting and spell-checking.
+
+on: workflow_call
+
+jobs:
+  # Clang-format
+  check-style-clang-format:
+    runs-on: ubuntu-latest
+    container:
+      image: ubuntu:rolling
+    strategy:
+      matrix:
+        version: [14, 15, 16]
+    timeout-minutes: 60
+    steps:
+      # The following step is required in all jobs that use this repo's actions
+      - name: "Retrieve actions from repository"
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: .github/actions
+      - name: "Install required system packages"
+        run: >
+          apt update && DEBIAN_FRONTEND=noninteractive apt install -y 
+          python3
+          clang-format-${{ matrix.version }}
+          wget
+      - name: "Checkout this repository as ns-3 module"
+        uses: ./.github/actions/checkout-in-ns3
+      - name: "Check code style"
+        run: python3 utils/check-style-clang-format.py --verbose src/lorawan
+
+  # Emacs line
+  emacs-line:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+      - run: >
+          if ( egrep -rn --include="*.h" --include="*.cc" --include="*.c" --include="*.py" --include="*.rst" "c-file-style:|py-indent-offset:" ) ; then
+          echo "Found Emacs lines on the above C/C++, Python and RST files" ;
+          exit 1 ;
+          else
+          echo "No Emacs lines found on C/C++, Python and RST files" ;
+          exit 0 ;
+          fi
+
+  # Spell checking
+  spell-check:
+    runs-on: ubuntu-latest
+    container:
+      image: python:latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install codespell
+      # Get commit messages
+      - run: >
+          if (git remote | grep -qw upstream) ; then
+          git remote remove upstream ;
+          fi
+      - run: git config --global --add safe.directory $GITHUB_WORKSPACE
+      # develop here is meant to be the "default branch"
+      - run: git remote add -t develop --no-tags -f upstream https://github.com/signetlabdei/lorawan.git
+      - run: git log --pretty=%B HEAD...upstream/develop ^upstream/develop > git_messages.txt
+      # Check source code and commit messages
+      - run: codespell -f -C0 --skip="./experiments" ./

.github/workflows/.linting.yml

@@ -0,0 +1,50 @@
+# ns-3 CI/CD script with jobs of the code-linting stage
+#
+# Contains jobs to perform lint checking.
+
+on: workflow_call
+
+jobs:
+  # Clang-tidy
+  clang-tidy-16:
+    runs-on: ubuntu-latest
+    container:
+      image: ubuntu:rolling
+    timeout-minutes: 180
+    env:
+      CLANG_TIDY_OUTPUT: clang-tidy-output.log
+    steps:
+      # The following step is required in all jobs that use this repo's actions
+      - name: "Retrieve actions from repository"
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: .github/actions
+      - name: "Install dependencies and checkout repo in ns-3"
+        uses: ./.github/actions/install-linting
+      - name: "Configure ns-3 CMake"
+        run: >
+          ./ns3 configure -d debug
+          --enable-examples --enable-tests --enable-asserts
+          --enable-modules "lorawan;applications"
+          --enable-clang-tidy
+      # Use a trick (git diff on empty tag) to only run clang-tidy on the lorawan module
+      - name: "Running clang-tidy"
+        shell: bash
+        run: >
+          git -C src/lorawan/ tag empty $(git hash-object -t tree /dev/null) &&
+          git -C src/lorawan/ diff -U0 empty 
+          --src-prefix=a/src/lorawan/ --dst-prefix=b/src/lorawan/ |
+          clang-tidy-diff-16.py -path cmake-cache/ -p1 -quiet -use-color
+          -iregex "src\/lorawan\/.+\.(cpp|cc|cxx|c|h|hpp)"
+          1> $CLANG_TIDY_OUTPUT
+          2> /dev/null
+      - name: "Check job results"
+        run: |
+          (! egrep -A 3 "error:|warning:|note:" $CLANG_TIDY_OUTPUT)
+          echo "No clang-tidy errors found"
+      - if: failure()
+        name: "Upload clang-tidy-output.log"
+        uses: actions/[email protected]
+        with:
+          name: ${{ env.CLANG_TIDY_OUTPUT }}
+          path: ${{ env.CLANG_TIDY_OUTPUT }}