Merge a4a491719e into 797780eda5

.github/actions/setup-build-env/action.yml

@@ -1,14 +1,65 @@
 name: Build environment setup
 description: Configure build env for Yosys builds
+
+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
+    required: false
+    type: boolean
+
 runs:
   using: composite
   steps:
-    - name: Install Linux Dependencies
+    # 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'
-      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: gawk 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-system-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
+
+    # 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
+      with:
+        packages: libgtest-dev
+        version: ${{ inputs.runs-on }}-testys
 
     - name: Install macOS Dependencies
       if: runner.os == 'macOS'
@@ -32,3 +83,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 == 'true'
+      uses: ./.github/actions/setup-iverilog
+      with:
+        runs-on: ${{ inputs.runs-on }}

.github/actions/setup-iverilog/action.yml

@@ -0,0 +1,70 @@
+name: iverilog setup
+description: Cached build and install of iverilog
+
+inputs:
+  runs-on:
+    required: true
+    type: string
+
+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 libbz2-dev
+        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
+      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
+
+    - uses: actions/cache/restore@v4
+      id: restore-iverilog
+      with:
+        path: .local/
+        key: ${{ inputs.runs-on }}-${{ steps.get-iverilog.outputs.IVERILOG_GIT }}
+
+    - name: Build iverilog
+      if: steps.restore-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
+
+    - 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 }}

.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

.github/workflows/test-build.yml

@@ -60,6 +60,9 @@ jobs:
 
       - name: Setup environment
         uses: ./.github/actions/setup-build-env
+        with:
+          runs-on: ${{ matrix.os }}
+          get-build-deps: true
 
       - name: Build
         shell: bash
@@ -105,48 +108,10 @@ jobs:
 
       - name: Setup environment
         uses: ./.github/actions/setup-build-env
-
-      - 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
+          runs-on: ${{ matrix.os }}
+          get-test-deps: true
+          get-iverilog: true
 
       - name: Download build artifact
         uses: actions/download-artifact@v4
@@ -191,6 +156,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 +196,10 @@ jobs:
 
       - name: Setup environment
         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

.github/workflows/test-compile.yml

@@ -60,6 +60,9 @@ jobs:
 
       - name: Setup environment
         uses: ./.github/actions/setup-build-env
+        with:
+          runs-on: ${{ matrix.os }}
+          get-build-deps: true
 
       - name: Setup Cpp
         uses: aminya/setup-cpp@v1

.github/workflows/test-sanitizers.yml

@@ -44,53 +44,11 @@ jobs:
 
       - name: Setup environment
         uses: ./.github/actions/setup-build-env
-
-      - 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
+          runs-on: ${{ matrix.os }}
+          get-build-deps: true
+          get-test-deps: true
+          get-iverilog: true
 
       - name: Build
         shell: bash

Brewfile

@@ -8,7 +8,6 @@ brew "pkg-config"
 brew "python3"
 brew "xdot"
 brew "bash"
-brew "boost-python3"
 brew "llvm@20"
 brew "lld"
 brew "googletest"

README.md

@@ -83,10 +83,10 @@ 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-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
 run one of the following to override it:

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

docs/source/getting_started/installation.rst

@@ -93,56 +93,62 @@ 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-system-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
 

docs/source/requirements.txt

@@ -1,3 +1,4 @@
 furo-ys @ git+https://github.com/YosysHQ/furo-ys
 sphinxcontrib-bibtex
 rtds-action
+sphinx-inline-tabs

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
    ----------------------