diff --git a/.gitignore b/.gitignore index 84d11a7cb..bf680feff 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ ## user config /Makefile.conf +/Configuration.cmake ## homebrew /Brewfile.lock.json diff --git a/README.md b/README.md index df65a6a10..9ac0812d9 100644 --- a/README.md +++ b/README.md @@ -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, 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,50 @@ 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, build variables can be inspected and modified with: -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 +one-off options with -To build Yosys simply type 'make' in this directory. + $ cmake -B build . --fresh \ + -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ - $ make - $ sudo make install +set persistent options with -Tests are located in the tests subdirectory and can be executed using the test + $ vi Configuration.cmake # ..then.. + $ cmake -C Configuration.cmake -B build . --fresh + +e.g. + + set(CMAKE_C_COMPILER clang CACHE STRING "") + set(CMAKE_CXX_COMPILER clang++ CACHE STRING "") + +ALSO + + $ cmake -G Ninja -B build . + +INSTALL + + $ 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 +140,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 +262,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 +271,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. diff --git a/cmake/YosysAbcSubmodule.cmake b/cmake/YosysAbcSubmodule.cmake index 2a648a7e0..742580513 100644 --- a/cmake/YosysAbcSubmodule.cmake +++ b/cmake/YosysAbcSubmodule.cmake @@ -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' make 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" ) diff --git a/docs/source/appendix/env_vars.rst b/docs/source/appendix/env_vars.rst index 69e86c922..7e10fad86 100644 --- a/docs/source/appendix/env_vars.rst +++ b/docs/source/appendix/env_vars.rst @@ -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 diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index 2a90a8071..02aec2023 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -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) @@ -127,6 +135,10 @@ Installing all prerequisites: .. note:: On FreeBSD system use gmake instead of make. To run tests use: ``MAKE=gmake CXX=cxx CC=cc gmake test`` + .. TODO:: CMAKE_TODO + + Is this still required, and (how) does it work with CMake + .. tab:: Cygwin Use the following command to install all prerequisites, or select these @@ -134,7 +146,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 +154,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,52 +180,53 @@ 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. + +set one-off options with .. code:: console - make config-clang # ..or.. - make config-gcc + cmake -B build . --fresh \ + -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -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: +set persistent options with .. code:: console - echo "ENABLE_ZLIB := 0" >> Makefile.conf + vi Configuration.cmake # ..then.. + cmake -C Configuration.cmake -B build . --fresh -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: +e.g. + +.. code:: cmake + + set(CMAKE_C_COMPILER clang CACHE STRING "") + set(CMAKE_CXX_COMPILER clang++ CACHE STRING "") + set(YOSYS_WITHOUT_ZLIB ON CACHE STRING "") + +Once generated, build variables can be inspected and modified with: .. 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`_, 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` make variable to point to +the desired executable. Running the build system ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -222,17 +235,12 @@ From the root ``yosys`` directory, call the following commands: .. code:: console - make - sudo make install + cmake -B build . -DCMAKE_BUILD_TYPE=Release + 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. - -.. code:: console - - mkdir build; cd build - make -f ../Makefile - -Out-of-tree builds require a clean source tree. +Note that Yosys does not support in-tree builds, and if calling ``cmake`` from +the root ``yosys`` directory the ``-B`` option must be provided. .. seealso:: @@ -248,6 +256,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 +292,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 + `. + ``techlibs/`` This directory contains simulation models and standard implementations for the cells from the internal cell library. @@ -289,19 +304,28 @@ 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_()`` 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()`` + + 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. + + 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. diff --git a/docs/source/using_yosys/pyosys.rst b/docs/source/using_yosys/pyosys.rst index 09b572e05..a0ea0a993 100644 --- a/docs/source/using_yosys/pyosys.rst +++ b/docs/source/using_yosys/pyosys.rst @@ -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 ``uv`` for managing python environments: + + .. code:: console + + curl -LsSf https://astral.sh/uv/install.sh | sh Getting Pyosys -------------- @@ -21,7 +30,11 @@ 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`` +.. TODO:: CMAKE_TODO + + may still be pending further changes + +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 +42,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``. If available, ``uv`` will be + used to create an ephemeral environment with the correct versions of the + tools installed. 2. Installing the Pyosys wheels diff --git a/docs/source/yosys_internals/extending_yosys/build_verific.rst b/docs/source/yosys_internals/extending_yosys/build_verific.rst index 2585ebae4..5ea491e1b 100644 --- a/docs/source/yosys_internals/extending_yosys/build_verific.rst +++ b/docs/source/yosys_internals/extending_yosys/build_verific.rst @@ -39,36 +39,36 @@ 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: +============== =========== =================================== +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 +============== =========== =================================== -.. literalinclude:: /generated/yosys-config - :start-at: --cxxflags - :end-before: --linkflags +.. TODO:: CMAKE_TODO + + ``yosys-config --cxxflags`` no longer includes the verific features, and the + CMakeCache.txt doesn't report auto detected :makevar:`YOSYS_VERIFIC_FEATURES` + - can we export these somehow? .. note:: @@ -82,11 +82,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 +104,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 +124,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. diff --git a/docs/source/yosys_internals/extending_yosys/test_suites.rst b/docs/source/yosys_internals/extending_yosys/test_suites.rst index d3422b23a..e33dc4836 100644 --- a/docs/source/yosys_internals/extending_yosys/test_suites.rst +++ b/docs/source/yosys_internals/extending_yosys/test_suites.rst @@ -7,19 +7,32 @@ 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) + +.. TODO:: CMAKE_TODO + + Using ``make -C `` does work, but only if using default + :makevar:`BUILD_DIR` (``build``) and :makevar:`PROGRAM_PREFIX` (none). 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 + +These make up the majority of our testing coverage. They can be run with the +``test-vanilla`` CMake target, or by calling ``make vanilla-test`` from the +``tests`` directory, 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: you write a .ys file that gets automatically run, @@ -45,7 +58,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,12 +88,20 @@ If you don't have one of the :ref:`getting_started/installation:CAD suite(s)` installed, you should also install Z3 `following their instructions `_. +.. TODO:: CMAKE_TODO + + How does this work under CMake? Is it only via ``make -C tests ENABLE_FUNCTIONAL_TESTS=1`` + Then, set the :makevar:`ENABLE_FUNCTIONAL_TESTS` make variable when calling ``make test`` and the functional tests will be run as well. Docs tests ~~~~~~~~~~ +.. TODO:: CMAKE_TODO + + Is this available via CMake? + 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