diff --git a/.gitignore b/.gitignore index 84d11a7cb..bb1a08bba 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ ## user config /Makefile.conf +/Configuration.cmake +/CMakeUserPresets.json ## homebrew /Brewfile.lock.json diff --git a/CMakeLists.txt b/CMakeLists.txt index 287631547..3deacd232 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -500,10 +500,10 @@ set(makefile_vars PROGRAM_PREFIX=${YOSYS_PROGRAM_PREFIX} ABC=$,$,${YOSYS_ABC_EXECUTABLE}> YOSYS=$ - YOSYS_CONFIG=${CMAKE_BINARY_DIR}/yosys-config + YOSYS_CONFIG=${CMAKE_BINARY_DIR}/${YOSYS_PROGRAM_PREFIX}yosys-config 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 $ @@ -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. diff --git a/README.md b/README.md index df65a6a10..f8b3dfa4f 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 (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 =` 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. diff --git a/cmake/YosysAbcSubmodule.cmake b/cmake/YosysAbcSubmodule.cmake index 2a648a7e0..ee0dcb4c3 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' 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" ) diff --git a/docs/Makefile b/docs/Makefile index 63ccd9b49..ce32dd723 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -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: 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/code_examples/stubnets/Makefile b/docs/source/code_examples/stubnets/Makefile index 324fdff6b..cefaf36ce 100644 --- a/docs/source/code_examples/stubnets/Makefile +++ b/docs/source/code_examples/stubnets/Makefile @@ -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 diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index 2a90a8071..691731fbf 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -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 =`` 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 + `. + ``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_()`` 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()`` + + - 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. diff --git a/docs/source/using_yosys/pyosys.rst b/docs/source/using_yosys/pyosys.rst index 09b572e05..b059516e1 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 :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 diff --git a/docs/source/yosys_internals/extending_yosys/build_verific.rst b/docs/source/yosys_internals/extending_yosys/build_verific.rst index 2585ebae4..b9ecd352e 100644 --- a/docs/source/yosys_internals/extending_yosys/build_verific.rst +++ b/docs/source/yosys_internals/extending_yosys/build_verific.rst @@ -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. diff --git a/docs/source/yosys_internals/extending_yosys/test_suites.rst b/docs/source/yosys_internals/extending_yosys/test_suites.rst index d3422b23a..2342c505d 100644 --- a/docs/source/yosys_internals/extending_yosys/test_suites.rst +++ b/docs/source/yosys_internals/extending_yosys/test_suites.rst @@ -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 `_. -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 diff --git a/kernel/register.cc b/kernel/register.cc index 705ec628a..a88d2acc8 100644 --- a/kernel/register.cc +++ b/kernel/register.cc @@ -28,6 +28,7 @@ #include #include #include +#include YOSYS_NAMESPACE_BEGIN @@ -772,6 +773,10 @@ struct HelpPass : public Pass { bool raise_error = false; std::map> 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);