Tidy up install instructions

Fill out sentences, move things around a little, switch from recommending `Configuration.cmake` to `CMakeUserPresets.json`.

.gitignore

@@ -1,6 +1,7 @@
 ## user config
 /Makefile.conf
 /Configuration.cmake
+/CMakeUserPresets.json
 
 ## homebrew
 /Brewfile.lock.json

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).
+such as GNU Flex, GNU Bison (>=3.8), CMake (>=3.27), Make (or other CMake
-Some additional tools: readline, libffi, Tcl and zlib; will be used if available
+generator such as Ninja), and Python (>=3.11). Some additional tools: readline,
-but are optional. Graphviz and Xdot are used by the `show` command to display
+libffi, Tcl and zlib; will be used if available but are optional. Graphviz and
-schematics.
+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 \
+	$ cmake -B build . -DYOSYS_WITHOUT_ZLIB=ON
-		-DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
 
-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..
+```json
-	$ cmake -C Configuration.cmake -B build . --fresh
+{
+	"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 "")
+	$ cmake --build build       #..or..
-	set(CMAKE_CXX_COMPILER clang++ CACHE STRING "")
+	$ cd build
+	$ cmake --build .
 
-ALSO
+To quickly install Yosys with the default settings:
-
-	$ cmake -G Ninja -B build .
-
-INSTALL
 
 	$ cmake -B build . -DCMAKE_BUILD_TYPE=Release
 	$ cmake --build build --config Release --parallel $(nproc)

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
+The Yosys build is configured via CMake, and uses a number of variables which
-which influence the build process.
+influence the build process.  When setting one-off variables, CMake provides the
-
+``-D <var>=<value>`` command line option. For example, disabling zlib support:
-set one-off options with
 
 .. code:: console
 
-   cmake -B build . --fresh \
+   cmake -B build . -DYOSYS_WITHOUT_ZLIB=ON
-      -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
 
-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..
+For a more persistent configuration, we recommend creating and using a
-   cmake -C Configuration.cmake -B build . --fresh
+``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 "")
+Once generated, available build variables can be inspected and modified with
-   set(CMAKE_CXX_COMPILER clang++ CACHE STRING "")
+``ccmake`` or opening the generated ``build/CMakeCache.txt`` file:
-   set(YOSYS_WITHOUT_ZLIB ON CACHE STRING "")
-
-Once generated, build variables can be inspected and modified with:
 
 .. 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
+executable instead, set the :makevar:`YOSYS_ABC_EXECUTABLE` CMake variable to
-the desired executable.
+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
+To use an existing configuration, use the ``--build`` option, e.g:
-the root ``yosys`` directory the ``-B`` option must be provided.
+
+.. code:: console
+
+   cmake -B build .
+   ccmake build              # modify configuration
+   cmake --build build
 
 .. seealso::