Merge pull request #5454 from YosysHQ/krys/cache-apt

Shuffling and documenting prerequisites

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

@@ -1,15 +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-dev zlib1g-dev libbz2-dev libgtest-dev
-        curl -LsSf https://astral.sh/uv/install.sh | sh
+      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 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'
@@ -33,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

.github/workflows/wheels.yml

@@ -25,13 +25,13 @@ jobs:
               archs: "aarch64",
             },
             {
-              name: "macOS 13",
+              name: "macOS 15 x64",
               family: "macos",
               runner: "macos-15-intel",
               archs: "x86_64",
             },
             {
-              name: "macOS 14",
+              name: "macOS 15 arm64",
               family: "macos",
               runner: "macos-15",
               archs: "arm64",
@@ -54,6 +54,11 @@ jobs:
           fetch-depth: 0
           submodules: true
           persist-credentials: false
+      - if: ${{ matrix.os.family == 'linux' }}
+        name: "[Linux] Install UV"
+        shell: bash
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
       - uses: actions/setup-python@v5
       - name: Get FFI
         shell: bash
@@ -114,7 +119,7 @@ jobs:
           path: ./wheelhouse/*.whl
   upload_wheels:
     name: Upload Wheels
-    if: github.repository == 'YosysHQ/Yosys'
+    if: (github.repository == 'YosysHQ/Yosys') && (github.event_name == 'workflow_dispatch')
     runs-on: ubuntu-latest
     # Specifying a GitHub environment is optional, but strongly encouraged
     environment: pypi

.github/workflows/wheels/_run_cibw_linux.py

@@ -24,10 +24,10 @@ from pathlib import Path
 
 __yosys_root__ = Path(__file__).absolute().parents[3]
 
-for source in ["boost", "ffi", "bison"]:
+for source in ["ffi", "bison"]:
     if not (__yosys_root__ / source).is_dir():
         print(
-            "You need to download boost, ffi and bison in a similar manner to wheels.yml first."
+            "You need to download ffi and bison in a similar manner to wheels.yml first."
         )
         exit(-1)
 

.gitignore

@@ -55,7 +55,6 @@
 # pyosys
 /kernel/*.pyh
 /kernel/python_wrappers.cc
-/boost
 /ffi
 /bison
 /venv

README.md

@@ -83,9 +83,9 @@ 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-dev zlib1g-dev
+	$ sudo apt-get install gawk git make python3 lld bison clang flex \
+		libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
+		graphviz xdot
 	$ curl -LsSf https://astral.sh/uv/install.sh | sh
 
 The environment variable `CXX` can be used to control the C++ compiler used, or

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,43 +93,48 @@ 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:
+
+.. tab:: Ubuntu 22.04
 
    .. code:: console
 
-   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-dev zlib1g-dev
+      sudo apt-get install gawk git make python3 lld bison clang flex \
+         libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
+         graphviz xdot
       curl -LsSf https://astral.sh/uv/install.sh | sh
 
-Installing all prerequisites for macOS 13 (with Homebrew):
+.. tab:: macOS 13 (with Homebrew)
 
    .. code:: console
 
       brew tap Homebrew/bundle && brew bundle
 
-or MacPorts:
+.. tab:: MacPorts
 
    .. code:: console
 
       sudo port install bison flex readline gawk libffi graphviz \
-      pkgconfig python311 boost zlib tcl
+         pkgconfig python311 zlib tcl
 
-On FreeBSD use the following command to install all prerequisites:
+.. tab:: FreeBSD
 
    .. code:: console
 
       pkg install bison flex readline gawk libffi graphviz \
-      pkgconf python311 tcl-wrapper boost-libs
+         pkgconf python311 tcl-wrapper
 
    .. note:: On FreeBSD system use gmake instead of make. To run tests use:
       ``MAKE=gmake CXX=cxx CC=cc gmake test``
 
-For Cygwin use the following command to install all prerequisites, or select these additional packages:
+.. tab:: Cygwin
+
+   Use the following command to install all prerequisites, or select these
+   additional packages:
 
    .. code:: console
 
-   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
+      setup-x86_64.exe -q --packages=bison,flex,gcc-core,gcc-g++,git,libffi-devel,libreadline-devel,make,pkg-config,python3,tcl-devel,zlib-devel
 
    .. warning::
 
@@ -137,16 +142,17 @@ For Cygwin use the following command to install all prerequisites, or select 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.
+      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
 
-      pacman -S bison flex mingw-w64-x86_64-gcc git libffi-devel libreadline-devel make pkg-config python3 tcl-devel mingw-w64-x86_64-boost zlib-devel
+      pacman -S bison flex mingw-w64-x86_64-gcc git libffi-devel libreadline-devel make pkg-config python3 tcl-devel zlib-devel
 
    Not that I can get this to work; it's failing during ld with what looks like
    math library issues: ``multiple definition of `tanh'`` and

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

flake.nix

@@ -41,7 +41,7 @@
         packages.default = yosys;
         defaultPackage = yosys;
         devShell = pkgs.mkShell {
-          buildInputs = with pkgs; [ clang llvmPackages.bintools gcc bison flex libffi tcl readline python3 zlib git gtest abc-verifier verilog boost python3Packages.boost ];
+          buildInputs = with pkgs; [ clang llvmPackages.bintools gcc bison flex libffi tcl readline python3 zlib git gtest abc-verifier verilog ];
         };
       }
     );