mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2026-06-06 17:11:01 +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 ## user config
/Makefile.conf /Makefile.conf
/Configuration.cmake
/CMakeUserPresets.json
## homebrew ## homebrew
/Brewfile.lock.json /Brewfile.lock.json

11
CMakeLists.txt
View file

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

112
README.md
View file

@ -75,10 +75,11 @@ or
$ cd yosys $ cd yosys
$ git submodule update --init --recursive $ git submodule update --init --recursive
You need a C++ compiler with C++17 support (up-to-date CLANG or GCC is A C++ compiler with C++20 support is required as well as some standard tools
recommended) and some standard tools such as GNU Flex, GNU Bison, and GNU Make. such as GNU Flex, GNU Bison (>=3.8), CMake (>=3.27), Make (or other CMake
TCL, readline and libffi are optional (see ``ENABLE_*`` settings in Makefile). generator such as Ninja), and Python (>=3.11). Some additional tools: readline,
Xdot (graphviz) is used by the ``show`` command in yosys to display schematics. 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 For example on Ubuntu Linux 22.04 LTS the following commands will install all
prerequisites for building yosys: prerequisites for building yosys:
@ -86,45 +87,66 @@ prerequisites for building yosys:
$ sudo apt-get install gawk git make python3 lld bison clang flex \ $ sudo apt-get install gawk git make python3 lld bison clang flex \
libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \ libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
graphviz xdot 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 **NOTE**: By default, Ubuntu 22.04 LTS is limited to CMake 3.22 via `apt`. To
run one of the following to override it: install a newer version and meet the minimum required for building Yosys, use
`sudo snap install cmake --classic`.
$ make config-clang CMake is used for build configuration, and requires a separate build directory:
$ make config-gcc
The Makefile has many variables influencing the build process. These can be $ cmake -B build .
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:
$ 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 $ ccmake build #..or..
changes to the config section of the Makefile. It's also an alternative way to $ vi build/CMakeCache.txt
set the make variables mentioned above.
$ vi Makefile # ..or.. When setting one-off variables, CMake provides the `-D <var>=<value>` command
$ vi Makefile.conf line option. For example, disabling zlib support:
To build Yosys simply type 'make' in this directory. $ cmake -B build . -DYOSYS_WITHOUT_ZLIB=ON
$ make For a more persistent configuration, we recommend creating and using a
$ sudo make install `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. target. Note that you need gawk, a recent version of iverilog, and gtest.
Execute tests via: Execute tests via:
$ make test $ cmake --build build --target test --parallel $(nproc)
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.
Getting Started 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 synthesis scripts or with command line arguments. Let's perform
a simple synthesis job using the interactive command shell: a simple synthesis job using the interactive command shell:
$ ./yosys $ ./build/yosys
yosys> yosys>
the command ``help`` can be used to print a list of all available 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: Or for MacOS, using homebrew:
$ brew install pdf2svg libfaketime $ brew install pdf2svg libfaketime
PDFLaTeX, included with most LaTeX distributions, is also needed during the PDFLaTeX, included with most LaTeX distributions, is also needed during the
build process for the website. Or, run the following: 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: Or for MacOS, using homebrew:
$ brew install basictex $ brew install basictex
$ sudo tlmgr update --self $ sudo tlmgr update --self
$ sudo tlmgr install collection-latexextra latexmk tex-gyre $ sudo tlmgr install collection-latexextra latexmk tex-gyre
The Python package, Sphinx, is needed along with those listed in The Python package, Sphinx, is needed along with those listed in
`docs/source/requirements.txt`: `docs/source/requirements.txt`:
$ pip install -U sphinx -r 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 DOCS (e.g.)
as necessary before generating the website documentation from the yosys help
commands. To build for pdf instead of html, call $ cmake --build build --target docs-html --parallel
`make docs DOC_TARGET=latexpdf`.
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() # else() #
message(FATAL_ERROR message(FATAL_ERROR
"${CMAKE_SOURCE_DIR} is not configured as a git repository, and 'abc' folder is missing.\n" "${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" "Otherwise, download release archive 'yosys.tar.gz' from https://github.com/YosysHQ/yosys/releases.\n"
" ('Source code' archive does not contain submodules.)\n" " ('Source code' archive does not contain submodules.)\n"
) )

10
docs/Makefile
View file

@ -265,15 +265,15 @@ extract:
@mkdir -p source/generated/functional @mkdir -p source/generated/functional
@cp ../backends/functional/smtlib.cc 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 > 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_SMTBMC) --help >source/generated/yosys-smtbmc
@$(YOSYS_WITNESS) --help >source/generated/yosys-witness @$(YOSYS_WITNESS) --help >source/generated/yosys-witness
@$(YOSYS_CONFIG) --help >source/generated/yosys-config @$(YOSYS_CONFIG) --help | sed "s%$(YOSYS_CONFIG)%$(PROGRAM_PREFIX)yosys-config%g" - >source/generated/yosys-config
@$(YOSYS_FILTERLIB) --help 2>source/generated/yosys-filterlib || true @$(YOSYS_FILTERLIB) --help 2>&1 >/dev/null | sed "s%filterlib%$(PROGRAM_PREFIX)yosys-filterlib%g" - >source/generated/yosys-filterlib
@$(ABC) --help 2>source/generated/yosys-abc > /dev/null || true @$(ABC) --help 2>&1 >/dev/null | sed "s%$(ABC)%$(PROGRAM_PREFIX)yosys-abc%g" - >source/generated/yosys-abc
.PHONY: gen .PHONY: gen
gen: gen:

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

@ -14,8 +14,9 @@ Yosys environment variables
Used for storing temporary files. Used for storing temporary files.
``ABC`` ``ABC``
When compiling Yosys with out-of-tree ABC using :makevar:`ABCEXTERNAL`, this When compiling Yosys with out-of-tree ABC using
variable can be used to override the external ABC executable. :makevar:`YOSYS_ABC_EXECUTABLE`, this variable can be used to override the
external ABC executable.
``YOSYS_NOVERIFIC`` ``YOSYS_NOVERIFIC``
If Yosys was built with Verific, this environment variable can be used to 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 .PHONY: all dots examples
all: dots examples all: dots examples
dots: dots:
examples: examples: test
.PHONY: test .PHONY: test
test: stubnets.so test: stubnets.so
@$(YOSYS) -ql test1.log -m ./stubnets.so test.v -p "stubnets" >/dev/null 2>&1 @$(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 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 @$(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 stubnets.so: stubnets.cc
@$(YOSYS_CONFIG) --exec --cxx --cxxflags --ldflags -o $@ -shared $^ --ldlibs >/dev/null 2>&1 @$(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 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 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 Supported platforms
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
@ -88,10 +88,10 @@ Build prerequisites
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
A C++ compiler with C++20 support is required as well as some standard tools 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 such as GNU Flex, GNU Bison (>=3.8), CMake (>=3.27), Make (or other CMake
tools: readline, libffi, Tcl and zlib; are optional but enabled by default (see generator such as Ninja), and Python (>=3.11). Some additional tools: readline,
:makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the libffi, Tcl and zlib; will be used if available but are optional. Graphviz and
`show` command to display schematics. Xdot are used by the `show` command to display schematics.
Installing all prerequisites: Installing all prerequisites:
@ -102,7 +102,15 @@ Installing all prerequisites:
sudo apt-get install gawk git make python3 lld bison clang flex \ sudo apt-get install gawk git make python3 lld bison clang flex \
libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \ libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
graphviz xdot 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) .. tab:: macOS 13 (with Homebrew)
@ -114,19 +122,16 @@ Installing all prerequisites:
.. code:: console .. 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 pkgconfig python311 zlib tcl
.. tab:: FreeBSD .. tab:: FreeBSD
.. code:: console .. code:: console
pkg install bison flex readline gawk libffi graphviz \ pkg install bison cmake-core flex readline gawk libffi graphviz \
pkgconf python311 tcl-wrapper 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 .. tab:: Cygwin
Use the following command to install all prerequisites, or select these Use the following command to install all prerequisites, or select these
@ -134,7 +139,7 @@ Installing all prerequisites:
.. code:: console .. 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:: .. warning::
@ -142,7 +147,7 @@ Installing all prerequisites:
minimum required version of Python is 3.11. This means that Cygwin is not 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 compatible with many of the Python-based frontends. While this does not
currently prevent Yosys itself from working, no guarantees are made for 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 resolve missing ``strdup`` function when using gcc. It is instead
recommended to use Windows Subsystem for Linux (WSL) and follow the recommended to use Windows Subsystem for Linux (WSL) and follow the
instructions for Ubuntu. instructions for Ubuntu.
@ -168,71 +173,86 @@ Installing all prerequisites:
Build configuration Build configuration
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
The Yosys build is based solely on Makefiles, and uses a number of variables The Yosys build is configured via CMake, and uses a number of variables which
which influence the build process. The recommended method for configuring influence the build process. When setting one-off variables, CMake provides the
builds is with a ``Makefile.conf`` file in the root ``yosys`` directory. The ``-D <var>=<value>`` command line option. For example, disabling zlib support:
following commands will clean the directory and provide an initial configuration
file:
.. code:: console .. code:: console
make config-clang # ..or.. cmake -B build . -DYOSYS_WITHOUT_ZLIB=ON
make config-gcc
Check the root Makefile to see what other configuration targets are available. .. warning::
Other variables can then be added to the ``Makefile.conf`` as needed, for
example: 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 .. code:: console
echo "ENABLE_ZLIB := 0" >> Makefile.conf ccmake build #..or..
vi build/CMakeCache.txt
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.
If you have clang, and (a compatible version of) ``ld.lld`` available in PATH, 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 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 ``CMAKE_INTERPROCEDURAL_OPTIMIZATION=ON``. On macOS, LTO requires using clang
clang from xcode. For example: from homebrew rather than clang from xcode. For example:
.. code:: console .. 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 using :program:`yosys-abc` as the executable name. To use an existing ABC
executable instead, set the ``ABCEXTERNAL`` make variable to point to the executable instead, set the :makevar:`YOSYS_ABC_EXECUTABLE` CMake variable to
desired executable. point to the desired executable.
Running the build system 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 .. code:: console
make cmake -B build . -DCMAKE_BUILD_TYPE=Release --fresh
sudo make install 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 .. code:: console
mkdir build; cd build cmake -B build .
make -f ../Makefile ccmake build # modify configuration
cmake --build build
Out-of-tree builds require a clean source tree.
.. seealso:: .. seealso::
@ -248,6 +268,9 @@ directories:
``backends/`` ``backends/``
This directory contains a subdirectory for each of the backend modules. This directory contains a subdirectory for each of the backend modules.
``cmake/``
Additional ``.cmake`` files used by CMake during build generation.
``docs/`` ``docs/``
Contains the source for this documentation, including images and sample code. 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 example as of this writing the directory :file:`passes/hierarchy/` contains
the code for three passes: `hierarchy`, `submod`, and `uniquify`. the code for three passes: `hierarchy`, `submod`, and `uniquify`.
``pyosys/``
Contains the scripts and wrappers necessary for building :doc:`Pyosys
</using_yosys/pyosys>`.
``techlibs/`` ``techlibs/``
This directory contains simulation models and standard implementations for This directory contains simulation models and standard implementations for
the cells from the internal cell library. 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 This directory contains the suite of unit tests and regression tests used by
Yosys. See :doc:`/yosys_internals/extending_yosys/test_suites`. Yosys. See :doc:`/yosys_internals/extending_yosys/test_suites`.
The top-level Makefile includes :file:`frontends/{*}/Makefile.inc`, .. TODO:: CMAKE_TODO
: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.
Good starting points for reading example source code to learn how to write - ``yosys_<pass|test_pass|frontend|backend>(<name>)`` for each pass
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 - see :file:`cmake/YosysComponent.cmake`
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 - if using a sub folder, add it to the parent's ``CMakeLists.txt`` with
CDT plugin has been installed) to create an Eclipse project in order to ``add_subdirectory(<name>)``
programming extensions to Yosys or just browse the Yosys code base.
- 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 Scripting with Pyosys
===================== =====================
.. TODO:: document libyosys sans python
Pyosys is a limited subset of the Yosys C++ API (aka "libyosys") made available Pyosys is a limited subset of the Yosys C++ API (aka "libyosys") made available
using the Python programming language. 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 Yosys API to implement advanced functionality that would otherwise require
custom passes written in C++. 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 Getting Pyosys
-------------- --------------
@ -21,7 +30,7 @@ Getting Pyosys
Pyosys supports CPython 3.8 or higher. You can access Pyosys using one of two Pyosys supports CPython 3.8 or higher. You can access Pyosys using one of two
methods: 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 This adds the flag ``-y`` to the Yosys binary, which allows you to execute
Python scripts using an interpreter embedded in Yosys itself: Python scripts using an interpreter embedded in Yosys itself:
@ -29,12 +38,9 @@ methods:
``yosys -y ./my_pyosys_script.py`` ``yosys -y ./my_pyosys_script.py``
Do note this requires some build-time dependencies to be available to Python, Do note this requires some build-time dependencies to be available to Python,
namely, ``pybind11`` and ``cxxheaderparser``. By default, the required namely, ``pybind11`` and ``cxxheaderparser``. :program:`uv` may be used to
``uv`` package will be used to create an ephemeral environment with the create an ephemeral environment with the correct versions of the tools
correct versions of the tools installed. installed if the current python environment doesn't provide them.
You can force use of your current Python environment by passing the Makefile
flag ``PYOSYS_USE_UV=0``.
2. Installing the Pyosys wheels 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 Compile options
--------------- ---------------
To enable Verific support ``ENABLE_VERIFIC`` has to be set to ``1`` and To enable Verific support, set the :makevar:`YOSYS_VERIFIC_DIR` CMake variable
``VERIFIC_DIR`` needs to point to the location where the library is located. to point to the location where the library is located, e.g.
============== ========================== =============================== .. code-block:: console
Parameter Default Description
============== ========================== ===============================
ENABLE_VERIFIC 0 Enable compilation with Verific
VERIFIC_DIR /usr/local/src/verific_lib Library and headers location
============== ========================== ===============================
Since there are multiple Verific library builds and they can have different cmake -B build . -DYOSYS_VERIFIC_DIR="/usr/local/src/verific_lib"
features, there are compile options to select them.
================================= ======= =================================== During building, CMake will attempt to automatically detect available Verific
Parameter Default Description library components to enable the corresponding compile-time option in Yosys.
================================= ======= =================================== This can be overridden by manually setting the :makevar:`YOSYS_VERIFIC_FEATURES`
ENABLE_VERIFIC_SYSTEMVERILOG 1 SystemVerilog support CMake variable. This variable should contain a semi-colon separated list, e.g.
ENABLE_VERIFIC_VHDL 1 VHDL support ``-DYOSYS_VERIFIC_FEATURES="systemverilog;hier_tree"``. The table below lists
ENABLE_VERIFIC_HIER_TREE 1 Hierarchy tree support the features available to Yosys.
ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS 0 YosysHQ specific extensions support
ENABLE_VERIFIC_EDIF 0 EDIF support
ENABLE_VERIFIC_LIBERTY 0 Liberty file support
================================= ======= ===================================
To find the compile options used for a given Yosys build, call ``yosys-config ============== =========== ===================================
--cxxflags``. This documentation was built with the following compile options: Feature Directory Description
============== =========== ===================================
.. literalinclude:: /generated/yosys-config systemverilog verilog SystemVerilog support
:start-at: --cxxflags vhdl vhdl VHDL support
:end-before: --linkflags hier_tree hier_tree Hierarchy tree support
extensions extensions YosysHQ specific extensions support
edif edif EDIF support
liberty synlib Liberty file support
============== =========== ===================================
.. note:: .. note::
@ -82,11 +76,10 @@ are required for the Yosys-Verific patch:
* RTL elaboration with * RTL elaboration with
* SystemVerilog with ``ENABLE_VERIFIC_SYSTEMVERILOG``, and/or * SystemVerilog with ``systemverilog``, and/or
* VHDL support with ``ENABLE_VERIFIC_VHDL``. * VHDL support with ``vhdl``.
* Hierarchy tree support and static elaboration with * Hierarchy tree support and static elaboration with ``hier_tree``.
``ENABLE_VERIFIC_HIER_TREE``.
Please be aware that the following Verific configuration build parameter needs Please be aware that the following Verific configuration build parameter needs
to be enabled in order to create the fully supported build: 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 Optional Verific features
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
The following Verific features are available with TabbyCAD and can be enabled in The following Verific features are available with TabbyCAD and will be
Yosys builds: automatically enabled in Yosys builds if the listed directory is included in the
:makevar:`YOSYS_VERIFIC_DIR`:
* EDIF support with ``ENABLE_VERIFIC_EDIF``, and * EDIF support with ``edif`` directory, and
* Liberty file support with ``ENABLE_VERIFIC_LIBERTY``. * Liberty file support with ``synlib`` directory.
Partially supported builds 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 limited subset of features. Please note that support is limited without YosysHQ
specific extensions of Verific library. specific extensions of Verific library.
Configuration values: ======================================================================= =================================
a. ``ENABLE_VERIFIC_SYSTEMVERILOG`` Features :makevar:`YOSYS_VERIFIC_FEATURES`
b. ``ENABLE_VERIFIC_VHDL`` ======================================================================= =================================
c. ``ENABLE_VERIFIC_HIER_TREE`` SystemVerilog + RTL elaboration systemverilog
d. ``ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS`` VHDL + RTL elaboration vhdl
SystemVerilog + VHDL + RTL elaboration systemverilog;vhdl
+--------------------------------------------------------------------------+-----+-----+-----+-----+ SystemVerilog + RTL elaboration + Static elaboration + Hier tree systemverilog;vhdl;hier_tree
| | Configuration values | VHDL + RTL elaboration + Static elaboration + Hier tree vhdl;hier_tree
+--------------------------------------------------------------------------+-----+-----+-----+-----+ SystemVerilog + VHDL + RTL elaboration + Static elaboration + Hier tree systemverilog;vhdl;hier_tree
| 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 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
.. note:: .. note::
In case your Verific build has EDIF and/or Liberty support, you can enable 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 those options. These are not mentioned above for simplification.
they are disabled by default.

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 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 everything working as expected. Tests can be run by building the ``test``
the root Yosys directory. By default, this runs vanilla and unit tests. 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 Vanilla tests
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
These make up the majority of our testing coverage. .. TODO:: update for test infra changes
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.
Usually their structure looks something like this: These make up the majority of our testing coverage. They can be run with the
you write a .ys file that gets automatically run, ``test-vanilla`` CMake target. Usually their structure looks something like
which runs a frontend like ``read_verilog`` or ``read_rtlil`` with this: you write a .ys file that gets automatically run, which runs a frontend
a relative path or a heredoc, then runs some commands including the command like ``read_verilog`` or ``read_rtlil`` with a relative path or a heredoc, then
under test, and then uses :doc:`/using_yosys/more_scripting/selections` runs some commands including the command under test, and then uses
with ``-assert-count``. Usually it's unnecessary to "register" the test anywhere :doc:`/using_yosys/more_scripting/selections` with ``-assert-count``. Usually
as if it's being added to an existing directory, depending it's unnecessary to "register" the test anywhere as if it's being added to an
on how the ``run-test.sh`` in that directory works. existing directory, depending on how the ``run-test.sh`` in that directory
works.
Unit tests Unit tests
~~~~~~~~~~ ~~~~~~~~~~
@ -45,7 +46,7 @@ Running the unit tests requires the following additional packages:
No additional requirements. 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 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 installed, you should also install Z3 `following their
instructions <https://github.com/Z3Prover/z3>`_. instructions <https://github.com/Z3Prover/z3>`_.
Then, set the :makevar:`ENABLE_FUNCTIONAL_TESTS` make variable when calling .. TODO:: CMAKE_TODO
``make test`` and the functional tests will be run as well.
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 Docs tests
~~~~~~~~~~ ~~~~~~~~~~
There are some additional tests for checking examples included in the There are some additional tests for checking examples included in the
documentation, which can be run by calling ``make test`` from the documentation, which can be run with the ``test-docs`` CMake target. This also
:file:`yosys/docs` sub-directory (or ``make -C docs test`` from the root). This includes checking some macro commands to ensure that descriptions of them are
also includes checking some macro commands to ensure that descriptions of them kept up to date, and is mostly intended for CI.
are kept up to date, and is mostly intended for CI.
Automatic testing Automatic testing

37
kernel/register.cc
View file

@ -28,6 +28,7 @@
#include <stdlib.h> #include <stdlib.h>
#include <stdio.h> #include <stdio.h>
#include <errno.h> #include <errno.h>
#include <filesystem>
YOSYS_NAMESPACE_BEGIN YOSYS_NAMESPACE_BEGIN
@ -772,6 +773,10 @@ struct HelpPass : public Pass {
bool raise_error = false; bool raise_error = false;
std::map<string, vector<string>> groups; 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(); json.name("cmds"); json.begin_object();
// iterate over commands // iterate over commands
for (auto &it : pass_register) { 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 // attempt auto group
if (!cmd_help.has_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) if (pass->internal_flag)
cmd_help.group = "internal"; cmd_help.group = "internal";
else if (source_file.find("backends/") == 0 || (!has_source && name.find("read_") == 0)) 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)) else if (source_file.find("frontends/") == 0 || (!has_source && name.find("write_") == 0))
cmd_help.group = "frontends"; cmd_help.group = "frontends";
else if (has_source) { else if (has_source) {
auto last_slash = source_file.find_last_of('/'); if (source_path.has_parent_path() && !no_source_group)
if (last_slash != string::npos) { cmd_help.group = source_path.parent_path().string();
auto parent_path = source_file.substr(0, last_slash);
cmd_help.group = parent_path;
}
} }
// implicit !has_source // implicit !has_source
else if (name.find("equiv") == 0) else if (name.find("equiv") == 0)
@ -955,7 +976,7 @@ struct HelpPass : public Pass {
json.value(content.to_json()); json.value(content.to_json());
json.end_array(); json.end_array();
json.entry("group", cmd_help.group); 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_line", pass->location.line());
json.entry("source_func", pass->location.function_name()); json.entry("source_func", pass->location.function_name());
json.entry("experimental_flag", pass->experimental_flag); json.entry("experimental_flag", pass->experimental_flag);