diff options
Diffstat (limited to 'Help')
52 files changed, 571 insertions, 113 deletions
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/message.rst b/Help/command/message.rst index c614286..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. @@ -59,12 +79,104 @@ The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE`` messages one at a time on a status line and other messages in an interactive pop-up box. The ``--log-level`` command-line option to each of these tools can be used to control which messages will be shown. +To make a log level persist between CMake runs, the +:variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can be set instead. +Note that the command line option takes precedence over the cache variable. -Messages of log levels ``NOTICE`` and below will also have each line preceded +Messages of log levels ``NOTICE`` and below will have each line preceded by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to a single string by concatenating its list items). For ``STATUS`` to ``TRACE`` messages, this indenting content will be inserted after the hyphens. +Messages of log levels ``NOTICE`` and below can also have each line preceded +with context of the form ``[some.context.example]``. The content between the +square brackets is obtained by converting the :variable:`CMAKE_MESSAGE_CONTEXT` +list variable to a dot-separated string. The message context will always +appear before any indenting content but after any automatically added leading +hyphens. By default, message context is not shown, it has to be explicitly +enabled by giving the :manual:`cmake <cmake(1)>` ``--log-context`` +command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` +variable to true. See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for +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/command/project.rst b/Help/command/project.rst index 3951456..b6093d3 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -102,9 +102,12 @@ options are intended for use as default values in package metadata and documenta Code Injection ^^^^^^^^^^^^^^ -If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variable is set, the file -pointed to by that variable will be included as the first step of the +If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` or +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set, +the files they point to will be included as the first step of the ``project()`` command. +If both are set, then :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` will be +included before :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`. If the :variable:`CMAKE_PROJECT_INCLUDE` or :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index cd2aea6..38676c4 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst @@ -128,3 +128,8 @@ on Windows Nullsoft Scriptable Install System. set(CPACK_NSIS_MENU_LINKS "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html" "CMake Help" "https://cmake.org" "CMake Web Site") + +.. variable:: CPACK_NSIS_UNINSTALL_NAME + + Specify the name of the program to uninstall the version. + Default is ``Uninstall``. diff --git a/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst new file mode 100644 index 0000000..e9e0810 --- /dev/null +++ b/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -0,0 +1,9 @@ +CMAKE_EXPORT_COMPILE_COMMANDS +----------------------------- + +.. include:: ENV_VAR.txt + +The default value for :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` when there +is no explicit configuration given on the first run while creating a new +build tree. On later runs in an existing build tree the value persists in +the cache as :variable:`CMAKE_EXPORT_COMPILE_COMMANDS`. 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/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 658694a..a9d4843 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -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-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 96ceb94..c98f18f 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -23,6 +23,7 @@ Environment Variables that Control the Build /envvar/CMAKE_BUILD_PARALLEL_LEVEL /envvar/CMAKE_CONFIG_TYPE + /envvar/CMAKE_EXPORT_COMPILE_COMMANDS /envvar/CMAKE_GENERATOR /envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_PLATFORM diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 1369aa3..02e07eb 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -342,6 +342,7 @@ Properties on Targets /prop_tgt/VS_DOTNET_REFERENCES /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION + /prop_tgt/VS_DOTNET_DOCUMENTATION_FILE /prop_tgt/VS_DPI_AWARE /prop_tgt/VS_GLOBAL_KEYWORD /prop_tgt/VS_GLOBAL_PROJECT_TYPES diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 0442d89..84018b7 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -70,7 +70,6 @@ Variables that Provide Information /variable/CMAKE_MAKE_PROGRAM /variable/CMAKE_MATCH_COUNT /variable/CMAKE_MATCH_n - /variable/CMAKE_MESSAGE_INDENT /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION /variable/CMAKE_NETRC @@ -191,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 @@ -205,6 +205,10 @@ Variables that Change Behavior /variable/CMAKE_LINK_DIRECTORIES_BEFORE /variable/CMAKE_MFC_FLAG /variable/CMAKE_MAXIMUM_RECURSION_DEPTH + /variable/CMAKE_MESSAGE_CONTEXT + /variable/CMAKE_MESSAGE_CONTEXT_SHOW + /variable/CMAKE_MESSAGE_INDENT + /variable/CMAKE_MESSAGE_LOG_LEVEL /variable/CMAKE_MODULE_PATH /variable/CMAKE_POLICY_DEFAULT_CMPNNNN /variable/CMAKE_POLICY_WARNING_CMPNNNN @@ -213,6 +217,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_INCLUDE /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE + /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS @@ -238,6 +243,7 @@ Variables that Change Behavior /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /variable/CMAKE_XCODE_SCHEME_ENVIRONMENT /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 4ab55a0..71110d1 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -206,9 +206,24 @@ Options The :command:`message` command will only output messages of the specified log level or higher. The default log level is ``STATUS``. + To make a log level persist between CMake runs, set + :variable:`CMAKE_MESSAGE_LOG_LEVEL` as a cache variable instead. + If both the command line option and the variable are given, the command line + option takes precedence. + For backward compatibility reasons, ``--loglevel`` is also accepted as a synonym for this option. +``--log-context`` + Enable the :command:`message` command outputting context attached to each + message. + + This option turns on showing context for the current CMake run only. + To make showing the context persistent for all subsequent CMake runs, set + :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` as a cache variable instead. + When this command line option is given, :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` + is ignored. + ``--debug-trycompile`` Do not delete the :command:`try_compile` build tree. Only useful on one :command:`try_compile` at a time. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index a18d43f..0097cee 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -266,6 +266,19 @@ Options This is useful in finding sporadic failures in test cases. +``--repeat-until-pass <n>`` + Allow each test to run up to ``<n>`` times in order to pass. + Repeats tests if they fail for any reason. + + This is useful in tolerating sporadic failures in test cases. + +``--repeat-after-timeout <n>`` + Allow each test to run up to ``<n>`` times in order to pass. + Repeats tests only if they timeout. + + This is useful in tolerating sporadic timeouts in test cases + on busy machines. + ``--max-width <width>`` Set the max width for a test name to output. 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/VS_DOTNET_DOCUMENTATION_FILE.rst b/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst new file mode 100644 index 0000000..1bc361c --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst @@ -0,0 +1,6 @@ +VS_DOTNET_DOCUMENTATION_FILE +---------------------------- + +Visual Studio managed project .NET documentation output + +Sets the target XML documentation file output. 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/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/ExternalProject-git-no-recurse.rst b/Help/release/dev/ExternalProject-git-no-recurse.rst new file mode 100644 index 0000000..b9e09d3 --- /dev/null +++ b/Help/release/dev/ExternalProject-git-no-recurse.rst @@ -0,0 +1,7 @@ +ExternalProject-git-no-recurse +------------------------------ + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + command gained a ``GIT_SUBMODULES_RECURSE`` option to specify whether + Git submodules should be updated recursively. The default is on to + preserve existing behavior. diff --git a/Help/release/dev/FindCURL-cmake-package.rst b/Help/release/dev/FindCURL-cmake-package.rst new file mode 100644 index 0000000..67c5bbc --- /dev/null +++ b/Help/release/dev/FindCURL-cmake-package.rst @@ -0,0 +1,7 @@ +FindCURL-cmake-package +---------------------- + +* The :module:`FindCURL` module learned to find CURL using + the ``CURLConfig.cmake`` package configuration file generated by + CURL's cmake buildsystem. It also gained a new ``CURL_NO_CURL_CMAKE`` + option to disable this behavior. diff --git a/Help/release/dev/ccmake_progress_bar_and_log_display.rst b/Help/release/dev/ccmake_progress_bar_and_log_display.rst new file mode 100644 index 0000000..5c67c7d --- /dev/null +++ b/Help/release/dev/ccmake_progress_bar_and_log_display.rst @@ -0,0 +1,6 @@ +ccmake_progress_bar_and_log_display +----------------------------------- + +* :manual:`ccmake(1)` now displays messages and a progress bar during + configure and generate. It will keep the output displayed if any + errors or warnings occurred. diff --git a/Help/release/dev/cpack-nsis-uninstaller-name.rst b/Help/release/dev/cpack-nsis-uninstaller-name.rst new file mode 100644 index 0000000..b7ceb4c --- /dev/null +++ b/Help/release/dev/cpack-nsis-uninstaller-name.rst @@ -0,0 +1,6 @@ +cpack-nsis-uninstaller-name +--------------------------- + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_UNINSTALL_NAME`. + This can be used to specify the name of the Uninstall program. diff --git a/Help/release/dev/ctest-repeat-until-pass.rst b/Help/release/dev/ctest-repeat-until-pass.rst new file mode 100644 index 0000000..d177247 --- /dev/null +++ b/Help/release/dev/ctest-repeat-until-pass.rst @@ -0,0 +1,6 @@ +ctest-repeat-until-pass +----------------------- + +* The :manual:`ctest(1)` tool learned new ``--repeat-until-pass <n>`` + and ``--repeat-after-timeout <n>`` options to help tolerate sporadic + test failures. diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000..401f4b2 --- /dev/null +++ b/Help/release/dev/deprecate-policy-old.rst @@ -0,0 +1,8 @@ +deprecate-policy-old +-------------------- + +* An explicit deprecation diagnostic was added for policy ``CMP0068`` + and policy ``CMP0069`` (``CMP0067`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. diff --git a/Help/release/dev/export-compile-commands-environment-variable.rst b/Help/release/dev/export-compile-commands-environment-variable.rst new file mode 100644 index 0000000..da9d66b --- /dev/null +++ b/Help/release/dev/export-compile-commands-environment-variable.rst @@ -0,0 +1,6 @@ +export-compile-commands-environment-variable +-------------------------------------------- + +* The :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable now takes its + initial value from the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment + variable if no explicit configuration is given. diff --git a/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT.rst b/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT.rst new file mode 100644 index 0000000..a6a5c71 --- /dev/null +++ b/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT.rst @@ -0,0 +1,11 @@ +feature-CMAKE_MESSAGE_CONTEXT +----------------------------- + +* The :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can now be used + to persist a log level between CMake runs, unlike the ``--log-level`` + command line option which only applies to that particular run. + +* The :command:`message` command learned to output context provided in + the :variable:`CMAKE_MESSAGE_CONTEXT` variable for log levels + ``NOTICE`` and below. Enable this output with the new ``--log-context`` + command-line option or :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable. 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/release/dev/vs-per-config-sources.rst b/Help/release/dev/vs-per-config-sources.rst new file mode 100644 index 0000000..bf7572b --- /dev/null +++ b/Help/release/dev/vs-per-config-sources.rst @@ -0,0 +1,5 @@ +vs-per-config-sources +--------------------- + +* :ref:`Visual Studio Generators` learned to support per-config sources. + Previously only :ref:`Command-Line Build Tool Generators` supported them. diff --git a/Help/release/dev/vs-vctargetspath.rst b/Help/release/dev/vs-vctargetspath.rst new file mode 100644 index 0000000..d40af34 --- /dev/null +++ b/Help/release/dev/vs-vctargetspath.rst @@ -0,0 +1,10 @@ +vs-vctargetspath +---------------- + +* With :ref:`Visual Studio Generators` for VS 2010 and above, + the :variable:`CMAKE_GENERATOR_TOOLSET` setting gained an option + to specify the ``VCTargetsPath`` value for project files. + +* The :variable:`CMAKE_VS_GLOBALS` variable value now applies during + compiler identification and in targets created by the + :command:`add_custom_target` command. diff --git a/Help/release/dev/vs_dotnet_documentation_file.rst b/Help/release/dev/vs_dotnet_documentation_file.rst new file mode 100644 index 0000000..fdffb1c --- /dev/null +++ b/Help/release/dev/vs_dotnet_documentation_file.rst @@ -0,0 +1,6 @@ +vs_dotnet_documentation_file +---------------------------- + +* The :prop_tgt:`VS_DOTNET_DOCUMENTATION_FILE` target property was added + to tell :ref:`Visual Studio Generators` to generate a ``DocumentationFile`` + reference in ``.csproj`` files. diff --git a/Help/release/dev/xcode-scheme-env.rst b/Help/release/dev/xcode-scheme-env.rst new file mode 100644 index 0000000..238cb61 --- /dev/null +++ b/Help/release/dev/xcode-scheme-env.rst @@ -0,0 +1,5 @@ +xcode-scheme-env +---------------- + +* The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable was added + to initialize the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property. diff --git a/Help/release/index.rst b/Help/release/index.rst index 0cc3f97..a4585a5 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst index 4548abc..6d2450b 100644 --- a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst +++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -25,6 +25,9 @@ form. The format of the JSON file looks like: } ] +This is initialized by the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment +variable. + .. note:: This option is implemented only by :ref:`Makefile Generators` and the :generator:`Ninja`. It is ignored on other generators. 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_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 222824f..53ad2f3 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -58,3 +58,8 @@ Supported pairs are: Specify the toolset version to use. Supported by VS 2017 and above with the specified toolset installed. See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_VERSION` variable. + +``VCTargetsPath=<path>`` + Specify an alternative ``VCTargetsPath`` value for Visual Studio + project files. This allows use of VS platform extension configuration + files (``.props`` and ``.targets``) that are not installed with VS. 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_MESSAGE_CONTEXT.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst new file mode 100644 index 0000000..6b4ca40 --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst @@ -0,0 +1,62 @@ +CMAKE_MESSAGE_CONTEXT +--------------------- + +When enabled by the :manual:`cmake <cmake(1)>` ``--log-context`` command line +option or the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable, the +:command:`message` command converts the ``CMAKE_MESSAGE_CONTEXT`` list into a +dot-separated string surrounded by square brackets and prepends it to each line +for messages of log levels ``NOTICE`` and below. + +For logging contexts to work effectively, projects should generally +``APPEND`` and ``POP_BACK`` an item to the current value of +``CMAKE_MESSAGE_CONTEXT`` rather than replace it. +Projects should not assume the message context at the top of the source tree +is empty, as there are scenarios where the context might have already been set +(e.g. hierarchical projects). + +.. warning:: + + Valid context names are restricted to anything that could be used + as a CMake variable name. All names that begin with an underscore + or the string ``cmake_`` are also reserved for use by CMake and + should not be used by projects. + +Example: + +.. code-block:: cmake + + function(bar) + list(APPEND CMAKE_MESSAGE_CONTEXT "bar") + message(VERBOSE "bar VERBOSE message") + endfunction() + + function(baz) + list(APPEND CMAKE_MESSAGE_CONTEXT "baz") + message(DEBUG "baz DEBUG message") + endfunction() + + function(foo) + list(APPEND CMAKE_MESSAGE_CONTEXT "foo") + bar() + message(TRACE "foo TRACE message") + baz() + endfunction() + + list(APPEND CMAKE_MESSAGE_CONTEXT "top") + + message(VERBOSE "Before `foo`") + foo() + message(VERBOSE "After `foo`") + + list(POP_BACK CMAKE_MESSAGE_CONTEXT) + + +Which results in the following output: + +.. code-block:: none + + -- [top] Before `foo` + -- [top.foo.bar] bar VERBOSE message + -- [top.foo] foo TRACE message + -- [top.foo.baz] baz DEBUG message + -- [top] After `foo` diff --git a/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst new file mode 100644 index 0000000..7ec218e --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst @@ -0,0 +1,15 @@ +CMAKE_MESSAGE_CONTEXT_SHOW +-------------------------- + +Setting this variable to true enables showing a context with each line +logged by the :command:`message` command (see :variable:`CMAKE_MESSAGE_CONTEXT` +for how the context itself is specified). + +This variable is an alternative to providing the ``--log-context`` option +on the :manual:`cmake <cmake(1)>` command line. Whereas the command line +option will apply only to that one CMake run, setting +``CMAKE_MESSAGE_CONTEXT_SHOW`` to true as a cache variable will ensure that +subsequent CMake runs will continue to show the message context. + +Projects should not set ``CMAKE_MESSAGE_CONTEXT_SHOW``. It is intended for +users so that they may control whether or not to include context with messages. diff --git a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst new file mode 100644 index 0000000..1d4cfe6 --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst @@ -0,0 +1,15 @@ +CMAKE_MESSAGE_LOG_LEVEL +----------------------- + +When set, this variable specifies the logging level used by the +:command:`message` command. Valid values are the same as those for the +``--log-level`` command line option of the :manual:`cmake(1)` program. +If this variable is set and the ``--log-level`` command line option is +given, the command line option takes precedence. + +The main advantage to using this variable is to make a log level persist +between CMake runs. Setting it as a cache variable will ensure that +subsequent CMake runs will continue to use the chosen log level. + +Projects should not set this variable, it is intended for users so that +they may control the log level according to their own needs. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE.rst index 965c94e..5835264 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE.rst @@ -5,5 +5,6 @@ A CMake language file or module to be included as the last step of all :command:`project` command calls. This is intended for injecting custom code into project builds without modifying their source. -See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` and +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst index 70b15e6..280c14a 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst @@ -5,5 +5,6 @@ A CMake language file or module to be included as the first step of all :command:`project` command calls. This is intended for injecting custom code into project builds without modifying their source. -See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` and +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and :variable:`CMAKE_PROJECT_INCLUDE` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst index 3485c38..74247f1 100644 --- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -6,5 +6,6 @@ A CMake language file or module to be included as the last step of any name. This is intended for injecting custom code into project builds without modifying their source. -See also the :variable:`CMAKE_PROJECT_INCLUDE` and +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_INCLUDE` and :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst new file mode 100644 index 0000000..db1432d --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE +------------------------------------------- + +A CMake language file or module to be included as the first step of any +:command:`project` command calls that specify ``<PROJECT-NAME>`` as the project +name. This is intended for injecting custom code into project builds without +modifying their source. + +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_INCLUDE` and +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst new file mode 100644 index 0000000..4832659 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_ENVIRONMENT +------------------------------ + +Specify environment variables that should be added to the Arguments +section of the generated Xcode scheme. + +If set to a list of environment variables and values of the form +``MYVAR=value`` those environment variables will be added to the +scheme. + +This variable initializes the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. |