diff options
Diffstat (limited to 'Help')
30 files changed, 335 insertions, 126 deletions
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/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/message.rst b/Help/command/message.rst index beb820a..6bc0e4c 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -1,13 +1,33 @@ message ------- -Display a message to the user. +Log a message. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `General messages`_ + message([<mode>] "message text" ...) + + `Reporting checks`_ + message(<checkState> "message text" ...) + + +General messages +^^^^^^^^^^^^^^^^ .. code-block:: cmake - message([<mode>] "message to display" ...) + message([<mode>] "message text" ...) + +Record the specified message text in the log. If more than one message +string is given, they are concatenated into a single message with no +separator between the strings. -The optional ``<mode>`` keyword determines the type of message: +The optional ``<mode>`` keyword determines the type of message, which +influences the way the message is handled: ``FATAL_ERROR`` CMake Error, stop processing and generation. @@ -82,3 +102,81 @@ usage examples. CMake Warning and Error message text displays using a simple markup language. Non-indented text is formatted in line-wrapped paragraphs delimited by newlines. Indented text is considered pre-formatted. + + +Reporting checks +^^^^^^^^^^^^^^^^ + +A common pattern in CMake output is a message indicating the start of some +sort of check, followed by another message reporting the result of that check. +For example: + +.. code-block:: cmake + + message(STATUS "Looking for someheader.h") + #... do the checks, set checkSuccess with the result + if(checkSuccess) + message(STATUS "Looking for someheader.h - found") + else() + message(STATUS "Looking for someheader.h - not found") + endif() + +This can be more robustly and conveniently expressed using the ``CHECK_...`` +keyword form of the ``message()`` command: + +.. code-block:: cmake + + message(<checkState> "message" ...) + +where ``<checkState>`` must be one of the following: + + ``CHECK_START`` + Record a concise message about the check about to be performed. + + ``CHECK_PASS`` + Record a successful result for a check. + + ``CHECK_FAIL`` + Record an unsuccessful result for a check. + +When recording a check result, the command repeats the message from the most +recently started check for which no result has yet been reported, then some +separator characters and then the message text provided after the +``CHECK_PASS`` or ``CHECK_FAIL`` keyword. Check messages are always reported +at ``STATUS`` log level. + +Checks may be nested and every ``CHECK_START`` should have exactly one +matching ``CHECK_PASS`` or ``CHECK_FAIL``. +The :variable:`CMAKE_MESSAGE_INDENT` variable can also be used to add +indenting to nested checks if desired. For example: + +.. code-block:: cmake + + message(CHECK_START "Finding my things") + list(APPEND CMAKE_MESSAGE_INDENT " ") + unset(missingComponents) + + message(CHECK_START "Finding partA") + # ... do check, assume we find A + message(CHECK_PASS "found") + + message(CHECK_START "Finding partB") + # ... do check, assume we don't find B + list(APPEND missingComponents B) + message(CHECK_FAIL "not found") + + list(POP_BACK CMAKE_MESSAGE_INDENT) + if(missingComponents) + message(CHECK_FAIL "missing components: ${missingComponents}") + else() + message(CHECK_PASS "all components found") + endif() + +Output from the above would appear something like the following:: + + -- Finding my things + -- Finding partA + -- Finding partA - found + -- Finding partB + -- Finding partB - not found + -- Finding my things - missing components: B diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index 38676c4..dc65249 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst @@ -133,3 +133,19 @@ on Windows Nullsoft Scriptable Install System. Specify the name of the program to uninstall the version. Default is ``Uninstall``. + +.. variable:: CPACK_NSIS_WELCOME_TITLE + + The title to display on the top of the page for the welcome page. + +.. variable:: CPACK_NSIS_WELCOME_TITLE_3LINES + + Display the title in the welcome page on 3 lines instead of 2. + +.. variable:: CPACK_NSIS_FINISH_TITLE + + The title to display on the top of the page for the finish page. + +.. variable:: CPACK_NSIS_FINISH_TITLE_3LINES + + Display the title in the finish page on 3 lines instead of 2. 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 75f4bd4..691481b 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -596,7 +596,8 @@ Target-Dependent Queries requirement. ``$<INSTALL_PREFIX>`` Content of the install prefix when the target is exported via - :command:`install(EXPORT)` and empty otherwise. + :command:`install(EXPORT)`, or when evaluated in + :prop_tgt:`INSTALL_NAME_DIR`, and empty otherwise. Output-Related Expressions -------------------------- diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 026740c..84018b7 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -190,6 +190,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/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_tgt/INSTALL_NAME_DIR.rst b/Help/prop_tgt/INSTALL_NAME_DIR.rst index 2216072..747615a 100644 --- a/Help/prop_tgt/INSTALL_NAME_DIR.rst +++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst @@ -10,3 +10,7 @@ installed targets. This property is initialized by the value of the variable :variable:`CMAKE_INSTALL_NAME_DIR` if it is set when a target is created. + +This property supports :manual:`generator expressions <cmake-generator-expressions(7)>`. +In particular, the ``$<INSTALL_PREFIX>`` generator expression can be used to set the +directory relative to the install-time prefix. 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..fab4f15 100644 --- a/Help/prop_tgt/UNITY_BUILD.rst +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -40,9 +40,8 @@ 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 marked by :prop_sf:`SKIP_UNITY_BUILD_INCLUSION` +will be skipped from unity build. The source files that have :prop_sf:`COMPILE_OPTIONS`, :prop_sf:`COMPILE_DEFINITIONS`, :prop_sf:`COMPILE_FLAGS`, or diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst index 570f536..3f198ca 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. diff --git a/Help/release/dev/ccmake-colored-values.rst b/Help/release/dev/ccmake-colored-values.rst new file mode 100644 index 0000000..b00885d --- /dev/null +++ b/Help/release/dev/ccmake-colored-values.rst @@ -0,0 +1,5 @@ +ccmake-colored-values +--------------------- + +* :manual:`ccmake(1)` now displays cache values using colors + based on the entry type if the terminal supports color. diff --git a/Help/release/dev/cpack-nsis-welcome-finish-page-title.rst b/Help/release/dev/cpack-nsis-welcome-finish-page-title.rst new file mode 100644 index 0000000..8091d31 --- /dev/null +++ b/Help/release/dev/cpack-nsis-welcome-finish-page-title.rst @@ -0,0 +1,10 @@ +cpack-nsis-welcome-finish-page-title +------------------------------------ + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_WELCOME_TITLE` and :variable:`CPACK_NSIS_WELCOME_TITLE_3LINES`. + These can be used to specify the welcome page title and display it in 3 lines. + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_FINISH_TITLE` and :variable:`CPACK_NSIS_FINISH_TITLE_3LINES`. + These can be used to specify the finish page title and display it in 3 lines. diff --git a/Help/release/dev/install-name-dir-genex.rst b/Help/release/dev/install-name-dir-genex.rst new file mode 100644 index 0000000..0cb41f0 --- /dev/null +++ b/Help/release/dev/install-name-dir-genex.rst @@ -0,0 +1,7 @@ +install-name-dir-genex +---------------------- + +* The :prop_tgt:`INSTALL_NAME_DIR` target property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + In particular, the ``$<INSTALL_PREFIX>`` generator expression can + be used to set the directory relative to the install-time prefix. diff --git a/Help/release/dev/mingw_no_sh.rst b/Help/release/dev/mingw_no_sh.rst new file mode 100644 index 0000000..7008865 --- /dev/null +++ b/Help/release/dev/mingw_no_sh.rst @@ -0,0 +1,5 @@ +mingw-no-sh +----------- + +* The :generator:`MinGW Makefiles` generator no longer issues an error if + ``sh.exe`` is present in the environment's ``PATH``. diff --git a/Help/release/dev/new-message-types.rst b/Help/release/dev/new-message-types.rst new file mode 100644 index 0000000..8f164b9 --- /dev/null +++ b/Help/release/dev/new-message-types.rst @@ -0,0 +1,5 @@ +new-message-types +----------------- + +* The :command:`message` command gained new keywords ``CHECK_START``, + ``CHECK_PASS`` and ``CHECK_FAIL``. 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. |