mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2026-06-06 00:50:57 +00:00
Code Activity

Merge pull request #5927 from YosysHQ/docs-preview-cmake

Browse source 
Update docs for CMake
This commit is contained in:
Miodrag Milanović 2026-06-04 10:51:45 +00:00 • committed by GitHub
commit 7261c2b444
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
12 changed files with 297 additions and 224 deletions
Download patch file Download diff file Expand all files Collapse all files

2
.gitignore vendored
View file

@ -1,5 +1,7 @@
## user config
/Makefile.conf
/Configuration.cmake
/CMakeUserPresets.json
## homebrew
/Brewfile.lock.json

11
CMakeLists.txt
View file

@ -500,10 +500,10 @@ set(makefile_vars
PROGRAM_PREFIX=${YOSYS_PROGRAM_PREFIX}
ABC=$<IF:$<TARGET_EXISTS:yosys-abc>,$<TARGET_FILE:yosys-abc>,${YOSYS_ABC_EXECUTABLE}>
YOSYS=$<TARGET_FILE:yosys>
YOSYS_CONFIG=${CMAKE_BINARY_DIR}/yosys-config
YOSYS_CONFIG=${CMAKE_BINARY_DIR}/${YOSYS_PROGRAM_PREFIX}yosys-config
YOSYS_FILTERLIB=$<$<TARGET_EXISTS:yosys-filterlib>:$<TARGET_FILE:yosys-filterlib>>
YOSYS_SMTBMC=${CMAKE_BINARY_DIR}/yosys-smtbmc
YOSYS_WITNESS=${CMAKE_BINARY_DIR}/yosys-witness
YOSYS_SMTBMC=${CMAKE_BINARY_DIR}/${YOSYS_PROGRAM_PREFIX}yosys-smtbmc
YOSYS_WITNESS=${CMAKE_BINARY_DIR}/${YOSYS_PROGRAM_PREFIX}yosys-witness
)
set(makefile_depends
# abc is implied via $<TARGET_FILE>
@ -545,6 +545,11 @@ if (NOT YOSYS_BUILD_PYTHON_ONLY)
DEPENDS docs-prepare
)
endforeach()
add_custom_target(test-docs
COMMAND make test ${makefile_vars}
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/docs
DEPENDS ${makefile_depends}
)
endif()
# Utilities.

112
README.md
View file

@ -75,10 +75,11 @@ or
$ cd yosys
$ git submodule update --init --recursive
You need a C++ compiler with C++17 support (up-to-date CLANG or GCC is
recommended) and some standard tools such as GNU Flex, GNU Bison, and GNU Make.
TCL, readline and libffi are optional (see ``ENABLE_*`` settings in Makefile).
Xdot (graphviz) is used by the ``show`` command in yosys to display schematics.
A C++ compiler with C++20 support is required as well as some standard tools
such as GNU Flex, GNU Bison (>=3.8), CMake (>=3.27), Make (or other CMake
generator such as Ninja), and Python (>=3.11). Some additional tools: readline,
libffi, Tcl and zlib; will be used if available but are optional. Graphviz and
Xdot are used by the `show` command to display schematics.
For example on Ubuntu Linux 22.04 LTS the following commands will install all
prerequisites for building yosys:
@ -86,45 +87,66 @@ prerequisites for building yosys:
$ 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
run one of the following to override it:
**NOTE**: By default, Ubuntu 22.04 LTS is limited to CMake 3.22 via `apt`. To
install a newer version and meet the minimum required for building Yosys, use
`sudo snap install cmake --classic`.
$ make config-clang
$ make config-gcc
CMake is used for build configuration, and requires a separate build directory:
The Makefile has many variables influencing the build process. These can be
adjusted by modifying the Makefile.conf file which is created at the `make
config-...` step (see above), or they can be set by passing an option to the
make command directly:
$ cmake -B build .
$ make CXX=$CXX
Once generated, available build variables can be inspected and modified with
`ccmake` or opening the generated `build/CMakeCache.txt` file:
For other compilers and build configurations it might be necessary to make some
changes to the config section of the Makefile. It's also an alternative way to
set the make variables mentioned above.
$ ccmake build #..or..
$ vi build/CMakeCache.txt
$ vi Makefile # ..or..
$ vi Makefile.conf
When setting one-off variables, CMake provides the `-D <var>=<value>` command
line option. For example, disabling zlib support:
To build Yosys simply type 'make' in this directory.
$ cmake -B build . -DYOSYS_WITHOUT_ZLIB=ON
$ make
$ sudo make install
For a more persistent configuration, we recommend creating and using a
`CMakeUserPresets.json` file in the root `yosys` directory. Below is an example
file which enables ccache and sets the default compiler to clang when calling
`cmake --preset clang`:
Tests are located in the tests subdirectory and can be executed using the test
```json
{
"version": 1,
"configurePresets": [
{
"name": "default",
"binaryDir": "build",
"generator": "Unix Makefiles",
"cacheVariables": {
"CMAKE_C_COMPILER": "clang",
"CMAKE_CXX_COMPILER": "clang++",
"YOSYS_COMPILER_LAUNCHER": "ccache"
}
}
]
}
```
Once generated, the build system can be run as follows:
$ cmake --build build #..or..
$ cd build
$ cmake --build .
To quickly install Yosys with the default settings:
$ cmake -B build . -DCMAKE_BUILD_TYPE=Release
$ cmake --build build --config Release --parallel $(nproc)
$ sudo cmake --install build --strip
Tests are located in the tests subdirectory and can be executed using the `test`
target. Note that you need gawk, a recent version of iverilog, and gtest.
Execute tests via:
$ make test
To use a separate (out-of-tree) build directory, provide a path to the Makefile.
$ mkdir build; cd build
$ make -f ../Makefile
Out-of-tree builds require a clean source tree.
$ cmake --build build --target test --parallel $(nproc)
Getting Started
@ -134,7 +156,7 @@ Yosys can be used with the interactive command shell, with
synthesis scripts or with command line arguments. Let's perform
a simple synthesis job using the interactive command shell:
$ ./yosys
$ ./build/yosys
yosys>
the command ``help`` can be used to print a list of all available
@ -256,7 +278,7 @@ following are used for building the website:
Or for MacOS, using homebrew:
$ brew install pdf2svg libfaketime
$ brew install pdf2svg libfaketime
PDFLaTeX, included with most LaTeX distributions, is also needed during the
build process for the website. Or, run the following:
@ -265,24 +287,20 @@ build process for the website. Or, run the following:
Or for MacOS, using homebrew:
$ brew install basictex
$ sudo tlmgr update --self
$ sudo tlmgr install collection-latexextra latexmk tex-gyre
$ brew install basictex
$ sudo tlmgr update --self
$ sudo tlmgr install collection-latexextra latexmk tex-gyre
The Python package, Sphinx, is needed along with those listed in
`docs/source/requirements.txt`:
$ pip install -U sphinx -r docs/source/requirements.txt
From the root of the repository, run `make docs`. This will build/rebuild yosys
as necessary before generating the website documentation from the yosys help
commands. To build for pdf instead of html, call
`make docs DOC_TARGET=latexpdf`.
DOCS (e.g.)
$ cmake --build build --target docs-html --parallel
This will build/rebuild yosys as necessary before generating the website
documentation from the yosys help commands. To build for pdf instead of html,
use the `docs-latexpdf` target.
It is recommended to use the `ENABLE_HELP_SOURCE` make option for Yosys builds
that will be used to build the documentation. This option enables source
location tracking for passes and improves the command reference through grouping
related commands and allowing for the documentation to link to the corresponding
source files. Without this, a warning will be raised during the Sphinx build
about `Found commands assigned to group unknown` and `make docs` is configured
to fail on warnings by default.

2
cmake/YosysAbcSubmodule.cmake
View file

@ -56,7 +56,7 @@ function(yosys_check_abc_submodule)
else() #
message(FATAL_ERROR
"${CMAKE_SOURCE_DIR} is not configured as a git repository, and 'abc' folder is missing.\n"
"If you already have ABC, set 'ABCEXTERNAL' make variable to point to ABC executable.\n"
"If you already have ABC, set 'YOSYS_ABC_EXECUTABLE' CMake variable to point to ABC executable.\n"
"Otherwise, download release archive 'yosys.tar.gz' from https://github.com/YosysHQ/yosys/releases.\n"
" ('Source code' archive does not contain submodules.)\n"
)

10
docs/Makefile
View file

@ -265,15 +265,15 @@ extract:
@mkdir -p source/generated/functional
@cp ../backends/functional/smtlib.cc source/generated/functional/
-@cd .. && diff -U 20 backends/functional/smtlib.cc backends/functional/smtlib_rosette.cc \
@cd .. && diff -U 20 backends/functional/smtlib.cc backends/functional/smtlib_rosette.cc \
> docs/source/generated/functional/rosette.diff || true
@$(YOSYS) --help >source/generated/yosys
@$(YOSYS) --help | sed "s%$(YOSYS)%$(PROGRAM_PREFIX)yosys%g" - >source/generated/yosys
@$(YOSYS_SMTBMC) --help >source/generated/yosys-smtbmc
@$(YOSYS_WITNESS) --help >source/generated/yosys-witness
@$(YOSYS_CONFIG) --help >source/generated/yosys-config
@$(YOSYS_FILTERLIB) --help 2>source/generated/yosys-filterlib || true
@$(ABC) --help 2>source/generated/yosys-abc > /dev/null || true
@$(YOSYS_CONFIG) --help | sed "s%$(YOSYS_CONFIG)%$(PROGRAM_PREFIX)yosys-config%g" - >source/generated/yosys-config
@$(YOSYS_FILTERLIB) --help 2>&1 >/dev/null | sed "s%filterlib%$(PROGRAM_PREFIX)yosys-filterlib%g" - >source/generated/yosys-filterlib
@$(ABC) --help 2>&1 >/dev/null | sed "s%$(ABC)%$(PROGRAM_PREFIX)yosys-abc%g" - >source/generated/yosys-abc
.PHONY: gen
gen:

5
docs/source/appendix/env_vars.rst
View file

@ -14,8 +14,9 @@ Yosys environment variables
Used for storing temporary files.
``ABC``
When compiling Yosys with out-of-tree ABC using :makevar:`ABCEXTERNAL`, this
variable can be used to override the external ABC executable.
When compiling Yosys with out-of-tree ABC using
:makevar:`YOSYS_ABC_EXECUTABLE`, this variable can be used to override the
external ABC executable.
``YOSYS_NOVERIFIC``
If Yosys was built with Verific, this environment variable can be used to

3
docs/source/code_examples/stubnets/Makefile
View file

@ -3,14 +3,13 @@ include ../../../common.mk
.PHONY: all dots examples
all: dots examples
dots:
examples:
examples: test
.PHONY: test
test: stubnets.so
@$(YOSYS) -ql test1.log -m ./stubnets.so test.v -p "stubnets" >/dev/null 2>&1
@$(YOSYS) -ql test2.log -m ./stubnets.so test.v -p "opt; stubnets" >/dev/null 2>&1
@$(YOSYS) -ql test3.log -m ./stubnets.so test.v -p "techmap; opt; stubnets -report_bits" >/dev/null 2>&1
@tail test1.log test2.log test3.log
stubnets.so: stubnets.cc
@$(YOSYS_CONFIG) --exec --cxx --cxxflags --ldflags -o $@ -shared $^ --ldlibs >/dev/null 2>&1

166
docs/source/getting_started/installation.rst
View file

@ -67,7 +67,7 @@ clone these submodules at the same time, use e.g.:
As of Yosys v0.47, releases include a ``yosys.tar.gz`` file which includes
all source code and all sub-modules in a single archive. This can be used as
an alternative which does not rely on ``git``.
an alternative which does not rely on :program:`git`.
Supported platforms
^^^^^^^^^^^^^^^^^^^
@ -88,10 +88,10 @@ Build prerequisites
^^^^^^^^^^^^^^^^^^^
A C++ compiler with C++20 support is required as well as some standard tools
such as GNU Flex, GNU Bison (>=3.8), Make, and Python (>=3.11). Some additional
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.
such as GNU Flex, GNU Bison (>=3.8), CMake (>=3.27), Make (or other CMake
generator such as Ninja), and Python (>=3.11). Some additional tools: readline,
libffi, Tcl and zlib; will be used if available but are optional. Graphviz and
Xdot are used by the `show` command to display schematics.
Installing all prerequisites:
@ -102,7 +102,15 @@ Installing all prerequisites:
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
sudo snap install cmake --classic
.. tab:: Ubuntu 24.04
.. code:: console
sudo apt-get install gawk git cmake make python3 lld bison clang flex \
libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
graphviz xdot
.. tab:: macOS 13 (with Homebrew)
@ -114,19 +122,16 @@ Installing all prerequisites:
.. code:: console
sudo port install bison flex readline gawk libffi graphviz \
sudo port install bison cmake flex readline gawk libffi graphviz \
pkgconfig python311 zlib tcl
.. tab:: FreeBSD
.. code:: console
pkg install bison flex readline gawk libffi graphviz \
pkg install bison cmake-core flex readline gawk libffi graphviz \
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``
.. tab:: Cygwin
Use the following command to install all prerequisites, or select these
@ -134,7 +139,7 @@ Installing all prerequisites:
.. 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,zlib-devel
setup-x86_64.exe -q --packages=bison,flex,gcc-core,gcc-g++,git,libffi-devel,libreadline-devel,cmake,make,pkg-config,python3,tcl-devel,zlib-devel
.. warning::
@ -142,7 +147,7 @@ Installing all prerequisites:
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
continued support. You may also need to specify ``CXXSTD=gnu++20`` 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.
@ -168,71 +173,86 @@ Installing all prerequisites:
Build configuration
^^^^^^^^^^^^^^^^^^^
The Yosys build is based solely on Makefiles, and uses a number of variables
which influence the build process. The recommended method for configuring
builds is with a ``Makefile.conf`` file in the root ``yosys`` directory. The
following commands will clean the directory and provide an initial configuration
file:
The Yosys build is configured via CMake, and uses a number of variables which
influence the build process. When setting one-off variables, CMake provides the
``-D <var>=<value>`` command line option. For example, disabling zlib support:
.. code:: console
make config-clang # ..or..
make config-gcc
cmake -B build . -DYOSYS_WITHOUT_ZLIB=ON
Check the root Makefile to see what other configuration targets are available.
Other variables can then be added to the ``Makefile.conf`` as needed, for
example:
.. warning::
Yosys does not support in-tree builds. If calling :program:`cmake` from the
root ``yosys`` directory the ``-B`` option must be provided.
For a more persistent configuration, we recommend creating and using a
``CMakeUserPresets.json`` file in the root ``yosys`` directory. Below is an
example file which enables ccache and sets the default compiler to clang when
calling ``cmake --preset default``:
.. code-block:: json
:caption: CMakeUserPresets.json
{
"version": 1,
"configurePresets": [
{
"name": "default",
"binaryDir": "build",
"generator": "Unix Makefiles",
"cacheVariables": {
"CMAKE_C_COMPILER": "clang",
"CMAKE_CXX_COMPILER": "clang++",
"YOSYS_COMPILER_LAUNCHER": "ccache"
}
}
]
}
Once generated, available build variables can be inspected and modified with
:program:`ccmake` or opening the generated ``build/CMakeCache.txt`` file:
.. code:: console
echo "ENABLE_ZLIB := 0" >> Makefile.conf
Using one of these targets will set the ``CONFIG`` variable to something other
than ``none``, and will override the environment variable for ``CXX``. To use a
different compiler than the default when building, use:
.. code:: console
make CXX=$CXX # ..or..
make CXX="g++-11"
.. note::
Setting the compiler in this way will prevent some other options such as
``ENABLE_CCACHE`` from working as expected.
ccmake build #..or..
vi build/CMakeCache.txt
If you have clang, and (a compatible version of) ``ld.lld`` available in PATH,
it's recommended to speed up incremental builds with lld by enabling LTO with
``ENABLE_LTO=1``. On macOS, LTO requires using clang from homebrew rather than
clang from xcode. For example:
``CMAKE_INTERPROCEDURAL_OPTIMIZATION=ON``. On macOS, LTO requires using clang
from homebrew rather than clang from xcode. For example:
.. code:: console
make ENABLE_LTO=1 CXX=$(brew --prefix)/opt/llvm/bin/clang++
cmake -B build . -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON \
-DCMAKE_C_COMPILER=$(brew --prefix)/opt/llvm/bin/clang \
-DCMAKE_CXX_COMPILER=$(brew --prefix)/opt/llvm/bin/clang++
By default, building (and installing) yosys will build (and install) `ABC`_,
By default, building (and installing) Yosys will build (and install) `ABC`_,
using :program:`yosys-abc` as the executable name. To use an existing ABC
executable instead, set the ``ABCEXTERNAL`` make variable to point to the
desired executable.
executable instead, set the :makevar:`YOSYS_ABC_EXECUTABLE` CMake variable to
point to the desired executable.
Running the build system
^^^^^^^^^^^^^^^^^^^^^^^^
From the root ``yosys`` directory, call the following commands:
To quickly install Yosys with default settings, call the following commands from
the root ``yosys`` directory:
.. code:: console
make
sudo make install
cmake -B build . -DCMAKE_BUILD_TYPE=Release --fresh
cmake --build build --config Release --parallel $(nproc)
sudo cmake --install build --strip
To use a separate (out-of-tree) build directory, provide a path to the Makefile.
To use an existing configuration, use the ``--build`` option, e.g:
.. code:: console
mkdir build; cd build
make -f ../Makefile
Out-of-tree builds require a clean source tree.
cmake -B build .
ccmake build # modify configuration
cmake --build build
.. seealso::
@ -248,6 +268,9 @@ directories:
``backends/``
This directory contains a subdirectory for each of the backend modules.
``cmake/``
Additional ``.cmake`` files used by CMake during build generation.
``docs/``
Contains the source for this documentation, including images and sample code.
@ -281,6 +304,10 @@ directories:
example as of this writing the directory :file:`passes/hierarchy/` contains
the code for three passes: `hierarchy`, `submod`, and `uniquify`.
``pyosys/``
Contains the scripts and wrappers necessary for building :doc:`Pyosys
</using_yosys/pyosys>`.
``techlibs/``
This directory contains simulation models and standard implementations for
the cells from the internal cell library.
@ -289,19 +316,26 @@ directories:
This directory contains the suite of unit tests and regression tests used by
Yosys. See :doc:`/yosys_internals/extending_yosys/test_suites`.
The top-level Makefile includes :file:`frontends/{*}/Makefile.inc`,
:file:`passes/{*}/Makefile.inc` and :file:`backends/{*}/Makefile.inc`. So when
extending Yosys it is enough to create a new directory in :file:`frontends/`,
:file:`passes/` or :file:`backends/` with your sources and a
:file:`Makefile.inc`. The Yosys kernel automatically detects all commands linked
with Yosys. So it is not needed to add additional commands to a central list of
commands.
.. TODO:: CMAKE_TODO
Good starting points for reading example source code to learn how to write
passes are :file:`passes/opt/opt_dff.cc` and :file:`passes/opt/opt_merge.cc`.
- ``yosys_<pass|test_pass|frontend|backend>(<name>)`` for each pass
Users of the Qt Creator IDE can generate a QT Creator project file using make
qtcreator. Users of the Eclipse IDE can use the "Makefile Project with Existing
Code" project type in the Eclipse "New Project" dialog (only available after the
CDT plugin has been installed) to create an Eclipse project in order to
programming extensions to Yosys or just browse the Yosys code base.
- see :file:`cmake/YosysComponent.cmake`
- if using a sub folder, add it to the parent's ``CMakeLists.txt`` with
``add_subdirectory(<name>)``
- previous:
The Yosys kernel automatically detects all commands linked
with Yosys. So it is not needed to add additional commands to a central list of
commands.
Good starting points for reading example source code to learn how to write
passes are :file:`passes/opt/opt_dff.cc` and :file:`passes/opt/opt_merge.cc`.
Users of the Qt Creator IDE can generate a QT Creator project file using make
qtcreator. Users of the Eclipse IDE can use the "Makefile Project with Existing
Code" project type in the Eclipse "New Project" dialog (only available after the
CDT plugin has been installed) to create an Eclipse project in order to
programming extensions to Yosys or just browse the Yosys code base.

20
docs/source/using_yosys/pyosys.rst
View file

@ -1,6 +1,8 @@
Scripting with Pyosys
=====================
.. TODO:: document libyosys sans python
Pyosys is a limited subset of the Yosys C++ API (aka "libyosys") made available
using the Python programming language.
@ -14,6 +16,13 @@ Though unlike these two, Pyosys goes a bit further, allowing you to use the
Yosys API to implement advanced functionality that would otherwise require
custom passes written in C++.
.. note::
It is recommended to install :program:`uv` for managing python environments:
.. code:: console
curl -LsSf https://astral.sh/uv/install.sh | sh
Getting Pyosys
--------------
@ -21,7 +30,7 @@ Getting Pyosys
Pyosys supports CPython 3.8 or higher. You can access Pyosys using one of two
methods:
1. Compiling Yosys with the Makefile flag ``ENABLE_PYOSYS=1``
1. Compiling Yosys with the CMake flag ``-DYOSYS_WITH_PYTHON=ON``
This adds the flag ``-y`` to the Yosys binary, which allows you to execute
Python scripts using an interpreter embedded in Yosys itself:
@ -29,12 +38,9 @@ methods:
``yosys -y ./my_pyosys_script.py``
Do note this requires some build-time dependencies to be available to Python,
namely, ``pybind11`` and ``cxxheaderparser``. By default, the required
``uv`` package will be used to create an ephemeral environment with the
correct versions of the tools installed.
You can force use of your current Python environment by passing the Makefile
flag ``PYOSYS_USE_UV=0``.
namely, ``pybind11`` and ``cxxheaderparser``. :program:`uv` may be used to
create an ephemeral environment with the correct versions of the tools
installed if the current python environment doesn't provide them.
2. Installing the Pyosys wheels

98
docs/source/yosys_internals/extending_yosys/build_verific.rst
View file

@ -39,36 +39,30 @@ incorrect results.
Compile options
---------------
To enable Verific support ``ENABLE_VERIFIC`` has to be set to ``1`` and
``VERIFIC_DIR`` needs to point to the location where the library is located.
To enable Verific support, set the :makevar:`YOSYS_VERIFIC_DIR` CMake variable
to point to the location where the library is located, e.g.
============== ========================== ===============================
Parameter Default Description
============== ========================== ===============================
ENABLE_VERIFIC 0 Enable compilation with Verific
VERIFIC_DIR /usr/local/src/verific_lib Library and headers location
============== ========================== ===============================
.. code-block:: console
Since there are multiple Verific library builds and they can have different
features, there are compile options to select them.
cmake -B build . -DYOSYS_VERIFIC_DIR="/usr/local/src/verific_lib"
================================= ======= ===================================
Parameter Default Description
================================= ======= ===================================
ENABLE_VERIFIC_SYSTEMVERILOG 1 SystemVerilog support
ENABLE_VERIFIC_VHDL 1 VHDL support
ENABLE_VERIFIC_HIER_TREE 1 Hierarchy tree support
ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS 0 YosysHQ specific extensions support
ENABLE_VERIFIC_EDIF 0 EDIF support
ENABLE_VERIFIC_LIBERTY 0 Liberty file support
================================= ======= ===================================
During building, CMake will attempt to automatically detect available Verific
library components to enable the corresponding compile-time option in Yosys.
This can be overridden by manually setting the :makevar:`YOSYS_VERIFIC_FEATURES`
CMake variable. This variable should contain a semi-colon separated list, e.g.
``-DYOSYS_VERIFIC_FEATURES="systemverilog;hier_tree"``. The table below lists
the features available to Yosys.
To find the compile options used for a given Yosys build, call ``yosys-config
--cxxflags``. This documentation was built with the following compile options:
.. literalinclude:: /generated/yosys-config
:start-at: --cxxflags
:end-before: --linkflags
============== =========== ===================================
Feature Directory Description
============== =========== ===================================
systemverilog verilog SystemVerilog support
vhdl vhdl VHDL support
hier_tree hier_tree Hierarchy tree support
extensions extensions YosysHQ specific extensions support
edif edif EDIF support
liberty synlib Liberty file support
============== =========== ===================================
.. note::
@ -82,11 +76,10 @@ are required for the Yosys-Verific patch:
* RTL elaboration with
* SystemVerilog with ``ENABLE_VERIFIC_SYSTEMVERILOG``, and/or
* VHDL support with ``ENABLE_VERIFIC_VHDL``.
* SystemVerilog with ``systemverilog``, and/or
* VHDL support with ``vhdl``.
* Hierarchy tree support and static elaboration with
``ENABLE_VERIFIC_HIER_TREE``.
* Hierarchy tree support and static elaboration with ``hier_tree``.
Please be aware that the following Verific configuration build parameter needs
to be enabled in order to create the fully supported build:
@ -105,11 +98,12 @@ to be enabled in order to create the fully supported build:
Optional Verific features
~~~~~~~~~~~~~~~~~~~~~~~~~
The following Verific features are available with TabbyCAD and can be enabled in
Yosys builds:
The following Verific features are available with TabbyCAD and will be
automatically enabled in Yosys builds if the listed directory is included in the
:makevar:`YOSYS_VERIFIC_DIR`:
* EDIF support with ``ENABLE_VERIFIC_EDIF``, and
* Liberty file support with ``ENABLE_VERIFIC_LIBERTY``.
* EDIF support with ``edif`` directory, and
* Liberty file support with ``synlib`` directory.
Partially supported builds
~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -124,32 +118,18 @@ lists a series of build configurations which are possible, but only provide a
limited subset of features. Please note that support is limited without YosysHQ
specific extensions of Verific library.
Configuration values:
a. ``ENABLE_VERIFIC_SYSTEMVERILOG``
b. ``ENABLE_VERIFIC_VHDL``
c. ``ENABLE_VERIFIC_HIER_TREE``
d. ``ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS``
+--------------------------------------------------------------------------+-----+-----+-----+-----+
| | Configuration values |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
| Features | a | b | c | d |
+==========================================================================+=====+=====+=====+=====+
| SystemVerilog + RTL elaboration | 1 | 0 | 0 | 0 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
| VHDL + RTL elaboration | 0 | 1 | 0 | 0 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
| SystemVerilog + VHDL + RTL elaboration | 1 | 1 | 0 | 0 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
| SystemVerilog + RTL elaboration + Static elaboration + Hier tree | 1 | 0 | 1 | 0 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
| VHDL + RTL elaboration + Static elaboration + Hier tree | 0 | 1 | 1 | 0 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
| SystemVerilog + VHDL + RTL elaboration + Static elaboration + Hier tree | 1 | 1 | 1 | 0 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
======================================================================= =================================
Features :makevar:`YOSYS_VERIFIC_FEATURES`
======================================================================= =================================
SystemVerilog + RTL elaboration systemverilog
VHDL + RTL elaboration vhdl
SystemVerilog + VHDL + RTL elaboration systemverilog;vhdl
SystemVerilog + RTL elaboration + Static elaboration + Hier tree systemverilog;vhdl;hier_tree
VHDL + RTL elaboration + Static elaboration + Hier tree vhdl;hier_tree
SystemVerilog + VHDL + RTL elaboration + Static elaboration + Hier tree systemverilog;vhdl;hier_tree
======================================================================= =================================
.. note::
In case your Verific build has EDIF and/or Liberty support, you can enable
those options. These are not mentioned above for simplification and since
they are disabled by default.
those options. These are not mentioned above for simplification.

55
docs/source/yosys_internals/extending_yosys/test_suites.rst
View file

@ -7,28 +7,29 @@ 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. By default, this runs vanilla and unit tests.
everything working as expected. Tests can be run by building the ``test``
target from the root Yosys directory. By default, this runs vanilla and unit
tests.
.. code:: console
cmake -B build .
cmake --build build --target test --parallel $(nproc)
Vanilla tests
~~~~~~~~~~~~~
These make up the majority of our testing coverage.
They can be run with ``make vanilla-test`` and are based on calls to
make subcommands (``make makefile-tests``) and shell scripts
(``make seed-tests`` and ``make abcopt-tests``). Both use ``run-test.sh``
files, but make-based tests only call ``tests/gen-tests-makefile.sh``
to generate a makefile appropriate for the given directory, so only
afterwards when make is invoked do the tests actually run.
.. TODO:: update for test infra changes
Usually their structure looks something like this:
you write a .ys file that gets automatically run,
which runs a frontend like ``read_verilog`` or ``read_rtlil`` with
a relative path or a heredoc, then runs some commands including the command
under test, and then uses :doc:`/using_yosys/more_scripting/selections`
with ``-assert-count``. Usually it's unnecessary to "register" the test anywhere
as if it's being added to an existing directory, depending
on how the ``run-test.sh`` in that directory works.
These make up the majority of our testing coverage. They can be run with the
``test-vanilla`` CMake target. Usually their structure looks something like
this: you write a .ys file that gets automatically run, which runs a frontend
like ``read_verilog`` or ``read_rtlil`` with a relative path or a heredoc, then
runs some commands including the command under test, and then uses
:doc:`/using_yosys/more_scripting/selections` with ``-assert-count``. Usually
it's unnecessary to "register" the test anywhere as if it's being added to an
existing directory, depending on how the ``run-test.sh`` in that directory
works.
Unit tests
~~~~~~~~~~
@ -45,7 +46,7 @@ Running the unit tests requires the following additional packages:
No additional requirements.
Unit tests can be run with ``make unit-test``.
Unit tests can be run with the ``test-unit`` CMake target.
Functional tests
~~~~~~~~~~~~~~~~
@ -75,17 +76,23 @@ 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.
.. TODO:: CMAKE_TODO
How does this work under CMake? Is it only via ``make -C tests
ENABLE_FUNCTIONAL_TESTS=1`` and then manually setting ``BUILD_DIR`` and
``PROGRAM_PREFIX``? And possibly also setting ``YOSYS`` et al if there is a
``.exe``. Previous instructions:
Then, set the :makevar:`ENABLE_FUNCTIONAL_TESTS` make variable when calling
``make test`` and the functional tests will be run as well.
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.
documentation, which can be run with the ``test-docs`` CMake target. 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

37
kernel/register.cc
View file

@ -28,6 +28,7 @@
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <filesystem>
YOSYS_NAMESPACE_BEGIN
@ -772,6 +773,10 @@ struct HelpPass : public Pass {
bool raise_error = false;
std::map<string, vector<string>> groups;
// get root path
auto this_path = std::filesystem::path(source_location::current().file_name());
auto source_root = this_path.parent_path().parent_path();
json.name("cmds"); json.begin_object();
// iterate over commands
for (auto &it : pass_register) {
@ -912,10 +917,29 @@ struct HelpPass : public Pass {
}
}
// fix path
string source_file = pass->location.file_name();
bool has_source = source_file.compare("unknown") != 0;
std::filesystem::path source_path;
auto no_source_group = false;
if (has_source) {
source_path = std::filesystem::path(pass->location.file_name());
if (source_path.is_absolute()) {
// using proximate instead of relative means that we
// still get the source path if they aren't relative
auto proximate_path = std::filesystem::proximate(source_path, source_root);
if (proximate_path == std::filesystem::weakly_canonical(proximate_path))
// we're only interested if it's a subpath of our root dir
source_path = proximate_path;
else
// don't try to group external paths
no_source_group = true;
}
source_file = source_path.string();
}
// attempt auto group
if (!cmd_help.has_group()) {
string source_file = pass->location.file_name();
bool has_source = source_file.compare("unknown") != 0;
if (pass->internal_flag)
cmd_help.group = "internal";
else if (source_file.find("backends/") == 0 || (!has_source && name.find("read_") == 0))
@ -923,11 +947,8 @@ struct HelpPass : public Pass {
else if (source_file.find("frontends/") == 0 || (!has_source && name.find("write_") == 0))
cmd_help.group = "frontends";
else if (has_source) {
auto last_slash = source_file.find_last_of('/');
if (last_slash != string::npos) {
auto parent_path = source_file.substr(0, last_slash);
cmd_help.group = parent_path;
}
if (source_path.has_parent_path() && !no_source_group)
cmd_help.group = source_path.parent_path().string();
}
// implicit !has_source
else if (name.find("equiv") == 0)
@ -955,7 +976,7 @@ struct HelpPass : public Pass {
json.value(content.to_json());
json.end_array();
json.entry("group", cmd_help.group);
json.entry("source_file", pass->location.file_name());
json.entry("source_file", source_file);
json.entry("source_line", pass->location.line());
json.entry("source_func", pass->location.function_name());
json.entry("experimental_flag", pass->experimental_flag);