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 `_. + +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 ----------------------