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] 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 =` 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 =`` 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::