diff options
Diffstat (limited to 'Help')
38 files changed, 466 insertions, 350 deletions
diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 0a33da3..7a3393b 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -17,7 +17,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. [EXCLUDE_FIXTURE_SETUP <regex>] [EXCLUDE_FIXTURE_CLEANUP <regex>] [PARALLEL_LEVEL <level>] - [HARDWARE_SPEC_FILE <file>] + [RESOURCE_SPEC_FILE <file>] [TEST_LOAD <threshold>] [SCHEDULE_RANDOM <ON|OFF>] [STOP_TIME <time-of-day>] @@ -83,10 +83,10 @@ The options are: Specify a positive number representing the number of tests to be run in parallel. -``HARDWARE_SPEC_FILE <file>`` +``RESOURCE_SPEC_FILE <file>`` Specify a - :ref:`hardware specification file <ctest-hardware-specification-file>`. See - :ref:`ctest-hardware-allocation` for more information. + :ref:`resource specification file <ctest-resource-specification-file>`. See + :ref:`ctest-resource-allocation` for more information. ``TEST_LOAD <threshold>`` While running tests in parallel, try not to start tests when they diff --git a/Help/command/file.rst b/Help/command/file.rst index 83e4516..b186177 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -187,14 +187,14 @@ The arguments are as follows: are typically created with :command:`add_executable`, but they do not have to be created by CMake. On Apple platforms, the paths to these files determine the value of ``@executable_path`` when recursively resolving the libraries. - Specifying ``STATIC`` libraries, ``MODULE`` s, or ``SHARED`` libraries here + Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here will result in undefined behavior. ``LIBRARIES <library_files>`` List of library files to read for dependencies. These are libraries that are typically created with :command:`add_library(SHARED)`, but they do not have - to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` s, or - executables here will result in undefined behavior. + to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` + libraries, or executables here will result in undefined behavior. ``MODULES <module_files>`` List of loadable module files to read for dependencies. These are modules @@ -209,13 +209,13 @@ The arguments are as follows: platforms, these directories are searched if the dependency is not found in any of the other usual paths. If it is found in such a directory, a warning is issued, because it means that the file is incomplete (it does not list all - of the directories that contain its dependencies.) On Windows platforms, + of the directories that contain its dependencies). On Windows platforms, these directories are searched if the dependency is not found in any of the other search paths, but no warning is issued, because searching other paths is a normal part of Windows dependency resolution. On Apple platforms, this argument has no effect. -``BUNDLE_EXECTUBLE <bundle_executable_file>`` +``BUNDLE_EXECUTABLE <bundle_executable_file>`` Executable to treat as the "bundle executable" when resolving libraries. On Apple platforms, this argument determines the value of ``@executable_path`` when recursively resolving libraries for ``LIBRARIES`` and ``MODULES`` files. @@ -284,7 +284,7 @@ On Linux platforms, library resolution works as follows: dependency is resolved to that file. In this case, a warning is issued, because finding a file in one of the ``DIRECTORIES`` means that the depending file is not complete (it does not list all the directories from - which it pulls dependencies.) + which it pulls dependencies). 5. Otherwise, the dependency is unresolved. On Windows platforms, library resolution works as follows: @@ -331,8 +331,8 @@ On Windows platforms, library resolution works as follows: dependency is resolved to that file. 5. Otherwise, if the library exists in one of the directories specified by ``DIRECTORIES``, in the order they are listed, the dependency is resolved to - that file. (In this case, a warning is not issued, because searching other - directories is a normal part of Windows library resolution.) + that file. In this case, a warning is not issued, because searching other + directories is a normal part of Windows library resolution. 6. Otherwise, the dependency is unresolved. On Apple platforms, library resolution works as follows: @@ -350,9 +350,9 @@ On Apple platforms, library resolution works as follows: existing file, the dependency is resolved to that file. 4. Otherwise, if the dependency starts with ``@rpath/``, and replacing ``@rpath/`` with one of the ``RPATH`` entries of the depending file yields - an existing file, the dependency is resolved to that file. (Note that + an existing file, the dependency is resolved to that file. Note that ``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/`` - also have these items replaced with the appropriate path.) + also have these items replaced with the appropriate path. 5. Otherwise, if the dependency is an absolute file that exists, the dependency is resolved to that file. 6. Otherwise, the dependency is unresolved. diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 546b00f..64a16f3 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -353,8 +353,10 @@ enabled. 8. Search paths stored in the CMake :ref:`System Package Registry`. This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed - or by setting the + or by setting the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` + variable to ``FALSE`` or the deprecated variable :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``. + See the :manual:`cmake-packages(7)` manual for details on the system package registry. diff --git a/Help/command/list.rst b/Help/command/list.rst index 39e7e2a..50bf417 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -180,7 +180,7 @@ Insert elements to the 0th position in the list. list(REMOVE_ITEM <list> <value> [<value> ...]) -Removes the given items from the list. +Removes all instances of the given items from the list. .. _REMOVE_AT: diff --git a/Help/command/load_cache.rst b/Help/command/load_cache.rst index 33625c4..b89eb61 100644 --- a/Help/command/load_cache.rst +++ b/Help/command/load_cache.rst @@ -5,7 +5,7 @@ Load in the values from another project's CMake cache. .. code-block:: cmake - load_cache(pathToCacheFile READ_WITH_PREFIX prefix entry1...) + load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...) Reads the cache and store the requested entries in variables with their name prefixed with the given prefix. This only reads the values, and @@ -13,7 +13,7 @@ does not create entries in the local project's cache. .. code-block:: cmake - load_cache(pathToCacheFile [EXCLUDE entry1...] + load_cache(pathToBuildDirectory [EXCLUDE entry1...] [INCLUDE_INTERNALS entry1...]) Loads in the values from another cache and store them in the local diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst index d283948..5ab3766 100644 --- a/Help/command/target_precompile_headers.rst +++ b/Help/command/target_precompile_headers.rst @@ -79,6 +79,17 @@ must be available for the compiler to find them. Other header file names source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be included by absolute path. +When specifying angle brackets inside a :manual:`generator expression +<cmake-generator-expressions(7)>`, be sure to encode the closing ``>`` +as ``$<ANGLE-R>``. For example: + +.. code-block:: cmake + + target_precompile_headers(mylib PRIVATE + "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>" + "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>" + ) + See Also ^^^^^^^^ diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 37a1d3a..44e2273 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -279,10 +279,11 @@ Push the update to the ``master`` and ``release`` branches: Announce 'release' Branch ------------------------- -Send email to the ``cmake-developers@cmake.org`` mailing list (perhaps -in reply to a release preparation thread) announcing that post-release -development is open:: +Post a topic to the `CMake Discourse Forum Development Category`_ +announcing that post-release development is open:: - I've branched 'release' for $ver. The repository is now open for - post-$ver development. Please rebase open merge requests on 'master' + I've branched `release` for $ver. The repository is now open for + post-$ver development. Please rebase open merge requests on `master` before staging or merging. + +.. _`CMake Discourse Forum Development Category`: https://discourse.cmake.org/c/development diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index d858c25..3f20aa2 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -18,9 +18,9 @@ A Basic Starting Point (Step 1) =============================== The most basic project is an executable built from source code files. -For simple projects, a three line CMakeLists file is all that is required. -This will be the starting point for our tutorial. Create a ``CMakeLists.txt`` -file in the ``Step1`` directory that looks like: +For simple projects, a three line ``CMakeLists.txt`` file is all that is +required. This will be the starting point for our tutorial. Create a +``CMakeLists.txt`` file in the ``Step1`` directory that looks like: .. code-block:: cmake @@ -33,7 +33,7 @@ file in the ``Step1`` directory that looks like: add_executable(Tutorial tutorial.cxx) -Note that this example uses lower case commands in the CMakeLists file. +Note that this example uses lower case commands in the ``CMakeLists.txt`` file. Upper, lower, and mixed case commands are supported by CMake. The source code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be used to compute the square root of a number. @@ -43,9 +43,9 @@ Adding a Version Number and Configured Header File The first feature we will add is to provide our executable and project with a version number. While we could do this exclusively in the source code, using -CMakeLists provides more flexibility. +``CMakeLists.txt`` provides more flexibility. -First, modify the CMakeLists file to set the version number. +First, modify the ``CMakeLists.txt`` file to set the version number. .. literalinclude:: Step2/CMakeLists.txt :language: cmake @@ -61,7 +61,7 @@ code: Since the configured file will be written into the binary tree, we must add that directory to the list of paths to search for include -files. Add the following lines to the end of the CMakeLists file: +files. Add the following lines to the end of the ``CMakeLists.txt`` file: .. literalinclude:: Step2/CMakeLists.txt :language: cmake @@ -103,8 +103,8 @@ Next let's add some C++11 features to our project by replacing ``atof`` with We will need to explicitly state in the CMake code that it should use the correct flags. The easiest way to enable support for a specific C++ standard in CMake is by using the ``CMAKE_CXX_STANDARD`` variable. For this tutorial, -set the ``CMAKE_CXX_STANDARD`` variable in the CMakeLists file to 11 and -``CMAKE_CXX_STANDARD_REQUIRED`` to True: +set the ``CMAKE_CXX_STANDARD`` variable in the ``CMakeLists.txt`` file to 11 +and ``CMAKE_CXX_STANDARD_REQUIRED`` to True: .. literalinclude:: Step2/CMakeLists.txt :language: cmake @@ -145,22 +145,22 @@ then use this library instead of the standard square root function provided by the compiler. For this tutorial we will put the library into a subdirectory -called MathFunctions. This directory already contains a header file, +called ``MathFunctions``. This directory already contains a header file, ``MathFunctions.h``, and a source file ``mysqrt.cxx``. The source file has one function called ``mysqrt`` that provides similar functionality to the compiler's ``sqrt`` function. -Add the following one line ``CMakeLists.txt`` file to the MathFunctions +Add the following one line ``CMakeLists.txt`` file to the ``MathFunctions`` directory: .. literalinclude:: Step3/MathFunctions/CMakeLists.txt :language: cmake To make use of the new library we will add an ``add_subdirectory`` call in the -top-level CMakeLists file so that the library will get built. We add the new -library to the executable, and add MathFunctions as an include directory so -that the ``mqsqrt.h`` header file can be found. The last few lines of the -top-level CMakeLists file should now look like: +top-level ``CMakeLists.txt`` file so that the library will get built. We add +the new library to the executable, and add ``MathFunctions`` as an include +directory so that the ``mqsqrt.h`` header file can be found. The last few lines +of the top-level ``CMakeLists.txt`` file should now look like: .. code-block:: cmake @@ -181,8 +181,8 @@ top-level CMakeLists file should now look like: Now let us make the MathFunctions library optional. While for the tutorial there really isn’t any need to do so, for larger projects this is a common -occurrence. The first step is to add an option to the top-level CMakeLists -file. +occurrence. The first step is to add an option to the top-level +``CMakeLists.txt`` file. .. literalinclude:: Step3/CMakeLists.txt :language: cmake @@ -195,8 +195,8 @@ the cache so that the user does not need to set the value each time they run CMake on a build directory. The next change is to make building and linking the MathFunctions library -conditional. To do this we change the end of the top-level CMakeLists file to -look like the following: +conditional. To do this we change the end of the top-level ``CMakeLists.txt`` +file to look like the following: .. literalinclude:: Step3/CMakeLists.txt :language: cmake @@ -209,15 +209,15 @@ classic approach when dealing with many optional components, we will cover the modern approach in the next step. The corresponding changes to the source code are fairly straightforward. First, -in ``tutorial.cxx``, include the MathFunctions header if we need it: +in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we need it: .. literalinclude:: Step3/tutorial.cxx :language: c++ :start-after: // should we include the MathFunctions header :end-before: int main -Then, in the same file, make which square root function is used dependent on -``USE_MYMATH``: +Then, in the same file, make ``USE_MYMATH`` control which square root +function is used: .. literalinclude:: Step3/tutorial.cxx :language: c++ @@ -268,7 +268,7 @@ doesn't. Add the following lines to the end of ``MathFunctions/CMakeLists.txt``: Now that we've specified usage requirements for MathFunctions we can safely remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level -CMakeLists, here: +``CMakeLists.txt``, here: .. literalinclude:: Step4/CMakeLists.txt :language: cmake @@ -330,9 +330,9 @@ Verify that the installed Tutorial runs. Testing Support --------------- -Next let's test our application. At the end of the top-level CMakeLists file we -can enable testing and then add a number of basic tests to verify that the -application is working correctly. +Next let's test our application. At the end of the top-level ``CMakeLists.txt`` +file we can enable testing and then add a number of basic tests to verify that +the application is working correctly. .. literalinclude:: Step5/CMakeLists.txt :language: cmake @@ -344,7 +344,7 @@ test. The next test makes use of the ``PASS_REGULAR_EXPRESSION`` test property to verify that the output of the test contains certain strings. In this case, -verifying that the the usage message is printed when an incorrect number of +verifying that the usage message is printed when an incorrect number of arguments are provided. Lastly, we have a function called ``do_test`` that runs the application and @@ -370,9 +370,9 @@ tutorial assume that they are not common. If the platform has ``log`` and ``exp`` then we will use them to compute the square root in the ``mysqrt`` function. We first test for the availability of -these functions using the ``CheckSymbolExists.cmake`` macro in the top-level -CMakeLists. We're going to use the new defines in ``TutorialConfig.h.in``, -so be sure to set them before that file is configured. +these functions using the ``CheckSymbolExists`` module in the top-level +``CMakeLists.txt``. We're going to use the new defines in +``TutorialConfig.h.in``, so be sure to set them before that file is configured. .. literalinclude:: Step6/MathFunctions/CMakeLists.txt :language: cmake @@ -405,9 +405,8 @@ You will notice that we're not using ``log`` and ``exp``, even if we think they should be available. We should realize quickly that we have forgotten to include ``TutorialConfig.h`` in ``mysqrt.cxx``. -We will also need to update MathFunctions/CMakeLists so ``mysqrt.cxx`` knows -where this file is located: - +We will also need to update ``MathFunctions/CMakeLists.txt`` so ``mysqrt.cxx`` +knows where this file is located: .. code-block:: cmake @@ -432,10 +431,10 @@ other than in ``TutorialConfig.h``? Let's try to use First, remove the defines from ``TutorialConfig.h.in``. We no longer need to include ``TutorialConfig.h`` from ``mysqrt.cxx`` or the extra include in -MathFunctions/CMakeLists. +``MathFunctions/CMakeLists.txt``. Next, we can move the check for ``HAVE_LOG`` and ``HAVE_EXP`` to -MathFunctions/CMakeLists and then add specify those values as ``PRIVATE`` +``MathFunctions/CMakeLists.txt`` and then specify those values as ``PRIVATE`` compile definitions. .. literalinclude:: Step6/MathFunctions/CMakeLists.txt @@ -444,7 +443,7 @@ compile definitions. :end-before: # install rules After making these updates, go ahead and build the project again. Run the -built Tutorial executable and verify that the results are same as earlier in +built Tutorial executable and verify that the results are same as earlier in this step. Adding a Custom Command and Generated File (Step 6) @@ -457,22 +456,23 @@ In this section, we will create the table as part of the build process, and then compile that table into our application. First, let's remove the check for the ``log`` and ``exp`` functions in -MathFunctions/CMakeLists. Then remove the check for ``HAVE_LOG`` and +``MathFunctions/CMakeLists.txt``. Then remove the check for ``HAVE_LOG`` and ``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove :code:`#include <cmath>`. -In the MathFunctions subdirectory, a new source file named ``MakeTable.cxx`` +In the ``MathFunctions`` subdirectory, a new source file named ``MakeTable.cxx`` has been provided to generate the table. After reviewing the file, we can see that the table is produced as valid C++ code and that the output filename is passed in as an argument. -The next step is to add the appropriate commands to MathFunctions CMakeLists -file to build the MakeTable executable and then run it as part of the build -process. A few commands are needed to accomplish this. +The next step is to add the appropriate commands to the +``MathFunctions/CMakeLists.txt`` file to build the MakeTable executable and +then run it as part of the build process. A few commands are needed to +accomplish this. -First, at the top of MathFunctions/CMakeLists, the executable for ``MakeTable`` -is added as any other executable would be added. +First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for +``MakeTable`` is added as any other executable would be added. .. literalinclude:: Step7/MathFunctions/CMakeLists.txt :language: cmake @@ -619,7 +619,7 @@ type must be specified:: Or, from an IDE, build the ``Experimental`` target. -Ctest will build and test the project and submit the results to the Kitware +``ctest`` will build and test the project and submit the results to the Kitware public dashboard. The results of your dashboard will be uploaded to Kitware's public dashboard here: https://my.cdash.org/index.php?project=CMakeTutorial. @@ -628,8 +628,8 @@ Mixing Static and Shared (Step 9) In this section we will show how by using the ``BUILD_SHARED_LIBS`` variable we can control the default behavior of ``add_library``, and allow control -over how libraries without an explicit type (STATIC/SHARED/MODULE/OBJECT) are -built. +over how libraries without an explicit type (``STATIC``, ``SHARED``, ``MODULE`` +or ``OBJECT``) are built. To accomplish this we need to add ``BUILD_SHARED_LIBS`` to the top-level ``CMakeLists.txt``. We use the ``option`` command as it allows users to @@ -678,10 +678,10 @@ Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: :language: c++ At this point, if you build everything, you will notice that linking fails -as we are combining a static library without position enabled code with a -library that has position enabled code. The solution to this is to explicitly -set the ``POSITION_INDEPENDENT_CODE`` target property of SqrtLibrary to be -True no matter the build type. +as we are combining a static library without position independent code with a +library that has position independent code. The solution to this is to +explicitly set the ``POSITION_INDEPENDENT_CODE`` target property of SqrtLibrary +to be True no matter the build type. .. literalinclude:: Step10/MathFunctions/CMakeLists.txt :language: cmake @@ -718,7 +718,7 @@ string, and ``<1:...>`` results in the content of "...". They can also be nested. A common usage of generator expressions is to conditionally add compiler -flags, such as those as language levels or warnings. A nice pattern is +flags, such as those for language levels or warnings. A nice pattern is to associate this information to an ``INTERFACE`` target allowing this information to propagate. Lets start by constructing an ``INTERFACE`` target and specifying the required C++ standard level of ``11`` instead @@ -816,19 +816,19 @@ directory and from an install / package. This means converting the :start-after: # to find MathFunctions.h, while we don't. :end-before: # should we use our own math functions -Once this has been updated, we can re-run CMake and see verify that it doesn't +Once this has been updated, we can re-run CMake and verify that it doesn't warn anymore. At this point, we have CMake properly packaging the target information that is required but we will still need to generate a ``MathFunctionsConfig.cmake`` so -that the CMake ``find_package command`` can find our project. So let's go +that the CMake ``find_package`` command can find our project. So let's go ahead and add a new file to the top-level of the project called ``Config.cmake.in`` with the following contents: .. literalinclude:: Complete/Config.cmake.in Then, to properly configure and install that file, add the following to the -bottom of the top-level CMakeLists: +bottom of the top-level ``CMakeLists.txt``: .. literalinclude:: Complete/CMakeLists.txt :language: cmake @@ -838,7 +838,7 @@ bottom of the top-level CMakeLists: At this point, we have generated a relocatable CMake Configuration for our project that can be used after the project has been installed or packaged. If we want our project to also be used from a build directory we only have to add -the following to the bottom of the top level CMakeLists: +the following to the bottom of the top level ``CMakeLists.txt``: .. literalinclude:: Complete/CMakeLists.txt :language: cmake @@ -851,7 +851,7 @@ other projects, without needing it to be installed. Import a CMake Project (Consumer) ================================= -This examples shows how a project can find other CMake packages that +This example shows how a project can find other CMake packages that generate ``Config.cmake`` files. It also shows how to state a project's external dependencies when generating @@ -860,22 +860,24 @@ a ``Config.cmake``. Packaging Debug and Release (MultiPackage) ========================================== -By default CMake is model is that a build directory only contains a single +By default CMake's model is that a build directory only contains a single configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. But it is possible to setup CPack to bundle multiple build directories at the same time to build a package that contains multiple configurations of the same project. -First we need to ahead and construct a directory called ``multi_config`` this +First we need to construct a directory called ``multi_config``, which will contain all the builds that we want to package together. Second create a ``debug`` and ``release`` directory underneath ``multi_config``. At the end you should have a layout that looks like: -─ multi_config - ├── debug - └── release +.. code-block:: none + + ─ multi_config + ├── debug + └── release Now we need to setup debug and release builds, which would roughly entail the following: @@ -891,8 +893,9 @@ the following: cd .. -Now that both the debug and release builds are complete we can now use -the custom MultiCPackConfig to package both builds into a single release. +Now that both the debug and release builds are complete, we can use +a custom ``MultiCPackConfig.cmake`` file to package both builds into a single +release. .. code-block:: console diff --git a/Help/manual/LINKS.txt b/Help/manual/LINKS.txt index 60a260c..810fa0b 100644 --- a/Help/manual/LINKS.txt +++ b/Help/manual/LINKS.txt @@ -11,11 +11,7 @@ Online Documentation and Community Resources Links to available documentation and community resources may be found on this web page. -Mailing List - https://cmake.org/mailing-lists +Discourse Forum + https://discourse.cmake.org - For help and discussion about using CMake, a mailing list is - provided at cmake@cmake.org. The list is member-post-only but one - may sign up on the CMake web page. Please first read the full - documentation at https://cmake.org before posting questions to - the list. + The Discourse Forum hosts discussion and questions about CMake. diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 658694a..a821189 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -90,21 +90,21 @@ Requiring Language Standards In projects that use a large number of commonly available features from a particular language standard (e.g. C++ 11) one may specify a meta-feature (e.g. ``cxx_std_11``) that requires use of a compiler mode -aware of that standard. This is simpler than specifying all the -features individually, but does not guarantee the existence of any -particular feature. Diagnosis of use of unsupported features will be -delayed until compile time. +that is at minimum aware of that standard, but could be greater. +This is simpler than specifying all the features individually, but does +not guarantee the existence of any particular feature. +Diagnosis of use of unsupported features will be delayed until compile time. For example, if C++ 11 features are used extensively in a project's -header files, then clients must use a compiler mode aware of C++ 11 -or above. This can be requested with the code: +header files, then clients must use a compiler mode that is no less +than C++ 11. This can be requested with the code: .. code-block:: cmake target_compile_features(mylib PUBLIC cxx_std_11) In this example, CMake will ensure the compiler is invoked in a mode -that is aware of C++ 11 (or above), adding flags such as +of at-least C++ 11 (or C++ 14, C++ 17, ...), adding flags such as ``-std=gnu++11`` if necessary. This applies to sources within ``mylib`` as well as any dependents (that may include headers from ``mylib``). @@ -331,12 +331,12 @@ and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 9.2. -* ``Clang``: Clang compiler versions 2.9 through 6.0. -* ``GNU``: GNU compiler versions 4.4 through 8.0. -* ``MSVC``: Microsoft Visual Studio versions 2010 through 2017. -* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.6. -* ``Intel``: Intel compiler versions 12.1 through 17.0. +* ``AppleClang``: Apple Clang for Xcode versions 4.4+. +* ``Clang``: Clang compiler versions 2.9+. +* ``GNU``: GNU compiler versions 4.4+. +* ``MSVC``: Microsoft Visual Studio versions 2010+. +* ``SunPro``: Oracle SolarisStudio versions 12.4+. +* ``Intel``: Intel compiler versions 12.1+. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and :prop_gbl:`compile features <CMAKE_C_KNOWN_FEATURES>` available from @@ -344,16 +344,16 @@ the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * all compilers and versions listed above for C++. -* ``GNU``: GNU compiler versions 3.4 through 8.0. +* ``GNU``: GNU compiler versions 3.4+ CMake is currently aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and their associated meta-features (e.g. ``cxx_std_11``) available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``Cray``: Cray Compiler Environment version 8.1 through 8.5.8. -* ``PGI``: PGI version 12.10 through 17.5. -* ``XL``: IBM XL version 10.1 through 13.1.5. +* ``Cray``: Cray Compiler Environment version 8.1+. +* ``PGI``: PGI version 12.10+. +* ``XL``: IBM XL version 10.1+. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and their associated meta-features (e.g. ``c_std_99``) available from the @@ -367,4 +367,4 @@ CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``NVIDIA``: NVIDIA nvcc compiler 7.5 though 9.1. +* ``NVIDIA``: NVIDIA nvcc compiler 7.5+. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index ba9887c..75f4bd4 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -47,8 +47,8 @@ Logical Operators ----------------- ``$<BOOL:string>`` - Converts ``string`` to ``0`` or ``1`` according to the rules of the - :command:`if()` command. Evaluates to ``0`` if any of the following is true: + Converts ``string`` to ``0`` or ``1``. Evaluates to ``0`` if any of the + following is true: * ``string`` is empty, * ``string`` is a case-insensitive equal of diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 1369aa3..a59dd6b 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -414,10 +414,10 @@ Properties on Tests /prop_test/LABELS /prop_test/MEASUREMENT /prop_test/PASS_REGULAR_EXPRESSION - /prop_test/PROCESSES /prop_test/PROCESSOR_AFFINITY /prop_test/PROCESSORS /prop_test/REQUIRED_FILES + /prop_test/RESOURCE_GROUPS /prop_test/RESOURCE_LOCK /prop_test/RUN_SERIAL /prop_test/SKIP_REGULAR_EXPRESSION diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 0442d89..360140c 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -191,6 +191,7 @@ Variables that Change Behavior /variable/CMAKE_FIND_USE_PACKAGE_REGISTRY /variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH /variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH + /variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FRAMEWORK_PATH /variable/CMAKE_IGNORE_PATH /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index f82c466..395cd41 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -55,6 +55,8 @@ Options When the CMake project uses a multi-configuration generator such as Xcode or Visual Studio, this option is needed to tell ``cpack`` which built executables to include in the package. + The user is responsible for ensuring that the configuration(s) listed + have already been built before invoking ``cpack``. ``-D <var>=<value>`` Set a CPack variable. This will override any value set for ``<var>`` in the diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index a18d43f..dbefb91 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -90,14 +90,14 @@ Options See `Label and Subproject Summary`_. -``--hardware-spec-file <file>`` - Run CTest with :ref:`hardware allocation <ctest-hardware-allocation>` enabled, +``--resource-spec-file <file>`` + Run CTest with :ref:`resource allocation <ctest-resource-allocation>` enabled, using the - :ref:`hardware specification file <ctest-hardware-specification-file>` + :ref:`resource specification file <ctest-resource-specification-file>` specified in ``<file>``. When ``ctest`` is run as a `Dashboard Client`_ this sets the - ``HardwareSpecFile`` option of the `CTest Test Step`_. + ``ResourceSpecFile`` option of the `CTest Test Step`_. ``--test-load <level>`` While running tests in parallel (e.g. with ``-j``), try not to start @@ -967,10 +967,10 @@ Arguments to the command may specify some of the step settings. Configuration settings include: -``HardwareSpecFile`` +``ResourceSpecFile`` Specify a - :ref:`hardware specification file <ctest-hardware-specification-file>`. See - :ref:`ctest-hardware-allocation` for more information. + :ref:`resource specification file <ctest-resource-specification-file>`. See + :ref:`ctest-resource-allocation` for more information. ``LabelsForSubprojects`` Specify a semicolon-separated list of labels that will be treated as @@ -1281,22 +1281,22 @@ model is defined as follows: Test properties. Can contain keys for each of the supported test properties. -.. _`ctest-hardware-allocation`: +.. _`ctest-resource-allocation`: -Hardware Allocation +Resource Allocation =================== -CTest provides a mechanism for tests to specify the hardware that they need and -how much of it they need, and for users to specify the hardware availiable on +CTest provides a mechanism for tests to specify the resources that they need +in a fine-grained way, and for users to specify the resources availiable on the running machine. This allows CTest to internally keep track of which -hardware is in use and which is free, scheduling tests in a way that prevents -them from trying to claim hardware that is not available. +resources are in use and which are free, scheduling tests in a way that +prevents them from trying to claim resources that are not available. A common use case for this feature is for tests that require the use of a GPU. Multiple tests can simultaneously allocate memory from a GPU, but if too many tests try to do this at once, some of them will fail to allocate, resulting in a failed test, even though the test would have succeeded if it had the memory -it needed. By using the hardware allocation feature, each test can specify how +it needed. By using the resource allocation feature, each test can specify how much memory it requires from a GPU, allowing CTest to schedule tests in a way that running several of these tests at once does not exhaust the GPU's memory pool. @@ -1312,36 +1312,35 @@ When a test is executed, and slots from a resource are allocated to that test, tests may assume that they have exclusive use of those slots for the duration of the test's process. -The CTest hardware allocation feature consists of two inputs: +The CTest resource allocation feature consists of two inputs: -* The :ref:`hardware specification file <ctest-hardware-specification-file>`, - described below, which describes the hardware resources available on the - system, and -* The :prop_test:`PROCESSES` property of tests, which describes the resources - required by the test +* The :ref:`resource specification file <ctest-resource-specification-file>`, + described below, which describes the resources available on the system. +* The :prop_test:`RESOURCE_GROUPS` property of tests, which describes the + resources required by the test. -When CTest runs a test, the hardware allocated to that test is passed in the +When CTest runs a test, the resources allocated to that test are passed in the form of a set of -:ref:`environment variables <ctest-hardware-environment-variables>` as +:ref:`environment variables <ctest-resource-environment-variables>` as described below. Using this information to decide which resource to connect to is left to the test writer. -Please note that these processes are not spawned by CTest. The ``PROCESSES`` -property merely tells CTest what processes the test expects to launch. It is up -to the test itself to do this process spawning, and read the :ref:`environment -variables <ctest-hardware-environment-variables>` to determine which resources -each process has been allocated. +The ``RESOURCE_GROUPS`` property tells CTest what resources a test expects +to use grouped in a way meaningful to the test. The test itself must read +the :ref:`environment variables <ctest-resource-environment-variables>` to +determine which resources have been allocated to each group. For example, +each group may correspond to a process the test will spawn when executed. -.. _`ctest-hardware-specification-file`: +.. _`ctest-resource-specification-file`: -Hardware Specification File +Resource Specification File --------------------------- -The hardware specification file is a JSON file which is passed to CTest, either -on the :manual:`ctest(1)` command line as ``--hardware-spec-file``, or as the -``HARDWARE_SPEC_FILE`` argument of :command:`ctest_test`. The hardware +The resource specification file is a JSON file which is passed to CTest, either +on the :manual:`ctest(1)` command line as ``--resource-spec-file``, or as the +``RESOURCE_SPEC_FILE`` argument of :command:`ctest_test`. The resource specification file must be a JSON object. All examples in this document assume -the following hardware specification file: +the following resource specification file: .. code-block:: json @@ -1378,11 +1377,11 @@ the following hardware specification file: The members are: ``local`` - A JSON array consisting of CPU sockets present on the system. Currently, only - one socket is supported. + A JSON array of resource sets present on the system. Currently, this array + is restricted to being of size 1. - Each socket is a JSON object with members whose names are equal to the - desired resource types, such as ``gpu``. These names must start with a + Each array element is a JSON object with members whose names are equal to the + desired resource types, such as ``gpus``. These names must start with a lowercase letter or an underscore, and subsequent characters can be a lowercase letter, a digit, or an underscore. Uppercase letters are not allowed, because certain platforms have case-insensitive environment @@ -1423,12 +1422,12 @@ In the example file above, there are four GPUs with ID's 0 through 3. GPU 0 has 2 slots, GPU 1 has 4, GPU 2 has 2, and GPU 3 has a default of 1 slot. There is also one cryptography chip with 4 slots. -``PROCESSES`` Property ----------------------- +``RESOURCE_GROUPS`` Property +---------------------------- -See :prop_test:`PROCESSES` for a description of this property. +See :prop_test:`RESOURCE_GROUPS` for a description of this property. -.. _`ctest-hardware-environment-variables`: +.. _`ctest-resource-environment-variables`: Environment Variables --------------------- @@ -1436,65 +1435,67 @@ Environment Variables Once CTest has decided which resources to allocate to a test, it passes this information to the test executable as a series of environment variables. For each example below, we will assume that the test in question has a -:prop_test:`PROCESSES` property of ``2,gpus:2;gpus:4,gpus:1,crypto_chips:2``. +:prop_test:`RESOURCE_GROUPS` property of +``2,gpus:2;gpus:4,gpus:1,crypto_chips:2``. The following variables are passed to the test process: -.. envvar:: CTEST_PROCESS_COUNT +.. envvar:: CTEST_RESOURCE_GROUP_COUNT - The total number of processes specified by the :prop_test:`PROCESSES` + The total number of groups specified by the :prop_test:`RESOURCE_GROUPS` property. For example: - * ``CTEST_PROCESS_COUNT=3`` + * ``CTEST_RESOURCE_GROUP_COUNT=3`` This variable will only be defined if :manual:`ctest(1)` has been given a - ``--hardware-spec-file``, or if :command:`ctest_test` has been given a - ``HARDWARE_SPEC_FILE``. If no hardware specification file has been given, + ``--resource-spec-file``, or if :command:`ctest_test` has been given a + ``RESOURCE_SPEC_FILE``. If no resource specification file has been given, this variable will not be defined. -.. envvar:: CTEST_PROCESS_<num> +.. envvar:: CTEST_RESOURCE_GROUP_<num> - The list of resource types allocated to each process, with each item + The list of resource types allocated to each group, with each item separated by a comma. ``<num>`` is a number from zero to - ``CTEST_PROCESS_COUNT`` minus one. ``CTEST_PROCESS_<num>`` is defined for - each ``<num>`` in this range. For example: + ``CTEST_RESOURCE_GROUP_COUNT`` minus one. ``CTEST_RESOURCE_GROUP_<num>`` + is defined for each ``<num>`` in this range. For example: - * ``CTEST_PROCESS_0=gpus`` - * ``CTEST_PROCESS_1=gpus`` - * ``CTEST_PROCESS_2=crypto_chips,gpus`` + * ``CTEST_RESOURCE_GROUP_0=gpus`` + * ``CTEST_RESOURCE_GROUP_1=gpus`` + * ``CTEST_RESOURCE_GROUP_2=crypto_chips,gpus`` -.. envvar:: CTEST_PROCESS_<num>_<resource-type> +.. envvar:: CTEST_RESOURCE_GROUP_<num>_<resource-type> The list of resource IDs and number of slots from each ID allocated to each - process for a given resource type. This variable consists of a series of + group for a given resource type. This variable consists of a series of pairs, each pair separated by a semicolon, and with the two items in the pair separated by a comma. The first item in each pair is ``id:`` followed by the ID of a resource of type ``<resource-type>``, and the second item is ``slots:`` followed by the number of slots from that resource allocated to - the given process. For example: + the given group. For example: - * ``CTEST_PROCESS_0_GPUS=id:0,slots:2`` - * ``CTEST_PROCESS_1_GPUS=id:2,slots:2`` - * ``CTEST_PROCESS_2_GPUS=id:1,slots:4;id:3,slots:1`` - * ``CTEST_PROCESS_2_CRYPTO_CHIPS=id:card0,slots:2`` + * ``CTEST_RESOURCE_GROUP_0_GPUS=id:0,slots:2`` + * ``CTEST_RESOURCE_GROUP_1_GPUS=id:2,slots:2`` + * ``CTEST_RESOURCE_GROUP_2_GPUS=id:1,slots:4;id:3,slots:1`` + * ``CTEST_RESOURCE_GROUP_2_CRYPTO_CHIPS=id:card0,slots:2`` - In this example, process 0 gets 2 slots from GPU ``0``, process 1 gets 2 slots - from GPU ``2``, and process 2 gets 4 slots from GPU ``1`` and 2 slots from - cryptography chip ``card0``. + In this example, group 0 gets 2 slots from GPU ``0``, group 1 gets 2 slots + from GPU ``2``, and group 2 gets 4 slots from GPU ``1``, 1 slot from GPU + ``3``, and 2 slots from cryptography chip ``card0``. - ``<num>`` is a number from zero to ``CTEST_PROCESS_COUNT`` minus one. + ``<num>`` is a number from zero to ``CTEST_RESOURCE_GROUP_COUNT`` minus one. ``<resource-type>`` is the name of a resource type, converted to uppercase. - ``CTEST_PROCESS_<num>_<resource-type>`` is defined for the product of each - ``<num>`` in the range listed above and each resource type listed in - ``CTEST_PROCESS_<num>``. + ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` is defined for the product + of each ``<num>`` in the range listed above and each resource type listed in + ``CTEST_RESOURCE_GROUP_<num>``. Because some platforms have case-insensitive names for environment variables, the names of resource types may not clash in a case-insensitive environment. Because of this, for the sake of simplicity, all resource types must be listed in all lowercase in the - :ref:`hardware specification file <ctest-hardware-specification-file>` and in - the :prop_test:`PROCESSES` property, and they are converted to all uppercase - in the ``CTEST_PROCESS_<num>_<resource-type>`` environment variable. + :ref:`resource specification file <ctest-resource-specification-file>` and + in the :prop_test:`RESOURCE_GROUPS` property, and they are converted to all + uppercase in the ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` environment + variable. See Also ======== diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index 262a67c..b921c6b 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -15,19 +15,19 @@ compile features and a list of supported compilers. The features known to this version of CMake are: ``cxx_std_98`` - Compiler mode is aware of C++ 98. + Compiler mode is at least C++ 98. ``cxx_std_11`` - Compiler mode is aware of C++ 11. + Compiler mode is at least C++ 11. ``cxx_std_14`` - Compiler mode is aware of C++ 14. + Compiler mode is at least C++ 14. ``cxx_std_17`` - Compiler mode is aware of C++ 17. + Compiler mode is at least C++ 17. ``cxx_std_20`` - Compiler mode is aware of C++ 20. + Compiler mode is at least C++ 20. ``cxx_aggregate_default_initializers`` Aggregate default initializers, as defined in N3605_. diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst index 3707fef..e5f896e 100644 --- a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -14,13 +14,13 @@ compile features and a list of supported compilers. The features known to this version of CMake are: ``c_std_90`` - Compiler mode is aware of C 90. + Compiler mode is at least C 90. ``c_std_99`` - Compiler mode is aware of C 99. + Compiler mode is at least C 99. ``c_std_11`` - Compiler mode is aware of C 11. + Compiler mode is at least C 11. ``c_function_prototypes`` Function prototypes, as defined in ``ISO/IEC 9899:1990``. diff --git a/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst index 53f3970..6d1e60d 100644 --- a/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst +++ b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst @@ -1,7 +1,11 @@ SKIP_UNITY_BUILD_INCLUSION -------------------------- -Is this source file skipped by :prop_tgt:`UNITY_BUILD` feature. +Setting this property to true ensures the source file will be skipped by +unity builds when its associated target has its :prop_tgt:`UNITY_BUILD` +property set to true. The source file will instead be compiled on its own +in the same way as it would with unity builds disabled. -This property helps with "ODR (One definition rule)" problems -that one would run into when using an :prop_tgt:`UNITY_BUILD`. +This property helps with "ODR (One definition rule)" problems where combining +a particular source file with others might lead to build errors or other +unintended side effects. diff --git a/Help/prop_test/PROCESSES.rst b/Help/prop_test/PROCESSES.rst deleted file mode 100644 index d09c6d1..0000000 --- a/Help/prop_test/PROCESSES.rst +++ /dev/null @@ -1,54 +0,0 @@ -PROCESSES ----------- - -Set to specify the number of processes spawned by a test, and the resources -that they require. See :ref:`hardware allocation <ctest-hardware-allocation>` -for more information on how this property integrates into the CTest hardware -allocation feature. - -The ``PROCESSES`` property is a :ref:`semicolon-separated list <CMake Language -Lists>` of process descriptions. Each process description consists of an -optional number of processes for the description followed by a series of -resource requirements for those processes. These requirements (and the number -of processes) are separated by commas. The resource requirements consist of the -name of a resource type, followed by a colon, followed by an unsigned integer -specifying the number of slots required on one resource of the given type. - -Please note that these processes are not spawned by CTest. The ``PROCESSES`` -property merely tells CTest what processes the test expects to launch. It is up -to the test itself to do this process spawning, and read the :ref:`environment -variables <ctest-hardware-environment-variables>` to determine which resources -each process has been allocated. - -Consider the following example: - -.. code-block:: cmake - - add_test(NAME MyTest COMMAND MyExe) - set_property(TEST MyTest PROPERTY PROCESSES - "2,gpus:2" - "gpus:4,crypto_chips:2") - -In this example, there are two process descriptions (implicitly separated by a -semicolon.) The content of the first description is ``2,gpus:2``. This -description spawns 2 processes, each of which requires 2 slots from a single -GPU. The content of the second description is ``gpus:4,crypto_chips:2``. This -description does not specify a process count, so a default of 1 is assumed. -This single process requires 4 slots from a single GPU and 2 slots from a -single cryptography chip. In total, 3 processes are spawned from this test, -each with their own unique requirements. - -When CTest sets the :ref:`environment variables -<ctest-hardware-environment-variables>` for a test, it assigns a process number -based on the process description, starting at 0 on the left and the number of -processes minus 1 on the right. For example, in the example above, the two -processes in the first description would have IDs of 0 and 1, and the single -process in the second description would have an ID of 2. - -Both the ``PROCESSES`` and :prop_test:`RESOURCE_LOCK` properties serve similar -purposes, but they are distinct and orthogonal. Resources specified by -``PROCESSES`` do not affect :prop_test:`RESOURCE_LOCK`, and vice versa. Whereas -:prop_test:`RESOURCE_LOCK` is a simpler property that is used for locking one -global resource, ``PROCESSES`` is a more advanced property that allows multiple -tests to simultaneously use multiple resources of the same type, specifying -their requirements in a fine-grained manner. diff --git a/Help/prop_test/RESOURCE_GROUPS.rst b/Help/prop_test/RESOURCE_GROUPS.rst new file mode 100644 index 0000000..436451c --- /dev/null +++ b/Help/prop_test/RESOURCE_GROUPS.rst @@ -0,0 +1,54 @@ +RESOURCE_GROUPS +--------------- + +Specify resources required by a test, grouped in a way that is meaningful to +the test. See :ref:`resource allocation <ctest-resource-allocation>` +for more information on how this property integrates into the CTest resource +allocation feature. + +The ``RESOURCE_GROUPS`` property is a :ref:`semicolon-separated list <CMake +Language Lists>` of group descriptions. Each entry consists of an optional +number of groups using the description followed by a series of resource +requirements for those groups. These requirements (and the number of groups) +are separated by commas. The resource requirements consist of the name of a +resource type, followed by a colon, followed by an unsigned integer +specifying the number of slots required on one resource of the given type. + +The ``RESOURCE_GROUPS`` property tells CTest what resources a test expects +to use grouped in a way meaningful to the test. The test itself must read +the :ref:`environment variables <ctest-resource-environment-variables>` to +determine which resources have been allocated to each group. For example, +each group may correspond to a process the test will spawn when executed. + +Consider the following example: + +.. code-block:: cmake + + add_test(NAME MyTest COMMAND MyExe) + set_property(TEST MyTest PROPERTY RESOURCE_GROUPS + "2,gpus:2" + "gpus:4,crypto_chips:2") + +In this example, there are two group descriptions (implicitly separated by a +semicolon.) The content of the first description is ``2,gpus:2``. This +description specifies 2 groups, each of which requires 2 slots from a single +GPU. The content of the second description is ``gpus:4,crypto_chips:2``. This +description does not specify a group count, so a default of 1 is assumed. +This single group requires 4 slots from a single GPU and 2 slots from a +single cryptography chip. In total, 3 resource groups are specified for this +test, each with its own unique requirements. + +When CTest sets the :ref:`environment variables +<ctest-resource-environment-variables>` for a test, it assigns a group number +based on the group description, starting at 0 on the left and the number of +groups minus 1 on the right. For example, in the example above, the two +groups in the first description would have IDs of 0 and 1, and the single +group in the second description would have an ID of 2. + +Both the ``RESOURCE_GROUPS`` and :prop_test:`RESOURCE_LOCK` properties serve +similar purposes, but they are distinct and orthogonal. Resources specified by +``RESOURCE_GROUPS`` do not affect :prop_test:`RESOURCE_LOCK`, and vice versa. +Whereas :prop_test:`RESOURCE_LOCK` is a simpler property that is used for +locking one global resource, ``RESOURCE_GROUPS`` is a more advanced property +that allows multiple tests to simultaneously use multiple resources of the +same type, specifying their requirements in a fine-grained manner. diff --git a/Help/prop_test/RESOURCE_LOCK.rst b/Help/prop_test/RESOURCE_LOCK.rst index 7d61f77..8b13a01 100644 --- a/Help/prop_test/RESOURCE_LOCK.rst +++ b/Help/prop_test/RESOURCE_LOCK.rst @@ -9,10 +9,10 @@ not to run concurrently. See also :prop_test:`FIXTURES_REQUIRED` if the resource requires any setup or cleanup steps. -Both the :prop_test:`PROCESSES` and ``RESOURCE_LOCK`` properties serve similar -purposes, but they are distinct and orthogonal. Resources specified by -:prop_test:`PROCESSES` do not affect ``RESOURCE_LOCK``, and vice versa. Whereas -``RESOURCE_LOCK`` is a simpler property that is used for locking one global -resource, :prop_test:`PROCESSES` is a more advanced property that allows -multiple tests to simultaneously use multiple resources of the same type, -specifying their requirements in a fine-grained manner. +Both the :prop_test:`RESOURCE_GROUPS` and ``RESOURCE_LOCK`` properties serve +similar purposes, but they are distinct and orthogonal. Resources specified by +:prop_test:`RESOURCE_GROUPS` do not affect ``RESOURCE_LOCK``, and vice versa. +Whereas ``RESOURCE_LOCK`` is a simpler property that is used for locking one +global resource, :prop_test:`RESOURCE_GROUPS` is a more advanced property +that allows multiple tests to simultaneously use multiple resources of the +same type, specifying their requirements in a fine-grained manner. diff --git a/Help/prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH.rst b/Help/prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH.rst index a474fc6..72dcaa0 100644 --- a/Help/prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH.rst +++ b/Help/prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH.rst @@ -1,10 +1,16 @@ INSTALL_REMOVE_ENVIRONMENT_RPATH -------------------------------- -Removes compiler defined rpaths durimg installation. +Controls whether toolchain-defined rpaths should be removed during installation. -``INSTALL_REMOVE_ENVIRONMENT_RPATH`` is a boolean that if set to ``True`` will -remove compiler defined rpaths from the project if the user also defines rpath -with :prop_tgt:`INSTALL_RPATH`. This property is initialized by whether the -value of :variable:`CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH` is set when a -target is created. +When a target is being installed, CMake may need to rewrite its rpath +information. This occurs when the install rpath (as specified by the +:prop_tgt:`INSTALL_RPATH` target property) has different contents to the rpath +that the target was built with. Some toolchains insert their own rpath +contents into the binary as part of the build. By default, CMake will +preserve those extra inserted contents in the install rpath. For those +scenarios where such toolchain-inserted entries need to be discarded during +install, set the ``INSTALL_REMOVE_ENVIRONMENT_RPATH`` target property to true. + +This property is initialized by the value of +:variable:`CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH` when the target is created. diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst index 2faad92..479802e 100644 --- a/Help/prop_tgt/UNITY_BUILD.rst +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -1,61 +1,60 @@ UNITY_BUILD ----------- -Should the target source files be processed into batches for -faster compilation. This feature is known as "Unity build", -or "Jumbo build". - -The ``C`` and ``CXX`` source files are grouped separately. - -This property is initialized by the value of the -:variable:`CMAKE_UNITY_BUILD` variable if it is set when -a target is created. - -.. note:: - - It's not recommended to directly set :prop_tgt:`UNITY_BUILD` - to ``ON``, but to instead set :variable:`CMAKE_UNITY_BUILD` from - the command line. However, it IS recommended to set - :prop_tgt:`UNITY_BUILD` to ``OFF`` if you need to ensure that a - target doesn't get a unity build. - -The batch size can be specified by setting -:prop_tgt:`UNITY_BUILD_BATCH_SIZE`. - -The batching of source files is done by adding new sources files -which will ``#include`` the source files, and exclude them from -building by setting :prop_sf:`HEADER_FILE_ONLY` to ``ON``. +When this property is set to true, the target source files will be combined +into batches for faster compilation. This is done by creating a (set of) +unity sources which ``#include`` the original sources, then compiling these +unity sources instead of the originals. This is known as a *Unity* or *Jumbo* +build. The :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property controls the upper +limit on how many sources can be combined per unity source file. + +Unity builds are not currently supported for all languages. CMake version +|release| supports combining ``C`` and ``CXX`` source files. For targets that +mix source files from more than one language, CMake will separate the languages +such that each generated unity source file only contains sources for a single +language. + +This property is initialized by the value of the :variable:`CMAKE_UNITY_BUILD` +variable when a target is created. .. note:: - Marking the original sources with :prop_sf:`HEADER_FILE_ONLY` - is considered an implementation detail that may change in the - future because it does not work well in combination with - the :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable. + Projects should not directly set the ``UNITY_BUILD`` property or its + associated :variable:`CMAKE_UNITY_BUILD` variable to true. Depending + on the capabilities of the build machine and compiler used, it might or + might not be appropriate to enable unity builds. Therefore, this feature + should be under developer control, which would normally be through the + developer choosing whether or not to set the :variable:`CMAKE_UNITY_BUILD` + variable on the :manual:`cmake(1)` command line or some other equivalent + method. However, it IS recommended to set the ``UNITY_BUILD`` target + property to false if it is known that enabling unity builds for the + target can lead to problems. ODR (One definition rule) errors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Since multiple source files are included into one source file, -it can lead to ODR errors. This section contains properties -which help fixing these errors. - -The source files marked by :prop_sf:`GENERATED` will be skipped -from unity build. This applies also for the source files marked -with :prop_sf:`SKIP_UNITY_BUILD_INCLUSION`. - -The source files that have :prop_sf:`COMPILE_OPTIONS`, -:prop_sf:`COMPILE_DEFINITIONS`, :prop_sf:`COMPILE_FLAGS`, or -:prop_sf:`INCLUDE_DIRECTORIES` will also be skipped. - -With the :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE` and -:prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE` one can specify code -to be injected in the unity source file before and after every -``#include`` statement. - -.. note:: - - The order of source files defined in the ``CMakeLists.txt`` will - be preserved into the generated unity source files. This can - be used to manually enforce a specific grouping based on the - :prop_tgt:`UNITY_BUILD_BATCH_SIZE` target property. +When multiple source files are included into one source file, as is done +for unity builds, it can potentially lead to ODR errors. CMake provides +a number of measures to help address such problems: + +* Any source file that has a non-empty :prop_sf:`COMPILE_OPTIONS`, + :prop_sf:`COMPILE_DEFINITIONS`, :prop_sf:`COMPILE_FLAGS`, or + :prop_sf:`INCLUDE_DIRECTORIES` source property will not be combined + into a unity source. + +* Projects can prevent an individual source file from being combined into + a unity source by setting its :prop_sf:`SKIP_UNITY_BUILD_INCLUSION` + source property to true. This can be a more effective way to prevent + problems with specific files than disabling unity builds for an entire + target. + +* The :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE` and + :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE` target properties can be used + to inject code into the unity source files before and after every + ``#include`` statement. + +* The order of source files added to the target via commands like + :command:`add_library`, :command:`add_executable` or + :command:`target_sources` will be preserved in the generated unity source + files. This can be used to manually enforce a specific grouping based on + the :prop_tgt:`UNITY_BUILD_BATCH_SIZE` target property. diff --git a/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst index 84047f2..44ffe27 100644 --- a/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst +++ b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst @@ -1,13 +1,23 @@ UNITY_BUILD_BATCH_SIZE ---------------------- -Specifies how many source code files will be included into a -:prop_tgt:`UNITY_BUILD` source file. +Specifies the maximum number of source files that can be combined into any one +unity source file when unity builds are enabled by the :prop_tgt:`UNITY_BUILD` +target property. The original source files will be distributed across as many +unity source files as necessary to honor this limit. -If the property is not set, CMake will use the value provided -by :variable:`CMAKE_UNITY_BUILD_BATCH_SIZE`. +The initial value for this property is taken from the +:variable:`CMAKE_UNITY_BUILD_BATCH_SIZE` variable when the target is created. +If that variable has not been set, the initial value will be 8. -By setting it to value `0` the generated unity source file will -contain all the source files that would otherwise be split -into multiple batches. It is not recommended to do so, since it -would affect performance. +The batch size needs to be selected carefully. If set too high, the size of +the combined source files could result in the compiler using excessive memory +or hitting other similar limits. In extreme cases, this can even result in +build failure. On the other hand, if the batch size is too low, there will be +little gain in build performance. + +Although strongly discouraged, the batch size may be set to a value of 0 to +combine all the sources for the target into a single unity file, regardless of +how many sources are involved. This runs the risk of creating an excessively +large unity source file and negatively impacting the build performance, so +a value of 0 is not generally recommended. diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst index 7795289..7231b61 100644 --- a/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst +++ b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst @@ -2,7 +2,18 @@ UNITY_BUILD_CODE_AFTER_INCLUDE ------------------------------ Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD` -feature just after the `#include` statement of the targeted source -files. +feature just after every ``#include`` statement in the generated unity +source files. For example: -This could be something like `#undef NOMINMAX`. +.. code-block:: cmake + + set(after [[ + #if defined(NOMINMAX) + #undef NOMINMAX + #endif + ]]) + set_target_properties(myTarget PROPERTIES + UNITY_BUILD_CODE_AFTER_INCLUDE "${after}" + ) + +See also :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE`. diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst index f335463..7ed6fa1 100644 --- a/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst +++ b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst @@ -2,7 +2,18 @@ UNITY_BUILD_CODE_BEFORE_INCLUDE ------------------------------- Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD` -feature just before the `#include` statement of the targeted source -files. +feature just before every ``#include`` statement in the generated unity +source files. For example: -This could be something like `#define NOMINMAX`. +.. code-block:: cmake + + set(before [[ + #if !defined(NOMINMAX) + #define NOMINMAX + #endif + ]]) + set_target_properties(myTarget PROPERTIES + UNITY_BUILD_CODE_BEFORE_INCLUDE "${before}" + ) + +See also :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE`. diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst index 570f536..0d1cc1e 100644 --- a/Help/release/3.16.rst +++ b/Help/release/3.16.rst @@ -95,7 +95,9 @@ Commands * The :command:`find_package` command has learned to check the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable to control the default - behavior of searching the CMake user package registry. + behavior of searching the CMake user package registry and to check the + :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variable to control + the default behavior of searching the CMake system package registry. * The :command:`message` command learned indentation control with the new :variable:`CMAKE_MESSAGE_INDENT` variable. @@ -190,8 +192,8 @@ Autogen CTest ----- -* :manual:`ctest(1)` now has the ability to serialize tests based on hardware - requirements for each test. See :ref:`ctest-hardware-allocation` for +* :manual:`ctest(1)` now has the ability to schedule tests based on resource + requirements for each test. See :ref:`ctest-resource-allocation` for details. * A new test property, :prop_test:`SKIP_REGULAR_EXPRESSION`, has been added. @@ -205,9 +207,8 @@ CTest CPack ----- -* CPack variable :variable:`CPACK_INSTALL_CMAKE_CONFIGURATIONS` was added to - control what configurations are to be packaged for multi-configuration - CMake generators. +* :manual:`cpack(1)` learned support for multiple configurations for ``-C`` + option. * The :cpack_gen:`CPack DEB Generator` is now able to format generic text (usually used as the description for multiple CPack generators) according diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst index 44588b1..107c183 100644 --- a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst @@ -1,12 +1,23 @@ CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY --------------------------------------------- -Skip :ref:`System Package Registry` in :command:`find_package` calls. +.. deprecated:: 3.16 + + Use the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variable instead. + +By default this variable is not set. If neither +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` nor +``CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`` is set, then +:command:`find_package()` will use the :ref:`System Package Registry` +unless the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` option is provided. + +``CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`` is ignored if +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` is set. In some cases, it is not desirable to use the :ref:`System Package Registry` when searching for packages. If the :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable is -enabled, all the :command:`find_package` commands will skip +``TRUE``, all the :command:`find_package` commands will skip the :ref:`System Package Registry` as if they were called with the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst index 9ebf672..957e956 100644 --- a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst @@ -19,5 +19,6 @@ take precedence over this variable. See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst index 62ae3cb..d2bdb09 100644 --- a/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst @@ -19,5 +19,6 @@ take precedence over this variable. See also the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst index b484a6a..b99081d 100644 --- a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst @@ -19,5 +19,6 @@ take precedence over this variable. See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst index a9c8469..7c7ca36 100644 --- a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst @@ -26,4 +26,5 @@ See also :ref:`Disabling the Package Registry` and the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst index 25a25f3..e7f5b0f 100644 --- a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst @@ -18,4 +18,5 @@ See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, and :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variables. diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst index 0713709..fbaba5a 100644 --- a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst @@ -20,4 +20,5 @@ See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, -and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. +:variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH`, +and :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variables. diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..cb4eec5 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst @@ -0,0 +1,31 @@ +CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY +-------------------------------------- + +Controls searching the :ref:`System Package Registry` by the +:command:`find_package` command. + +By default this variable is not set and the behavior will fall back +to that determined by the deprecated +:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable. +If that is also not set, then :command:`find_package()` will use the +:ref:`System Package Registry` unless the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` +option is provided. + +This variable takes precedence over +:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` when both are set. + +In some cases, for example to locate only user specific installations, it +is not desirable to use the :ref:`System Package Registry` when searching +for packages. If the ``CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`` +variable is ``FALSE``, all the :command:`find_package` commands will skip +the :ref:`System Package Registry` as if they were called with the +``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry`. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst b/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst index 19ae5f3..76ca3da 100644 --- a/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst +++ b/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst @@ -1,9 +1,9 @@ CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH -------------------------------------- -Removes compiler defined rpaths durimg installation. +Sets the default for whether toolchain-defined rpaths should be removed during +installation. -``CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH`` is a boolean that if set to ``true`` -removes compiler defined rpaths from the project if the user also defines rpath -with :prop_tgt:`INSTALL_RPATH`. This is used to initialize the target property -:prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` for all targets. +``CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH`` is a boolean that provides the +default value for the :prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` property +of all subsequently created targets. diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst index bbcfd68..a86cd67 100644 --- a/Help/variable/CMAKE_UNITY_BUILD.rst +++ b/Help/variable/CMAKE_UNITY_BUILD.rst @@ -1,11 +1,19 @@ CMAKE_UNITY_BUILD ----------------- -Initializes the :prop_tgt:`UNITY_BUILD` target property on targets -as they are created. Set to ``ON`` to batch compilation of multiple -sources within each target. This feature is known as "Unity build", -or "Jumbo build". By default this variable is not set and so does -not enable unity builds on targets. +This variable is used to initialize the :prop_tgt:`UNITY_BUILD` +property of targets when they are created. Setting it to true +enables batch compilation of multiple sources within each target. +This feature is known as a *Unity* or *Jumbo* build. + +Projects should not set this variable, it is intended as a developer +control to be set on the :manual:`cmake(1)` command line or other +equivalent methods. The developer must have the ability to enable or +disable unity builds according to the capabilities of their own machine +and compiler. + +By default, this variable is not set, which will result in unity builds +being disabled. .. note:: This option currently does not work well in combination with diff --git a/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst index 3ab2344..7988d4b 100644 --- a/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst +++ b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst @@ -1,6 +1,7 @@ CMAKE_UNITY_BUILD_BATCH_SIZE ---------------------------- -Default value for :prop_tgt:`UNITY_BUILD_BATCH_SIZE` of targets. - -By default ``CMAKE_UNITY_BUILD_BATCH_SIZE`` is set to ``8``. +This variable is used to initialize the :prop_tgt:`UNITY_BUILD_BATCH_SIZE` +property of targets when they are created. It specifies the default upper +limit on the number of source files that may be combined in any one unity +source file when unity builds are enabled for a target. |