From fdc4511f186e11748db29113db200001085bdb0a Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Thu, 14 May 2026 17:54:34 -0400 Subject: [PATCH 1/3] Tutorial: Fix some typos --- Help/guide/tutorial/Finding Dependencies.rst | 4 ++-- Help/guide/tutorial/Getting Started with CMake.rst | 2 +- Help/guide/tutorial/Installation Commands and Concepts.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Help/guide/tutorial/Finding Dependencies.rst b/Help/guide/tutorial/Finding Dependencies.rst index 0ad3abcd34..d38021c75b 100644 --- a/Help/guide/tutorial/Finding Dependencies.rst +++ b/Help/guide/tutorial/Finding Dependencies.rst @@ -142,7 +142,7 @@ Build and Run ------------- First we must install the ``SimpleTest`` framework. Navigate to the -``Help/guide/Step10/SimpleTest`` directory and run the following commands +``Help/guide/Step10/SimpleTest`` directory and run the following commands. .. code-block:: console @@ -191,7 +191,7 @@ We do this with ``REQUIRED`` because the tests cannot build without -Next we add the ``SimpleTest::SimpleTest`` target to ``TestMathFunctions`` +Next we add the ``SimpleTest::SimpleTest`` target to ``TestMathFunctions``. .. raw:: html diff --git a/Help/guide/tutorial/Getting Started with CMake.rst b/Help/guide/tutorial/Getting Started with CMake.rst index 19c811d124..7f492f03b1 100644 --- a/Help/guide/tutorial/Getting Started with CMake.rst +++ b/Help/guide/tutorial/Getting Started with CMake.rst @@ -449,7 +449,7 @@ executable. Next we need to describe the source files. For the implementation file, -``MathFunctions.cxx``, this is straight-forward; for the header file +``MathFunctions.cxx``, this is straightforward; for the header file ``MathFunctions.h`` we will need to use a ``FILE_SET``. We can either give this ``FILE_SET`` its own name, or use the shortcut of naming diff --git a/Help/guide/tutorial/Installation Commands and Concepts.rst b/Help/guide/tutorial/Installation Commands and Concepts.rst index c2422a5865..8d797b2c22 100644 --- a/Help/guide/tutorial/Installation Commands and Concepts.rst +++ b/Help/guide/tutorial/Installation Commands and Concepts.rst @@ -471,7 +471,7 @@ When importing CMake targets from a target export file, there is no way to incompatible version for the one we requested, we'll be stuck with any side-effects incurred while we learned that version information. -The answer CMake provides for this problem is a light-weight version file which +The answer CMake provides for this problem is a lightweight version file which only describes this version compatibility information, which can be checked before CMake commits to fully importing the file. From 653356bed0e5f80a20b3401ca9e9d576ed2d9689 Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Thu, 14 May 2026 18:11:41 -0400 Subject: [PATCH 2/3] Tutorial: Describe install prefix Give a brief overview of what the install prefix is and the various ways it can be set. --- .../Installation Commands and Concepts.rst | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Help/guide/tutorial/Installation Commands and Concepts.rst b/Help/guide/tutorial/Installation Commands and Concepts.rst index 8d797b2c22..914b65b8a4 100644 --- a/Help/guide/tutorial/Installation Commands and Concepts.rst +++ b/Help/guide/tutorial/Installation Commands and Concepts.rst @@ -66,6 +66,27 @@ to unless instructed to do otherwise. For example, ``RUNTIME`` will be installed to the location named by :module:`CMAKE_INSTALL_BINDIR `, if the variable is available, otherwise they default to ``bin``. +Just like we use :option:`cmake -B` to control what build directory will be +used by CMake, we have a variety of options for telling CMake where to install +things. This location is generally referred to as the install prefix. To +set this at configure time, so that every :option:`cmake --install` performed +using that build tree defaults to a given prefix, we can use any of: + +* the :option:`cmake --install-prefix` option; +* the :ref:`installDir ` field in CMake presets; or +* the :variable:`CMAKE_INSTALL_PREFIX` variable. + +.. note:: + We have discouraged setting ``CMAKE_`` variables inside the project. Setting + :variable:`CMAKE_INSTALL_PREFIX` is *particularly* bad practice without very + good reasoning for doing so, since it prevents users from ever overriding it. + When providing a default, projects should check + :variable:`CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT`. + +Alternatively, we can use the +:option:`cmake --install --prefix ` option to set the +install prefix for a single install invocation. + The full list of artifact kind default destinations is described in the following table. @@ -140,6 +161,8 @@ Helpful Resources ----------------- * :command:`install` +* :option:`cmake --install-prefix` +* :option:`cmake --install --prefix ` Files to Edit ------------- From 4b093ae12eae69a50c2ca4f09f35eb283a69fa8c Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Thu, 14 May 2026 18:14:43 -0400 Subject: [PATCH 3/3] Tutorial: Move multi-config install note to the first exercise The context is needed when running all exercises in this step. Revise both this note and its mirror for `ctest` in Step 7 to cross-reference the relevant flags. --- .../Installation Commands and Concepts.rst | 17 ++++++++--------- Help/guide/tutorial/Testing and CTest.rst | 9 ++++----- 2 files changed, 12 insertions(+), 14 deletions(-) diff --git a/Help/guide/tutorial/Installation Commands and Concepts.rst b/Help/guide/tutorial/Installation Commands and Concepts.rst index 914b65b8a4..bc78718e64 100644 --- a/Help/guide/tutorial/Installation Commands and Concepts.rst +++ b/Help/guide/tutorial/Installation Commands and Concepts.rst @@ -187,6 +187,14 @@ No special configuration is needed, configure and build as usual. We can verify the installation is correct with :option:`cmake --install`. +.. note:: + + As with CTest, when using a multi-config generator such as Visual Studio, it + will be necessary to specify a configuration like ``Debug`` or ``Release`` + using :option:`cmake --install --config `. + This is true whenever using a multi-config generator, and won't be called out + specifically in future commands. + .. code-block:: console cmake --install build --prefix install @@ -352,15 +360,6 @@ The build command is sufficient to reconfigure the project. We can verify the installation is correct with :option:`cmake --install`. -.. note:: - - As with CTest, when using multi-config generator, eg Visual Studio, it will be - necessary to specify a configuration with - ``cmake --install --config ``, where - ```` is a value like ``Debug`` or ``Release``. This is true whenever - using a multi-config generator, and won't be called out specifically in - future commands. - .. code-block:: console cmake --install build --prefix install diff --git a/Help/guide/tutorial/Testing and CTest.rst b/Help/guide/tutorial/Testing and CTest.rst index 360b3838de..df4ffdc71a 100644 --- a/Help/guide/tutorial/Testing and CTest.rst +++ b/Help/guide/tutorial/Testing and CTest.rst @@ -117,11 +117,10 @@ Verify all the tests pass with CTest. .. note:: - If using a multi-config generator, eg Visual Studio, it will be necessary to - specify a configuration with ``ctest -C ``, where - ```` is a value like ``Debug`` or ``Release``. This is true whenever - using a multi-config generator, and won't be called out specifically in - future commands. + When using a multi-config generator such as Visual Studio, it + will be necessary to specify a configuration like ``Debug`` or ``Release`` + using :option:`ctest -C`. This is true whenever using a multi-config + generator, and won't be called out specifically in future commands. .. code-block:: console