From fc075b901c939f183d8ae1b5fbf1ca2ebcb6c431 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Sat, 1 Nov 2025 12:04:13 +1300
Subject: [PATCH 1/9] action.yml: Playing with apt cache

---
 .github/actions/setup-build-env/action.yml | 14 ++++++++++----
 .github/workflows/test-build.yml           |  8 ++++++++
 .github/workflows/test-compile.yml         |  2 ++
 .github/workflows/test-sanitizers.yml      |  2 ++
 4 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/.github/actions/setup-build-env/action.yml b/.github/actions/setup-build-env/action.yml
index e4bc8ec58..0bd7bf71b 100644
--- a/.github/actions/setup-build-env/action.yml
+++ b/.github/actions/setup-build-env/action.yml
@@ -1,14 +1,20 @@
 name: Build environment setup
 description: Configure build env for Yosys builds
+
+inputs:
+  runs-on:
+    required: true
+    type: string
+
 runs:
   using: composite
   steps:
     - name: Install Linux Dependencies
       if: runner.os == 'Linux'
-      shell: bash
-      run: |
-        sudo apt-get update
-        sudo apt-get install gperf build-essential bison flex libfl-dev libreadline-dev gawk tcl-dev libffi-dev git graphviz xdot pkg-config python3 libboost-system-dev libboost-python-dev libboost-filesystem-dev zlib1g-dev libbz2-dev libgtest-dev
+      uses: awalsh128/cache-apt-pkgs-action@v1.6.0
+      with:
+        packages: gperf build-essential bison flex libfl-dev libreadline-dev gawk tcl-dev libffi-dev git graphviz xdot pkg-config python3 libboost-system-dev libboost-python-dev libboost-filesystem-dev zlib1g-dev libbz2-dev libgtest-dev
+        version: ${{ inputs.runs-on }}-buildys
 
     - name: Install macOS Dependencies
       if: runner.os == 'macOS'
diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml
index 2d4a7a6c8..eb52da203 100644
--- a/.github/workflows/test-build.yml
+++ b/.github/workflows/test-build.yml
@@ -60,6 +60,8 @@ jobs:
 
       - name: Setup environment
         uses: ./.github/actions/setup-build-env
+        with:
+          runs-on: ${{ matrix.os }}
 
       - name: Build
         shell: bash
@@ -105,6 +107,8 @@ jobs:
 
       - name: Setup environment
         uses: ./.github/actions/setup-build-env
+        with:
+          runs-on: ${{ matrix.os }}
 
       - name: Get iverilog
         id: get-iverilog
@@ -191,6 +195,8 @@ jobs:
 
       - name: Setup environment
         uses: ./.github/actions/setup-build-env
+        with:
+          runs-on: ${{ matrix.os }}
 
       - name: Download build artifact
         uses: actions/download-artifact@v4
@@ -229,6 +235,8 @@ jobs:
 
       - name: Setup environment
         uses: ./.github/actions/setup-build-env
+        with:
+          runs-on: ${{ matrix.os }}
 
       - name: Download build artifact
         uses: actions/download-artifact@v4
diff --git a/.github/workflows/test-compile.yml b/.github/workflows/test-compile.yml
index 7c18c7ba0..5c5cdfd1d 100644
--- a/.github/workflows/test-compile.yml
+++ b/.github/workflows/test-compile.yml
@@ -60,6 +60,8 @@ jobs:
 
       - name: Setup environment
         uses: ./.github/actions/setup-build-env
+        with:
+          runs-on: ${{ matrix.os }}
 
       - name: Setup Cpp
         uses: aminya/setup-cpp@v1
diff --git a/.github/workflows/test-sanitizers.yml b/.github/workflows/test-sanitizers.yml
index 9c0f6d746..38e51f7b4 100644
--- a/.github/workflows/test-sanitizers.yml
+++ b/.github/workflows/test-sanitizers.yml
@@ -44,6 +44,8 @@ jobs:
 
       - name: Setup environment
         uses: ./.github/actions/setup-build-env
+        with:
+          runs-on: ${{ matrix.os }}
 
       - name: Get iverilog
         id: get-iverilog

From 4aa075be4639b061d7a4b712d8d8d42ac5db6eee Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Sat, 1 Nov 2025 12:43:45 +1300
Subject: [PATCH 2/9] CI: iverilog setup as composite action

Called during setup-build-env.
---
 .github/actions/setup-build-env/action.yml | 11 +++++
 .github/actions/setup-iverilog/action.yml  | 57 ++++++++++++++++++++++
 .github/workflows/test-build.yml           | 43 +---------------
 .github/workflows/test-sanitizers.yml      | 48 +-----------------
 4 files changed, 70 insertions(+), 89 deletions(-)
 create mode 100644 .github/actions/setup-iverilog/action.yml

diff --git a/.github/actions/setup-build-env/action.yml b/.github/actions/setup-build-env/action.yml
index 0bd7bf71b..6bf0afa15 100644
--- a/.github/actions/setup-build-env/action.yml
+++ b/.github/actions/setup-build-env/action.yml
@@ -5,6 +5,11 @@ inputs:
   runs-on:
     required: true
     type: string
+  get-iverilog:
+    description: 'Install iverilog'
+    default: false
+    required: false
+    type: boolean
 
 runs:
   using: composite
@@ -38,3 +43,9 @@ runs:
         echo "$(brew --prefix bison)/bin" >> $GITHUB_PATH
         echo "$(brew --prefix flex)/bin" >> $GITHUB_PATH
         echo "procs=$(sysctl -n hw.ncpu)" >> $GITHUB_ENV
+
+    - name: Setup iverilog
+      if: inputs.get-iverilog
+      uses: ./.github/actions/setup-iverilog
+      with:
+        runs-on: ${{ inputs.runs-on }}
diff --git a/.github/actions/setup-iverilog/action.yml b/.github/actions/setup-iverilog/action.yml
new file mode 100644
index 000000000..7f264a462
--- /dev/null
+++ b/.github/actions/setup-iverilog/action.yml
@@ -0,0 +1,57 @@
+name: iverilog setup
+description: Cached build and install of iverilog
+
+inputs:
+  runs-on:
+    required: true
+    type: string
+
+runs:
+  using: composite
+  steps:
+    - name: Get iverilog
+      id: get-iverilog
+      shell: bash
+      run: |
+        git clone https://github.com/steveicarus/iverilog.git
+        cd iverilog
+        echo "IVERILOG_GIT=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
+
+    - name: Get vcd2fst
+      shell: bash
+      run: |
+        git clone https://github.com/mmicko/libwave.git
+        mkdir -p ${{ github.workspace }}/.local/
+        cd libwave
+        cmake . -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/.local
+        make -j$procs
+        make install
+
+    - name: Cache iverilog
+      id: cache-iverilog
+      uses: actions/cache@v4
+      with:
+        path: .local/
+        key: ${{ inputs.runs-on }}-${{ steps.get-iverilog.outputs.IVERILOG_GIT }}
+
+    - name: iverilog macOS deps
+      if: steps.cache-iverilog.outputs.cache-hit != 'true' && runner.os == 'macOS'
+      shell: bash
+      run: |
+        brew install autoconf
+
+    - name: Build iverilog
+      if: steps.cache-iverilog.outputs.cache-hit != 'true'
+      shell: bash
+      run: |
+        mkdir -p ${{ github.workspace }}/.local/
+        cd iverilog
+        autoconf
+        CC=gcc CXX=g++ ./configure --prefix=${{ github.workspace }}/.local
+        make -j$procs
+        make install
+
+    - name: Check iverilog
+      shell: bash
+      run: |
+        iverilog -V
diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml
index eb52da203..6bd5495f0 100644
--- a/.github/workflows/test-build.yml
+++ b/.github/workflows/test-build.yml
@@ -109,48 +109,7 @@ jobs:
         uses: ./.github/actions/setup-build-env
         with:
           runs-on: ${{ matrix.os }}
-
-      - name: Get iverilog
-        id: get-iverilog
-        shell: bash
-        run: |
-          git clone https://github.com/steveicarus/iverilog.git
-          cd iverilog
-          echo "IVERILOG_GIT=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-
-      - name: Get vcd2fst
-        shell: bash
-        run: |
-          git clone https://github.com/mmicko/libwave.git
-          mkdir -p ${{ github.workspace }}/.local/
-          cd libwave
-          cmake . -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/.local
-          make -j$procs
-          make install
-
-      - name: Cache iverilog
-        id: cache-iverilog
-        uses: actions/cache@v4
-        with:
-          path: .local/
-          key: ${{ matrix.os }}-${{ steps.get-iverilog.outputs.IVERILOG_GIT }}
-
-      - name: iverilog macOS deps
-        if: steps.cache-iverilog.outputs.cache-hit != 'true' && runner.os == 'macOS'
-        shell: bash
-        run: |
-          brew install autoconf
-
-      - name: Build iverilog
-        if: steps.cache-iverilog.outputs.cache-hit != 'true'
-        shell: bash
-        run: |
-          mkdir -p ${{ github.workspace }}/.local/
-          cd iverilog
-          autoconf
-          CC=gcc CXX=g++ ./configure --prefix=${{ github.workspace }}/.local
-          make -j$procs
-          make install
+          setup-iverilog: true
 
       - name: Download build artifact
         uses: actions/download-artifact@v4
diff --git a/.github/workflows/test-sanitizers.yml b/.github/workflows/test-sanitizers.yml
index 38e51f7b4..6e3dfb2f2 100644
--- a/.github/workflows/test-sanitizers.yml
+++ b/.github/workflows/test-sanitizers.yml
@@ -46,53 +46,7 @@ jobs:
         uses: ./.github/actions/setup-build-env
         with:
           runs-on: ${{ matrix.os }}
-
-      - name: Get iverilog
-        id: get-iverilog
-        shell: bash
-        run: |
-          git clone https://github.com/steveicarus/iverilog.git
-          cd iverilog
-          echo "IVERILOG_GIT=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-
-      - name: Get vcd2fst
-        shell: bash
-        run: |
-          git clone https://github.com/mmicko/libwave.git
-          mkdir -p ${{ github.workspace }}/.local/
-          cd libwave
-          cmake . -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/.local
-          make -j$procs
-          make install
-
-      - name: Cache iverilog
-        id: cache-iverilog
-        uses: actions/cache@v4
-        with:
-          path: .local/
-          key: ${{ matrix.os }}-${{ steps.get-iverilog.outputs.IVERILOG_GIT }}
-
-      - name: iverilog macOS deps
-        if: steps.cache-iverilog.outputs.cache-hit != 'true' && runner.os == 'macOS'
-        shell: bash
-        run: |
-          brew install autoconf
-
-      - name: Build iverilog
-        if: steps.cache-iverilog.outputs.cache-hit != 'true'
-        shell: bash
-        run: |
-          mkdir -p ${{ github.workspace }}/.local/
-          cd iverilog
-          autoconf
-          CC=gcc CXX=g++ ./configure --prefix=${{ github.workspace }}/.local
-          make -j$procs
-          make install
-
-      - name: Check iverilog
-        shell: bash
-        run: |
-          iverilog -V
+          setup-iverilog: true
 
       - name: Build
         shell: bash

From dcc24edd9a3e758619df9ea74a1917ec41153b59 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Sat, 1 Nov 2025 13:03:33 +1300
Subject: [PATCH 3/9] CI: Save iverilog cache in action

We still want to cache iverilog even if the rest of the action fails, so explicitly save/restore instead of standard cache.
---
 .github/actions/setup-build-env/action.yml |  2 +-
 .github/actions/setup-iverilog/action.yml  | 16 +++++++++++-----
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/.github/actions/setup-build-env/action.yml b/.github/actions/setup-build-env/action.yml
index 6bf0afa15..6e46e1dfb 100644
--- a/.github/actions/setup-build-env/action.yml
+++ b/.github/actions/setup-build-env/action.yml
@@ -45,7 +45,7 @@ runs:
         echo "procs=$(sysctl -n hw.ncpu)" >> $GITHUB_ENV
 
     - name: Setup iverilog
-      if: inputs.get-iverilog
+      if: inputs.get-iverilog == 'true'
       uses: ./.github/actions/setup-iverilog
       with:
         runs-on: ${{ inputs.runs-on }}
diff --git a/.github/actions/setup-iverilog/action.yml b/.github/actions/setup-iverilog/action.yml
index 7f264a462..1517ad9c4 100644
--- a/.github/actions/setup-iverilog/action.yml
+++ b/.github/actions/setup-iverilog/action.yml
@@ -27,21 +27,20 @@ runs:
         make -j$procs
         make install
 
-    - name: Cache iverilog
-      id: cache-iverilog
-      uses: actions/cache@v4
+    - uses: actions/cache/restore@v4
+      id: restore-iverilog
       with:
         path: .local/
         key: ${{ inputs.runs-on }}-${{ steps.get-iverilog.outputs.IVERILOG_GIT }}
 
     - name: iverilog macOS deps
-      if: steps.cache-iverilog.outputs.cache-hit != 'true' && runner.os == 'macOS'
+      if: steps.restore-iverilog.outputs.cache-hit != 'true' && runner.os == 'macOS'
       shell: bash
       run: |
         brew install autoconf
 
     - name: Build iverilog
-      if: steps.cache-iverilog.outputs.cache-hit != 'true'
+      if: steps.restore-iverilog.outputs.cache-hit != 'true'
       shell: bash
       run: |
         mkdir -p ${{ github.workspace }}/.local/
@@ -55,3 +54,10 @@ runs:
       shell: bash
       run: |
         iverilog -V
+
+    - uses: actions/cache/save@v4
+      id: save-iverilog
+      if: steps.restore-iverilog.outputs.cache-hit != 'true'
+      with:
+        path: .local/
+        key: ${{ steps.restore-iverilog.outputs.cache-primary-key }}

From 1c4d2f7790c7d23d7cdbe08005947e17d9b90a8a Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Sat, 1 Nov 2025 14:29:58 +1300
Subject: [PATCH 4/9] CI: Split dependency setup

Split into common + build/docs/test (common always installs, build/docs/test are installed as requested with `build-*-deps` input flag).
---
 .github/actions/setup-build-env/action.yml | 40 ++++++++++++++++++++--
 .github/workflows/codeql.yml               |  7 ++--
 .github/workflows/test-build.yml           |  6 +++-
 .github/workflows/test-compile.yml         |  1 +
 .github/workflows/test-sanitizers.yml      |  4 ++-
 5 files changed, 52 insertions(+), 6 deletions(-)

diff --git a/.github/actions/setup-build-env/action.yml b/.github/actions/setup-build-env/action.yml
index 6e46e1dfb..24e7d84a5 100644
--- a/.github/actions/setup-build-env/action.yml
+++ b/.github/actions/setup-build-env/action.yml
@@ -5,6 +5,21 @@ inputs:
   runs-on:
     required: true
     type: string
+  get-build-deps:
+    description: 'Install Yosys build dependencies'
+    default: false
+    required: false
+    type: boolean
+  get-docs-deps:
+    description: 'Install Yosys docs dependencies'
+    default: false
+    required: false
+    type: boolean
+  get-test-deps:
+    description: 'Install Yosys test dependencies'
+    default: false
+    required: false
+    type: boolean
   get-iverilog:
     description: 'Install iverilog'
     default: false
@@ -14,13 +29,34 @@ inputs:
 runs:
   using: composite
   steps:
-    - name: Install Linux Dependencies
+    - name: Linux common dependencies
       if: runner.os == 'Linux'
       uses: awalsh128/cache-apt-pkgs-action@v1.6.0
       with:
-        packages: gperf build-essential bison flex libfl-dev libreadline-dev gawk tcl-dev libffi-dev git graphviz xdot pkg-config python3 libboost-system-dev libboost-python-dev libboost-filesystem-dev zlib1g-dev libbz2-dev libgtest-dev
+        packages: autoconf git make python3
+        version: ${{ inputs.runs-on }}-commonys
+
+    - name: Linux build dependencies
+      if: runner.os == 'Linux' && inputs.get-build-deps == 'true'
+      uses: awalsh128/cache-apt-pkgs-action@v1.6.0
+      with:
+        packages: bison clang flex libboost-filesystem-dev libboost-python-dev libboost-system-dev libbz2-dev libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev
         version: ${{ inputs.runs-on }}-buildys
 
+    - name: Linux docs dependencies
+      if: runner.os == 'Linux' && inputs.get-docs-deps == 'true'
+      uses: awalsh128/cache-apt-pkgs-action@v1.6.0
+      with:
+        packages: graphviz xdot
+        version: ${{ inputs.runs-on }}-docsys
+
+    - name: Linux test dependencies
+      if: runner.os == 'Linux' && inputs.get-test-deps == 'true'
+      uses: awalsh128/cache-apt-pkgs-action@v1.6.0
+      with:
+        packages: gawk libgtest-dev
+        version: ${{ inputs.runs-on }}-testys
+
     - name: Install macOS Dependencies
       if: runner.os == 'macOS'
       shell: bash
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
index 95595924a..da30e3da4 100644
--- a/.github/workflows/codeql.yml
+++ b/.github/workflows/codeql.yml
@@ -10,8 +10,11 @@ jobs:
     name: Analyze
     runs-on: ubuntu-latest
     steps:
-    - name: Install deps
-      run: sudo apt-get install bison flex libfl-dev libreadline-dev tcl-dev libffi-dev
+    - name: Setup environment
+      uses: ./.github/actions/setup-build-env
+      with:
+        runs-on: ubuntu-latest
+        get-build-deps: true
 
     - name: Checkout repository
       uses: actions/checkout@v4
diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml
index 6bd5495f0..8c1a3bbd2 100644
--- a/.github/workflows/test-build.yml
+++ b/.github/workflows/test-build.yml
@@ -62,6 +62,7 @@ jobs:
         uses: ./.github/actions/setup-build-env
         with:
           runs-on: ${{ matrix.os }}
+          get-build-deps: true
 
       - name: Build
         shell: bash
@@ -109,7 +110,8 @@ jobs:
         uses: ./.github/actions/setup-build-env
         with:
           runs-on: ${{ matrix.os }}
-          setup-iverilog: true
+          get-test-deps: true
+          get-iverilog: true
 
       - name: Download build artifact
         uses: actions/download-artifact@v4
@@ -196,6 +198,8 @@ jobs:
         uses: ./.github/actions/setup-build-env
         with:
           runs-on: ${{ matrix.os }}
+          get-build-deps: true
+          get-docs-deps: true
 
       - name: Download build artifact
         uses: actions/download-artifact@v4
diff --git a/.github/workflows/test-compile.yml b/.github/workflows/test-compile.yml
index 5c5cdfd1d..6de52cf08 100644
--- a/.github/workflows/test-compile.yml
+++ b/.github/workflows/test-compile.yml
@@ -62,6 +62,7 @@ jobs:
         uses: ./.github/actions/setup-build-env
         with:
           runs-on: ${{ matrix.os }}
+          get-build-deps: true
 
       - name: Setup Cpp
         uses: aminya/setup-cpp@v1
diff --git a/.github/workflows/test-sanitizers.yml b/.github/workflows/test-sanitizers.yml
index 6e3dfb2f2..4c8e3ec51 100644
--- a/.github/workflows/test-sanitizers.yml
+++ b/.github/workflows/test-sanitizers.yml
@@ -46,7 +46,9 @@ jobs:
         uses: ./.github/actions/setup-build-env
         with:
           runs-on: ${{ matrix.os }}
-          setup-iverilog: true
+          get-build-deps: true
+          get-test-deps: true
+          get-iverilog: true
 
       - name: Build
         shell: bash

From c6f19790326c11a983a26c9c2e463296b4704165 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Sat, 1 Nov 2025 15:36:07 +1300
Subject: [PATCH 5/9] CI: Fix iverilog deps

---
 .github/actions/setup-build-env/action.yml | 4 ++--
 .github/actions/setup-iverilog/action.yml  | 7 +++++++
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/.github/actions/setup-build-env/action.yml b/.github/actions/setup-build-env/action.yml
index 24e7d84a5..c8dc5dc64 100644
--- a/.github/actions/setup-build-env/action.yml
+++ b/.github/actions/setup-build-env/action.yml
@@ -33,7 +33,7 @@ runs:
       if: runner.os == 'Linux'
       uses: awalsh128/cache-apt-pkgs-action@v1.6.0
       with:
-        packages: autoconf git make python3
+        packages: gawk git make python3
         version: ${{ inputs.runs-on }}-commonys
 
     - name: Linux build dependencies
@@ -54,7 +54,7 @@ runs:
       if: runner.os == 'Linux' && inputs.get-test-deps == 'true'
       uses: awalsh128/cache-apt-pkgs-action@v1.6.0
       with:
-        packages: gawk libgtest-dev
+        packages: libgtest-dev
         version: ${{ inputs.runs-on }}-testys
 
     - name: Install macOS Dependencies
diff --git a/.github/actions/setup-iverilog/action.yml b/.github/actions/setup-iverilog/action.yml
index 1517ad9c4..ac4f33ad8 100644
--- a/.github/actions/setup-iverilog/action.yml
+++ b/.github/actions/setup-iverilog/action.yml
@@ -33,6 +33,13 @@ runs:
         path: .local/
         key: ${{ inputs.runs-on }}-${{ steps.get-iverilog.outputs.IVERILOG_GIT }}
 
+    - name: iverilog Linux deps
+      if: steps.restore-iverilog.outputs.cache-hit != 'true' && runner.os == 'Linux'
+      uses: awalsh128/cache-apt-pkgs-action@v1.6.0
+      with:
+        packages: autoconf gperf make gcc g++ bison flex
+        version: ${{ inputs.runs-on }}-iverilog
+
     - name: iverilog macOS deps
       if: steps.restore-iverilog.outputs.cache-hit != 'true' && runner.os == 'macOS'
       shell: bash

From bb8c72a9d7988fbb4c28830238a726cf0c31cb84 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Sat, 1 Nov 2025 16:19:38 +1300
Subject: [PATCH 6/9] Docs: Bringing prereqs in line

Add comments in setup-build-env/action.yml for where to document prereqs (and the separation between build/run and test).
Add some initial (very basic) text for `test_suites.rst`, listing prereqs and how to run the tests (with subsections for the different optional tests, which is currently docs, functional and unit).
Add sphinx-inline-tabs, use it for tidying up prereq instructions based on OS/platform (mostly helpful in the test suites doc where there are multiple sections split by OS).
Also fixes some single backticks that should be double backtick.
---
 .github/actions/setup-build-env/action.yml    |  4 ++
 README.md                                     |  9 +--
 docs/source/conf.py                           |  2 +-
 docs/source/getting_started/installation.rst  | 69 ++++++++++---------
 docs/source/requirements.txt                  |  1 +
 .../extending_yosys/test_suites.rst           | 69 ++++++++++++++++++-
 6 files changed, 115 insertions(+), 39 deletions(-)

diff --git a/.github/actions/setup-build-env/action.yml b/.github/actions/setup-build-env/action.yml
index c8dc5dc64..4fea7ad46 100644
--- a/.github/actions/setup-build-env/action.yml
+++ b/.github/actions/setup-build-env/action.yml
@@ -29,6 +29,8 @@ inputs:
 runs:
   using: composite
   steps:
+    # if updating common/build/docs dependencies, make sure to update README.md
+    # and docs/source/getting_started/installation.rst to match.
     - name: Linux common dependencies
       if: runner.os == 'Linux'
       uses: awalsh128/cache-apt-pkgs-action@v1.6.0
@@ -50,6 +52,8 @@ runs:
         packages: graphviz xdot
         version: ${{ inputs.runs-on }}-docsys
 
+    # if updating test dependencies, make sure to update
+    # docs/source/yosys_internals/extending_yosys/test_suites.rst to match.
     - name: Linux test dependencies
       if: runner.os == 'Linux' && inputs.get-test-deps == 'true'
       uses: awalsh128/cache-apt-pkgs-action@v1.6.0
diff --git a/README.md b/README.md
index 6118d6079..059394a4e 100644
--- a/README.md
+++ b/README.md
@@ -83,10 +83,11 @@ Xdot (graphviz) is used by the ``show`` command in yosys to display schematics.
 For example on Ubuntu Linux 22.04 LTS the following commands will install all
 prerequisites for building yosys:
 
-	$ sudo apt-get install build-essential clang lld bison flex libfl-dev \
-		libreadline-dev gawk tcl-dev libffi-dev git \
-		graphviz xdot pkg-config python3 libboost-system-dev \
-		libboost-python-dev libboost-filesystem-dev zlib1g-dev
+	$ sudo apt-get install gawk git make python3 lld \
+		bison clang flex libboost-filesystem-dev libboost-python-dev \
+		libboost-system-dev libbz2-dev libffi-dev libfl-dev \
+		libreadline-dev pkg-config tcl-dev zlib1g-dev \
+		graphviz xdot
 
 The environment variable `CXX` can be used to control the C++ compiler used, or
 run one of the following to override it:
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 49f8f5eab..6740fab83 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -50,7 +50,7 @@ rst_prolog = """
    :language: yoscrypt
 """
 
-extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex']
+extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex', 'sphinx_inline_tabs']
 
 if os.getenv("READTHEDOCS"):
     # Use rtds_action if we are building on read the docs and have a github token env var
diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst
index 0ac85d199..28766e6fb 100644
--- a/docs/source/getting_started/installation.rst
+++ b/docs/source/getting_started/installation.rst
@@ -93,56 +93,63 @@ tools: readline, libffi, Tcl and zlib; are optional but enabled by default (see
 :makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the
 `show` command to display schematics.
 
-Installing all prerequisites for Ubuntu 22.04:
+Installing all prerequisites:
 
-.. code:: console
+.. tab:: Ubuntu 22.04
 
-   sudo apt-get install gperf build-essential clang lld bison flex libfl-dev \
-      libreadline-dev gawk tcl-dev libffi-dev git \
-      graphviz xdot pkg-config python3 libboost-system-dev \
-      libboost-python-dev libboost-filesystem-dev zlib1g-dev
+   .. code:: console
 
-Installing all prerequisites for macOS 13 (with Homebrew):
+      sudo apt-get install gawk git make python3 lld \
+         bison clang flex libboost-filesystem-dev libboost-python-dev \
+         libboost-system-dev libbz2-dev libffi-dev libfl-dev \
+         libreadline-dev pkg-config tcl-dev zlib1g-dev \
+         graphviz xdot
 
-.. code:: console
+.. tab:: macOS 13 (with Homebrew)
 
-   brew tap Homebrew/bundle && brew bundle
+   .. code:: console
 
-or MacPorts:
+      brew tap Homebrew/bundle && brew bundle
 
-.. code:: console
+.. tab:: MacPorts
 
-   sudo port install bison flex readline gawk libffi graphviz \
-      pkgconfig python311 boost zlib tcl
+   .. code:: console
 
-On FreeBSD use the following command to install all prerequisites:
+      sudo port install bison flex readline gawk libffi graphviz \
+         pkgconfig python311 boost zlib tcl
 
-.. code:: console
+.. tab:: FreeBSD
 
-   pkg install bison flex readline gawk libffi graphviz \
-      pkgconf python311 tcl-wrapper boost-libs
+   .. code:: console
 
-.. note:: On FreeBSD system use gmake instead of make. To run tests use:
-    ``MAKE=gmake CXX=cxx CC=cc gmake test``
+      pkg install bison flex readline gawk libffi graphviz \
+         pkgconf python311 tcl-wrapper boost-libs
 
-For Cygwin use the following command to install all prerequisites, or select these additional packages:
+   .. note:: On FreeBSD system use gmake instead of make. To run tests use:
+      ``MAKE=gmake CXX=cxx CC=cc gmake test``
 
-.. code:: console
+.. tab:: Cygwin
 
-   setup-x86_64.exe -q --packages=bison,flex,gcc-core,gcc-g++,git,libffi-devel,libreadline-devel,make,pkg-config,python3,tcl-devel,boost-build,zlib-devel
+   Use the following command to install all prerequisites, or select these
+   additional packages:
 
-.. warning::
+   .. code:: console
 
-   As of this writing, Cygwin only supports up to Python 3.9.16 while the
-   minimum required version of Python is 3.11.  This means that Cygwin is not
-   compatible with many of the Python-based frontends.  While this does not
-   currently prevent Yosys itself from working, no guarantees are made for
-   continued support.  You may also need to specify `CXXSTD=gnu++17` to resolve
-   missing `strdup` function when using gcc.  It is instead recommended to use
-   Windows Subsystem for Linux (WSL) and follow the instructions for Ubuntu.
+      setup-x86_64.exe -q --packages=bison,flex,gcc-core,gcc-g++,git,libffi-devel,libreadline-devel,make,pkg-config,python3,tcl-devel,boost-build,zlib-devel
+
+   .. warning::
+
+      As of this writing, Cygwin only supports up to Python 3.9.16 while the
+      minimum required version of Python is 3.11.  This means that Cygwin is not
+      compatible with many of the Python-based frontends.  While this does not
+      currently prevent Yosys itself from working, no guarantees are made for
+      continued support.  You may also need to specify ``CXXSTD=gnu++17`` to
+      resolve missing ``strdup`` function when using gcc.  It is instead
+      recommended to use Windows Subsystem for Linux (WSL) and follow the
+      instructions for Ubuntu.
 
 .. 
-   For MSYS2 (MINGW64):
+   tab:: MSYS2 (MINGW64)
 
    .. code:: console
 
diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt
index 203205169..403bfb1c6 100644
--- a/docs/source/requirements.txt
+++ b/docs/source/requirements.txt
@@ -1,3 +1,4 @@
 furo-ys @ git+https://github.com/YosysHQ/furo-ys
 sphinxcontrib-bibtex
 rtds-action
+sphinx-inline-tabs
diff --git a/docs/source/yosys_internals/extending_yosys/test_suites.rst b/docs/source/yosys_internals/extending_yosys/test_suites.rst
index 3e5f45b94..81a79e77f 100644
--- a/docs/source/yosys_internals/extending_yosys/test_suites.rst
+++ b/docs/source/yosys_internals/extending_yosys/test_suites.rst
@@ -1,7 +1,72 @@
 Testing Yosys
 =============
 
-.. TODO:: more about the included test suite and how to add tests
+.. todo:: adding tests (makefile-tests vs seed-tests)
+
+Running the included test suite
+-------------------------------
+
+The Yosys source comes with a test suite to avoid regressions and keep
+everything working as expected.  Tests can be run by calling ``make test`` from
+the root Yosys directory.
+
+Functional tests
+~~~~~~~~~~~~~~~~
+
+Testing functional backends (see
+:doc:`/yosys_internals/extending_yosys/functional_ir`) has a few requirements in
+addition to those listed in :ref:`getting_started/installation:Build
+prerequisites`:
+
+.. tab:: Ubuntu
+
+   .. code:: console
+
+      sudo apt-get install racket
+      raco pkg install rosette
+      pip install pytest-xdist pytest-xdist-gnumake
+
+.. tab:: macOS
+
+   .. code:: console
+
+      brew install racket
+      raco pkg install rosette
+      pip install pytest-xdist pytest-xdist-gnumake
+
+If you don't have one of the :ref:`getting_started/installation:CAD suite(s)`
+installed, you should also install Z3 `following their
+instructions <https://github.com/Z3Prover/z3>`_.
+
+Then, set the :makevar:`ENABLE_FUNCTIONAL_TESTS` make variable when calling
+``make test`` and the functional tests will be run as well.
+
+Unit tests
+~~~~~~~~~~
+
+Running the unit tests requires the following additional packages:
+
+.. tab:: Ubuntu
+
+   .. code:: console
+
+      sudo apt-get install libgtest-dev
+
+.. tab:: macOS
+
+   No additional requirements.
+
+Unit tests can be run with ``make unit-test``. 
+
+Docs tests
+~~~~~~~~~~
+
+There are some additional tests for checking examples included in the
+documentation, which can be run by calling ``make test`` from the
+:file:`yosys/docs` sub-directory (or ``make -C docs test`` from the root). This
+also includes checking some macro commands to ensure that descriptions of them
+are kept up to date, and is mostly intended for CI.
+
 
 Automatic testing
 -----------------
@@ -14,8 +79,6 @@ compiler versions.  For up to date information, including OS versions, refer to
 .. _Yosys Git repo: https://github.com/YosysHQ/yosys
 .. _the git actions page: https://github.com/YosysHQ/yosys/actions
 
-.. todo:: are unit tests currently working
-
 ..
    How to add a unit test
    ----------------------

From d1f89ccb232b82e56b4f01773d1ede658d3baf3c Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Sat, 1 Nov 2025 17:27:09 +1300
Subject: [PATCH 7/9] CI: vcd2fst needs deps

---
 .github/actions/setup-iverilog/action.yml | 26 +++++++++++------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/.github/actions/setup-iverilog/action.yml b/.github/actions/setup-iverilog/action.yml
index ac4f33ad8..557ff6add 100644
--- a/.github/actions/setup-iverilog/action.yml
+++ b/.github/actions/setup-iverilog/action.yml
@@ -9,6 +9,19 @@ inputs:
 runs:
   using: composite
   steps:
+    - name: iverilog Linux deps
+      if: steps.restore-iverilog.outputs.cache-hit != 'true' && runner.os == 'Linux'
+      uses: awalsh128/cache-apt-pkgs-action@v1.6.0
+      with:
+        packages: autoconf gperf make gcc g++ bison flex
+        version: ${{ inputs.runs-on }}-iverilog
+
+    - name: iverilog macOS deps
+      if: steps.restore-iverilog.outputs.cache-hit != 'true' && runner.os == 'macOS'
+      shell: bash
+      run: |
+        brew install autoconf
+
     - name: Get iverilog
       id: get-iverilog
       shell: bash
@@ -33,19 +46,6 @@ runs:
         path: .local/
         key: ${{ inputs.runs-on }}-${{ steps.get-iverilog.outputs.IVERILOG_GIT }}
 
-    - name: iverilog Linux deps
-      if: steps.restore-iverilog.outputs.cache-hit != 'true' && runner.os == 'Linux'
-      uses: awalsh128/cache-apt-pkgs-action@v1.6.0
-      with:
-        packages: autoconf gperf make gcc g++ bison flex
-        version: ${{ inputs.runs-on }}-iverilog
-
-    - name: iverilog macOS deps
-      if: steps.restore-iverilog.outputs.cache-hit != 'true' && runner.os == 'macOS'
-      shell: bash
-      run: |
-        brew install autoconf
-
     - name: Build iverilog
       if: steps.restore-iverilog.outputs.cache-hit != 'true'
       shell: bash

From ec2148d16bc0d5d86e639604a17fc9dd8dd905a0 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Sat, 1 Nov 2025 20:08:45 +1300
Subject: [PATCH 8/9] CI: Move libbz2 to iverilog setup

Needed for vcd2fst.
---
 .github/actions/setup-build-env/action.yml   | 2 +-
 .github/actions/setup-iverilog/action.yml    | 2 +-
 README.md                                    | 4 ++--
 docs/source/getting_started/installation.rst | 4 ++--
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/actions/setup-build-env/action.yml b/.github/actions/setup-build-env/action.yml
index 4fea7ad46..216742791 100644
--- a/.github/actions/setup-build-env/action.yml
+++ b/.github/actions/setup-build-env/action.yml
@@ -42,7 +42,7 @@ runs:
       if: runner.os == 'Linux' && inputs.get-build-deps == 'true'
       uses: awalsh128/cache-apt-pkgs-action@v1.6.0
       with:
-        packages: bison clang flex libboost-filesystem-dev libboost-python-dev libboost-system-dev libbz2-dev libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev
+        packages: bison clang flex libboost-filesystem-dev libboost-python-dev libboost-system-dev libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev
         version: ${{ inputs.runs-on }}-buildys
 
     - name: Linux docs dependencies
diff --git a/.github/actions/setup-iverilog/action.yml b/.github/actions/setup-iverilog/action.yml
index 557ff6add..0acb582e3 100644
--- a/.github/actions/setup-iverilog/action.yml
+++ b/.github/actions/setup-iverilog/action.yml
@@ -13,7 +13,7 @@ runs:
       if: steps.restore-iverilog.outputs.cache-hit != 'true' && runner.os == 'Linux'
       uses: awalsh128/cache-apt-pkgs-action@v1.6.0
       with:
-        packages: autoconf gperf make gcc g++ bison flex
+        packages: autoconf gperf make gcc g++ bison flex libbz2-dev
         version: ${{ inputs.runs-on }}-iverilog
 
     - name: iverilog macOS deps
diff --git a/README.md b/README.md
index 059394a4e..5aba7c9fb 100644
--- a/README.md
+++ b/README.md
@@ -85,8 +85,8 @@ prerequisites for building yosys:
 
 	$ sudo apt-get install gawk git make python3 lld \
 		bison clang flex libboost-filesystem-dev libboost-python-dev \
-		libboost-system-dev libbz2-dev libffi-dev libfl-dev \
-		libreadline-dev pkg-config tcl-dev zlib1g-dev \
+		libboost-system-dev libffi-dev libfl-dev libreadline-dev \
+		pkg-config tcl-dev zlib1g-dev \
 		graphviz xdot
 
 The environment variable `CXX` can be used to control the C++ compiler used, or
diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst
index 28766e6fb..ebba05c70 100644
--- a/docs/source/getting_started/installation.rst
+++ b/docs/source/getting_started/installation.rst
@@ -101,8 +101,8 @@ Installing all prerequisites:
 
       sudo apt-get install gawk git make python3 lld \
          bison clang flex libboost-filesystem-dev libboost-python-dev \
-         libboost-system-dev libbz2-dev libffi-dev libfl-dev \
-         libreadline-dev pkg-config tcl-dev zlib1g-dev \
+         libboost-system-dev libffi-dev libfl-dev libreadline-dev \
+         pkg-config tcl-dev zlib1g-dev \
          graphviz xdot
 
 .. tab:: macOS 13 (with Homebrew)

From a4a491719e11c99a4135a88207bb0b3105c7e4c1 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Sat, 1 Nov 2025 20:11:36 +1300
Subject: [PATCH 9/9] Drop boost-python

---
 .github/actions/setup-build-env/action.yml   | 2 +-
 Brewfile                                     | 1 -
 README.md                                    | 5 ++---
 docs/source/getting_started/installation.rst | 5 ++---
 4 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/.github/actions/setup-build-env/action.yml b/.github/actions/setup-build-env/action.yml
index 216742791..5ecb4d3a9 100644
--- a/.github/actions/setup-build-env/action.yml
+++ b/.github/actions/setup-build-env/action.yml
@@ -42,7 +42,7 @@ runs:
       if: runner.os == 'Linux' && inputs.get-build-deps == 'true'
       uses: awalsh128/cache-apt-pkgs-action@v1.6.0
       with:
-        packages: bison clang flex libboost-filesystem-dev libboost-python-dev libboost-system-dev libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev
+        packages: bison clang flex libboost-filesystem-dev libboost-system-dev libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev
         version: ${{ inputs.runs-on }}-buildys
 
     - name: Linux docs dependencies
diff --git a/Brewfile b/Brewfile
index c90434e62..c1d925462 100644
--- a/Brewfile
+++ b/Brewfile
@@ -8,7 +8,6 @@ brew "pkg-config"
 brew "python3"
 brew "xdot"
 brew "bash"
-brew "boost-python3"
 brew "llvm@20"
 brew "lld"
 brew "googletest"
diff --git a/README.md b/README.md
index 5aba7c9fb..960263e9d 100644
--- a/README.md
+++ b/README.md
@@ -84,9 +84,8 @@ For example on Ubuntu Linux 22.04 LTS the following commands will install all
 prerequisites for building yosys:
 
 	$ sudo apt-get install gawk git make python3 lld \
-		bison clang flex libboost-filesystem-dev libboost-python-dev \
-		libboost-system-dev libffi-dev libfl-dev libreadline-dev \
-		pkg-config tcl-dev zlib1g-dev \
+		bison clang flex libboost-filesystem-dev libboost-system-dev \
+		libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
 		graphviz xdot
 
 The environment variable `CXX` can be used to control the C++ compiler used, or
diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst
index ebba05c70..b18f8cfc6 100644
--- a/docs/source/getting_started/installation.rst
+++ b/docs/source/getting_started/installation.rst
@@ -100,9 +100,8 @@ Installing all prerequisites:
    .. code:: console
 
       sudo apt-get install gawk git make python3 lld \
-         bison clang flex libboost-filesystem-dev libboost-python-dev \
-         libboost-system-dev libffi-dev libfl-dev libreadline-dev \
-         pkg-config tcl-dev zlib1g-dev \
+         bison clang flex libboost-filesystem-dev libboost-system-dev \
+         libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
          graphviz xdot
 
 .. tab:: macOS 13 (with Homebrew)