mirror of
https://github.com/YosysHQ/yosys
synced 2025-11-03 13:07:58 +00:00
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.
This commit is contained in:
Krystine Sherwin
parent
c6f1979032
commit
bb8c72a9d7
6 changed files with 115 additions and 39 deletions
4
.github/actions/setup-build-env/action.yml
vendored
4
.github/actions/setup-build-env/action.yml
vendored
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
furo-ys @ git+https://github.com/YosysHQ/furo-ys
|
||||
sphinxcontrib-bibtex
|
||||
rtds-action
|
||||
sphinx-inline-tabs
|
||||
|
|
|
|||
|
|
@ -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
|
||||
----------------------
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue