From 776995c74dbeff1226be5bcc0d7c835fb6620e1f Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 2 Jun 2026 15:45:00 +1200
Subject: [PATCH 1/8] WIP docs

---
 .gitignore                                    |   1 +
 README.md                                     |  96 ++++++------
 cmake/YosysAbcSubmodule.cmake                 |   2 +-
 docs/source/appendix/env_vars.rst             |   5 +-
 docs/source/getting_started/installation.rst  | 138 ++++++++++--------
 docs/source/using_yosys/pyosys.rst            |  24 ++-
 .../extending_yosys/build_verific.rst         | 102 ++++++-------
 .../extending_yosys/test_suites.rst           |  41 ++++--
 8 files changed, 227 insertions(+), 182 deletions(-)

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
+   </using_yosys/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_<pass|test_pass|frontend|backend>(<name>)`` for each pass
 
-Users of the Qt Creator IDE can generate a QT Creator project file using make
-qtcreator. Users of the Eclipse IDE can use the "Makefile Project with Existing
-Code" project type in the Eclipse "New Project" dialog (only available after the
-CDT plugin has been installed) to create an Eclipse project in order to
-programming extensions to Yosys or just browse the Yosys code base.
+      - see :file:`cmake/YosysComponent.cmake`
+
+   - if using a sub folder, add it to the parent's ``CMakeLists.txt`` with
+     ``add_subdirectory(<name>)``
+
+   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 <docs|tests>`` 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 <https://github.com/Z3Prover/z3>`_.
 
+.. 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

From 1bef4261240e1e49e5ff630f930d1f54c17b0a11 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 2 Jun 2026 15:42:54 +1200
Subject: [PATCH 2/8] docs: Run stubnets with docs tests

---
 docs/source/code_examples/stubnets/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/code_examples/stubnets/Makefile b/docs/source/code_examples/stubnets/Makefile
index 324fdff6b..334daead0 100644
--- a/docs/source/code_examples/stubnets/Makefile
+++ b/docs/source/code_examples/stubnets/Makefile
@@ -3,7 +3,7 @@ include ../../../common.mk
 .PHONY: all dots examples
 all: dots examples
 dots:
-examples:
+examples: test
 
 .PHONY: test
 test: stubnets.so

From 7c24b69e62790c82a2dda858fbaa50847fc42ada Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Wed, 3 Jun 2026 11:32:06 +1200
Subject: [PATCH 3/8] register.cc: Make cmd paths proximate

The CMake refactor changes relative paths to absolute when calling `source_location::current()`.  Use the path to `register.cc` to find the root yosys dir, and use that as the base for other paths.
Includes provisions for when plugins have a valid location; if it's not in the yosys source tree we shouldn't try to make the path relative, and we shouldn't try to auto group by path (since such groups will never be allocated, leaving them as unknown is preferable).
Limited to non wasm (I think that's the only one where we can't (easily) use `<filesystem>`). But where we do use `<filesystem>` we can also simplify the auto group to use `fs::path::parent_path()`.
---
 kernel/register.cc | 42 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/kernel/register.cc b/kernel/register.cc
index 705ec628a..bfb442dae 100644
--- a/kernel/register.cc
+++ b/kernel/register.cc
@@ -29,6 +29,11 @@
 #include <stdio.h>
 #include <errno.h>
 
+#if !defined(__wasm)
+#include <filesystem>
+namespace fs = std::filesystem;
+#endif
+
 YOSYS_NAMESPACE_BEGIN
 
 #define MAX_REG_COUNT 1000
@@ -772,6 +777,11 @@ struct HelpPass : public Pass {
 		bool raise_error = false;
 		std::map<string, vector<string>> groups;
 
+#if !defined(__wasm)
+		auto this_path = fs::path(source_location::current().file_name());
+		auto source_root = this_path.parent_path().parent_path();
+#endif
+
 		json.name("cmds"); json.begin_object();
 		// iterate over commands
 		for (auto &it : pass_register) {
@@ -912,10 +922,31 @@ struct HelpPass : public Pass {
 				}
 			}
 
+			string source_file = pass->location.file_name();
+			bool has_source = source_file.compare("unknown") != 0;
+#if !defined(__wasm)
+			// fix path 
+			fs::path source_path;
+			auto no_source_group = false;
+			if (has_source) {
+				source_path = fs::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 = fs::proximate(source_path, source_root);
+					if (proximate_path == fs::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();
+			}
+#endif
+
 			// 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 +954,16 @@ 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) {
+#if !defined(__wasm)
+					if (source_path.has_parent_path() && !no_source_group)
+						cmd_help.group = source_path.parent_path();
+#else
 					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;
 					}
+#endif
 				}
 				// implicit !has_source
 				else if (name.find("equiv") == 0)
@@ -955,7 +991,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);

From 042dbe593d7efe71f4eb39688d1f66b908925d35 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Wed, 3 Jun 2026 12:00:19 +1200
Subject: [PATCH 4/8] docs: Remove build dir from tool help

Pipes the help through sed for the tools that include the path.  Also means we can drop the `|| true` from abc, since we're now reading the sed return instead.
---
 docs/Makefile | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 63ccd9b49..948404a79 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%$(BUILD_DIR)/yosys%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_CONFIG) --help | sed "s%$(BUILD_DIR)/yosys-config%yosys-config%g" - >source/generated/yosys-config
 	@$(YOSYS_FILTERLIB) --help 2>source/generated/yosys-filterlib || true
-	@$(ABC) --help 2>source/generated/yosys-abc > /dev/null || true
+	@$(ABC) --help 2>&1 >/dev/null | sed "s%$(BUILD_DIR)/yosys-abc%yosys-abc%g" - >source/generated/yosys-abc
 
 .PHONY: gen
 gen:

From 2889c733382fd9b38ac4c64dc39351f8aeea7252 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Wed, 3 Jun 2026 16:40:17 +1200
Subject: [PATCH 5/8] Tidy up install instructions

Fill out sentences, move things around a little, switch from recommending `Configuration.cmake` to `CMakeUserPresets.json`.
---
 .gitignore                                   |  1 +
 README.md                                    | 52 ++++++++++------
 docs/source/getting_started/installation.rst | 62 ++++++++++++--------
 3 files changed, 73 insertions(+), 42 deletions(-)

diff --git a/.gitignore b/.gitignore
index bf680feff..bb1a08bba 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
 ## user config
 /Makefile.conf
 /Configuration.cmake
+/CMakeUserPresets.json
 
 ## homebrew
 /Brewfile.lock.json
diff --git a/README.md b/README.md
index 9ac0812d9..9a3e45388 100644
--- a/README.md
+++ b/README.md
@@ -76,10 +76,10 @@ or
 	$ git submodule update --init --recursive
 
 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.
+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:
@@ -96,31 +96,45 @@ CMake is used for build configuration, and requires a separate build directory:
 
 	$ cmake -B build .
 
-Once generated, build variables can be inspected and modified with:
+Once generated, available build variables can be inspected and modified with
+`ccmake` or opening the generated `build/CMakeCache.txt` file:
 
 	$ ccmake build              #..or..
 	$ vi build/CMakeCache.txt
 
-one-off options with
+When setting one-off variables, CMake provides the `-D <var>=<value>` command line
+option. For example, disabling zlib support:
 
-	$ cmake -B build . --fresh \
-		-DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
+	$ cmake -B build . -DYOSYS_WITHOUT_ZLIB=ON
 
-set persistent options with
+For a more persistent configuration, we recommend creating and using a
+`CMakeUserPresets.json` file. Below is an example file which sets the default
+compiler to clang when calling `cmake --preset clang`:
 
-	$ vi Configuration.cmake     # ..then..
-	$ cmake -C Configuration.cmake -B build . --fresh
+```json
+{
+	"version": 1,
+	"configurePresets": [
+		{
+			"name": "clang",
+			"binaryDir": "build",
+			"generator": "Unix Makefiles",
+			"cacheVariables": {
+				"CMAKE_C_COMPILER": "clang",
+				"CMAKE_CXX_COMPILER": "clang++"
+			}
+		}
+	]
+}
+```
 
-e.g.
+Once generated, the build system can be run as follows:
 
-	set(CMAKE_C_COMPILER clang CACHE STRING "")
-	set(CMAKE_CXX_COMPILER clang++ CACHE STRING "")
+	$ cmake --build build       #..or..
+	$ cd build
+	$ cmake --build .
 
-ALSO
-
-	$ cmake -G Ninja -B build .
-
-INSTALL
+To quickly install Yosys with the default settings:
 
 	$ cmake -B build . -DCMAKE_BUILD_TYPE=Release
 	$ cmake --build build --config Release --parallel $(nproc)
diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst
index 02aec2023..60dcd09ea 100644
--- a/docs/source/getting_started/installation.rst
+++ b/docs/source/getting_started/installation.rst
@@ -180,32 +180,42 @@ Installing all prerequisites:
 Build configuration
 ^^^^^^^^^^^^^^^^^^^
 
-The Yosys build is configured via CMake, and uses a number of variables
-which influence the build process.
-
-set one-off options with
+The Yosys build is configured via CMake, and uses a number of variables which
+influence the build process.  When setting one-off variables, CMake provides the
+``-D <var>=<value>`` command line option. For example, disabling zlib support:
 
 .. code:: console
 
-   cmake -B build . --fresh \
-      -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
+   cmake -B build . -DYOSYS_WITHOUT_ZLIB=ON
 
-set persistent options with
+.. warning::
 
-.. code:: console
+   Yosys does not support in-tree builds. If calling ``cmake`` from the root
+   ``yosys`` directory the ``-B`` option must be provided.
 
-   vi Configuration.cmake     # ..then..
-   cmake -C Configuration.cmake -B build . --fresh
+For a more persistent configuration, we recommend creating and using a
+``CMakeUserPresets.json`` file. Below is an example file which sets the default
+compiler to clang when calling ``cmake --preset clang``:
 
-e.g.
+.. code:: json
 
-.. code:: cmake
+   {
+      "version": 1,
+      "configurePresets": [
+         {
+            "name": "clang",
+            "binaryDir": "build",
+            "generator": "Unix Makefiles",
+            "cacheVariables": {
+               "CMAKE_C_COMPILER": "clang",
+               "CMAKE_CXX_COMPILER": "clang++"
+            }
+         }
+      ]
+   }
 
-   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:
+Once generated, available build variables can be inspected and modified with
+``ccmake`` or opening the generated ``build/CMakeCache.txt`` file:
 
 .. code:: console
 
@@ -225,22 +235,28 @@ from homebrew rather than clang from xcode.  For example:
 
 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 :makevar:`YOSYS_ABC_EXECUTABLE` 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
 
-   cmake -B build . -DCMAKE_BUILD_TYPE=Release
+   cmake -B build . -DCMAKE_BUILD_TYPE=Release --fresh
    cmake --build build --config Release --parallel $(nproc)
    sudo cmake --install build --strip
 
-Note that Yosys does not support in-tree builds, and if calling ``cmake`` from
-the root ``yosys`` directory the ``-B`` option must be provided.
+To use an existing configuration, use the ``--build`` option, e.g:
+
+.. code:: console
+
+   cmake -B build .
+   ccmake build              # modify configuration
+   cmake --build build
 
 .. seealso::
 

From e1931596ae8b3fe95897316c91eb2aae3e5ca96a Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Wed, 3 Jun 2026 16:53:25 +1200
Subject: [PATCH 6/8] CMake: Add wrapper for test-docs

Also skip calling `tail` on stubnets log outputs.

Fix auxprog prefixes

i.e. if we've set `YOSYS_PROGRAM_PREFIX=why`, we shouldn't be trying to call `build/yosys` when building docs (because if we've done a clean build it doesn't exist).
I suspect this also affects tests, but I was working on docs when I noticed it.
---
 CMakeLists.txt                              | 11 ++++++++---
 docs/Makefile                               |  8 ++++----
 docs/source/code_examples/stubnets/Makefile |  1 -
 3 files changed, 12 insertions(+), 8 deletions(-)

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=$<IF:$<TARGET_EXISTS:yosys-abc>,$<TARGET_FILE:yosys-abc>,${YOSYS_ABC_EXECUTABLE}>
 	YOSYS=$<TARGET_FILE:yosys>
-	YOSYS_CONFIG=${CMAKE_BINARY_DIR}/yosys-config
+	YOSYS_CONFIG=${CMAKE_BINARY_DIR}/${YOSYS_PROGRAM_PREFIX}yosys-config
 	YOSYS_FILTERLIB=$<$<TARGET_EXISTS:yosys-filterlib>:$<TARGET_FILE:yosys-filterlib>>
-	YOSYS_SMTBMC=${CMAKE_BINARY_DIR}/yosys-smtbmc
-	YOSYS_WITNESS=${CMAKE_BINARY_DIR}/yosys-witness
+	YOSYS_SMTBMC=${CMAKE_BINARY_DIR}/${YOSYS_PROGRAM_PREFIX}yosys-smtbmc
+	YOSYS_WITNESS=${CMAKE_BINARY_DIR}/${YOSYS_PROGRAM_PREFIX}yosys-witness
 )
 set(makefile_depends
 	# abc is implied via $<TARGET_FILE>
@@ -545,6 +545,11 @@ if (NOT YOSYS_BUILD_PYTHON_ONLY)
 			DEPENDS docs-prepare
 		)
 	endforeach()
+	add_custom_target(test-docs
+		COMMAND make test ${makefile_vars}
+		WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/docs
+		DEPENDS ${makefile_depends}
+	)
 endif()
 
 # Utilities.
diff --git a/docs/Makefile b/docs/Makefile
index 948404a79..ce32dd723 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -268,12 +268,12 @@ extract:
 	@cd .. && diff -U 20 backends/functional/smtlib.cc backends/functional/smtlib_rosette.cc \
 		> docs/source/generated/functional/rosette.diff || true
 
-	$(YOSYS) --help | sed "s%$(BUILD_DIR)/yosys%yosys%g" - >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 | sed "s%$(BUILD_DIR)/yosys-config%yosys-config%g" - >source/generated/yosys-config
-	@$(YOSYS_FILTERLIB) --help 2>source/generated/yosys-filterlib || true
-	@$(ABC) --help 2>&1 >/dev/null | sed "s%$(BUILD_DIR)/yosys-abc%yosys-abc%g" - >source/generated/yosys-abc
+	@$(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/code_examples/stubnets/Makefile b/docs/source/code_examples/stubnets/Makefile
index 334daead0..cefaf36ce 100644
--- a/docs/source/code_examples/stubnets/Makefile
+++ b/docs/source/code_examples/stubnets/Makefile
@@ -10,7 +10,6 @@ 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

From 72f5836fb180b96d5c6e6c25d719676a2639f9c0 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Wed, 3 Jun 2026 17:30:38 +1200
Subject: [PATCH 7/8] docs: Resolving todos

Make explicit the location for the `CMakeUserPresets.json` file.
Update docs tests documentation.
Move `BUILD_DIR` and `PROGRAM_PREFIX` comments into the functional tests todo.
Add cmake to MacPorts/FreeBSD install instructions.
Add ccache to example `CMakeUserPresets.json` (it isn't otherwise documented, and is no longer as obvious without an `ENABLE_CCACHE` makevar).

Addressing comments
---
 README.md                                     | 14 +++---
 cmake/YosysAbcSubmodule.cmake                 |  2 +-
 docs/source/getting_started/installation.rst  | 42 +++++++---------
 docs/source/using_yosys/pyosys.rst            | 12 ++---
 .../extending_yosys/build_verific.rst         |  6 ---
 .../extending_yosys/test_suites.rst           | 48 +++++++------------
 kernel/register.cc                            | 29 +++--------
 7 files changed, 55 insertions(+), 98 deletions(-)

diff --git a/README.md b/README.md
index 9a3e45388..f8b3dfa4f 100644
--- a/README.md
+++ b/README.md
@@ -102,26 +102,28 @@ Once generated, available build variables can be inspected and modified with
 	$ ccmake build              #..or..
 	$ vi build/CMakeCache.txt
 
-When setting one-off variables, CMake provides the `-D <var>=<value>` command line
-option. For example, disabling zlib support:
+When setting one-off variables, CMake provides the `-D <var>=<value>` command
+line option. For example, disabling zlib support:
 
 	$ cmake -B build . -DYOSYS_WITHOUT_ZLIB=ON
 
 For a more persistent configuration, we recommend creating and using a
-`CMakeUserPresets.json` file. Below is an example file which sets the default
-compiler to clang when calling `cmake --preset clang`:
+`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`:
 
 ```json
 {
 	"version": 1,
 	"configurePresets": [
 		{
-			"name": "clang",
+			"name": "default",
 			"binaryDir": "build",
 			"generator": "Unix Makefiles",
 			"cacheVariables": {
 				"CMAKE_C_COMPILER": "clang",
-				"CMAKE_CXX_COMPILER": "clang++"
+				"CMAKE_CXX_COMPILER": "clang++",
+				"YOSYS_COMPILER_LAUNCHER": "ccache"
 			}
 		}
 	]
diff --git a/cmake/YosysAbcSubmodule.cmake b/cmake/YosysAbcSubmodule.cmake
index 742580513..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 'YOSYS_ABC_EXECUTABLE' 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/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst
index 60dcd09ea..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
 ^^^^^^^^^^^^^^^^^^^
@@ -122,23 +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``
-
-   .. 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
@@ -190,32 +183,35 @@ influence the build process.  When setting one-off variables, CMake provides the
 
 .. warning::
 
-   Yosys does not support in-tree builds. If calling ``cmake`` from the root
-   ``yosys`` directory the ``-B`` option must be provided.
+   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. Below is an example file which sets the default
-compiler to clang when calling ``cmake --preset clang``:
+``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:: json
+.. code-block:: json
+   :caption: CMakeUserPresets.json
 
    {
       "version": 1,
       "configurePresets": [
          {
-            "name": "clang",
+            "name": "default",
             "binaryDir": "build",
             "generator": "Unix Makefiles",
             "cacheVariables": {
                "CMAKE_C_COMPILER": "clang",
-               "CMAKE_CXX_COMPILER": "clang++"
+               "CMAKE_CXX_COMPILER": "clang++",
+               "YOSYS_COMPILER_LAUNCHER": "ccache"
             }
          }
       ]
    }
 
 Once generated, available build variables can be inspected and modified with
-``ccmake`` or opening the generated ``build/CMakeCache.txt`` file:
+:program:`ccmake` or opening the generated ``build/CMakeCache.txt`` file:
 
 .. code:: console
 
@@ -233,7 +229,7 @@ from homebrew rather than clang from xcode.  For example:
       -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 :makevar:`YOSYS_ABC_EXECUTABLE` CMake variable to
 point to the desired executable.
@@ -329,11 +325,9 @@ directories:
    - if using a sub folder, add it to the parent's ``CMakeLists.txt`` with
      ``add_subdirectory(<name>)``
 
-   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
+   - 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.
 
diff --git a/docs/source/using_yosys/pyosys.rst b/docs/source/using_yosys/pyosys.rst
index a0ea0a993..b059516e1 100644
--- a/docs/source/using_yosys/pyosys.rst
+++ b/docs/source/using_yosys/pyosys.rst
@@ -18,7 +18,7 @@ custom passes written in C++.
 
 .. note::
 
-   It is recommended to install ``uv`` for managing python environments:
+   It is recommended to install :program:`uv` for managing python environments:
 
    .. code:: console
 
@@ -30,10 +30,6 @@ Getting Pyosys
 Pyosys supports CPython 3.8 or higher. You can access Pyosys using one of two
 methods:
 
-.. 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
@@ -42,9 +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``. If available, ``uv`` will be
-   used to create an ephemeral environment with the correct versions of the
-   tools installed.
+   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 5ea491e1b..b9ecd352e 100644
--- a/docs/source/yosys_internals/extending_yosys/build_verific.rst
+++ b/docs/source/yosys_internals/extending_yosys/build_verific.rst
@@ -64,12 +64,6 @@ edif           edif        EDIF support
 liberty        synlib      Liberty file support
 ============== =========== ===================================
 
-.. 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::
 
    The YosysHQ specific extensions are only available with the TabbyCAD suite.
diff --git a/docs/source/yosys_internals/extending_yosys/test_suites.rst b/docs/source/yosys_internals/extending_yosys/test_suites.rst
index e33dc4836..2342c505d 100644
--- a/docs/source/yosys_internals/extending_yosys/test_suites.rst
+++ b/docs/source/yosys_internals/extending_yosys/test_suites.rst
@@ -16,32 +16,20 @@ tests.
    cmake -B build .
    cmake --build build --target test --parallel $(nproc)
 
-.. TODO:: CMAKE_TODO
-
-   Using ``make -C <docs|tests>`` does work, but only if using default
-   :makevar:`BUILD_DIR` (``build``) and :makevar:`PROGRAM_PREFIX` (none).
-
 Vanilla tests
 ~~~~~~~~~~~~~
 
 .. 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,
-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.
+``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
 ~~~~~~~~~~
@@ -90,23 +78,21 @@ instructions <https://github.com/Z3Prover/z3>`_.
 
 .. TODO:: CMAKE_TODO
 
-   How does this work under CMake?  Is it only via ``make -C tests ENABLE_FUNCTIONAL_TESTS=1``
+   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.
+   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
-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 bfb442dae..004650ff2 100644
--- a/kernel/register.cc
+++ b/kernel/register.cc
@@ -28,11 +28,7 @@
 #include <stdlib.h>
 #include <stdio.h>
 #include <errno.h>
-
-#if !defined(__wasm)
 #include <filesystem>
-namespace fs = std::filesystem;
-#endif
 
 YOSYS_NAMESPACE_BEGIN
 
@@ -777,10 +773,9 @@ struct HelpPass : public Pass {
 		bool raise_error = false;
 		std::map<string, vector<string>> groups;
 
-#if !defined(__wasm)
-		auto this_path = fs::path(source_location::current().file_name());
+		// get root path
+		auto this_path = std::filesystem::path(source_location::current().file_name());
 		auto source_root = this_path.parent_path().parent_path();
-#endif
 
 		json.name("cmds"); json.begin_object();
 		// iterate over commands
@@ -922,19 +917,18 @@ struct HelpPass : public Pass {
 				}
 			}
 
+			// fix path
 			string source_file = pass->location.file_name();
 			bool has_source = source_file.compare("unknown") != 0;
-#if !defined(__wasm)
-			// fix path 
-			fs::path source_path;
+			std::filesystem::path source_path;
 			auto no_source_group = false;
 			if (has_source) {
-				source_path = fs::path(pass->location.file_name());
+				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 = fs::proximate(source_path, source_root);
-					if (proximate_path == fs::weakly_canonical(proximate_path))
+					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
@@ -943,7 +937,6 @@ struct HelpPass : public Pass {
 				}
 				source_file = source_path.string();
 			}
-#endif
 
 			// attempt auto group
 			if (!cmd_help.has_group()) {
@@ -954,16 +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) {
-#if !defined(__wasm)
 					if (source_path.has_parent_path() && !no_source_group)
 						cmd_help.group = source_path.parent_path();
-#else
-					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;
-					}
-#endif
 				}
 				// implicit !has_source
 				else if (name.find("equiv") == 0)

From 58f44a1c1bee0a8e102ba8d2057db6b26b9ff0f6 Mon Sep 17 00:00:00 2001
From: Miodrag Milanovic <mmicko@gmail.com>
Date: Thu, 4 Jun 2026 12:25:41 +0200
Subject: [PATCH 8/8] Fix compile with VisualStudio

---
 kernel/register.cc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/kernel/register.cc b/kernel/register.cc
index 004650ff2..a88d2acc8 100644
--- a/kernel/register.cc
+++ b/kernel/register.cc
@@ -948,7 +948,7 @@ struct HelpPass : public Pass {
 					cmd_help.group = "frontends";
 				else if (has_source) {
 					if (source_path.has_parent_path() && !no_source_group)
-						cmd_help.group = source_path.parent_path();
+						cmd_help.group = source_path.parent_path().string();
 				}
 				// implicit !has_source
 				else if (name.find("equiv") == 0)