diff --git a/.clang-format b/.clang-format index 0c7d6b07208..4bfce446216 100644 --- a/.clang-format +++ b/.clang-format @@ -22,7 +22,9 @@ IncludeBlocks: Regroup IncludeCategories: - Regex: '^[<"]cmConfigure\.h' Priority: -1 - - Regex: '^(<|")cm/' + - Regex: '^' + Priority: 1 + - Regex: '^(<|")cm(ext)?/' Priority: 2 - Regex: '^(<|")windows\.h' Priority: 3 diff --git a/Auxiliary/vim/syntax/cmake.vim b/Auxiliary/vim/syntax/cmake.vim index 5de117b8265..0676f7ed296 100644 --- a/Auxiliary/vim/syntax/cmake.vim +++ b/Auxiliary/vim/syntax/cmake.vim @@ -101,6 +101,7 @@ syn keyword cmakeProperty contained \ CLEAN_NO_CUSTOM \ CMAKE_CONFIGURE_DEPENDS \ CMAKE_CXX_KNOWN_FEATURES + \ CMAKE_CUDA_KNOWN_FEATURES \ CMAKE_C_KNOWN_FEATURES \ CMAKE_ROLE \ COMMON_LANGUAGE_RUNTIME @@ -220,6 +221,7 @@ syn keyword cmakeProperty contained \ JOB_POOLS \ JOB_POOL_COMPILE \ JOB_POOL_LINK + \ JOB_POOL_PRECOMPILE_HEADER \ KEEP_EXTENSION \ LABELS \ LANGUAGE @@ -725,6 +727,7 @@ syn keyword cmakeVariable contained \ CMAKE_CUDA_COMPILER_AR \ CMAKE_CUDA_COMPILER_ARCHITECTURE_ID \ CMAKE_CUDA_COMPILER_EXTERNAL_TOOLCHAIN + \ CMAKE_CUDA_COMPILE_FEATURES \ CMAKE_CUDA_COMPILER_ID \ CMAKE_CUDA_COMPILER_LAUNCHER \ CMAKE_CUDA_COMPILER_LOADED @@ -1064,6 +1067,7 @@ syn keyword cmakeVariable contained \ CMAKE_JOB_POOLS \ CMAKE_JOB_POOL_COMPILE \ CMAKE_JOB_POOL_LINK + \ CMAKE_JOB_POOL_PRECOMPILE_HEADER \ CMAKE_Java \ CMAKE_Java_ANDROID_TOOLCHAIN_MACHINE \ CMAKE_Java_ANDROID_TOOLCHAIN_PREFIX @@ -2862,6 +2866,11 @@ syn keyword cmakeKWtarget_link_options contained \ _LINKER_WRAPPER_FLAG \ _LINKER_WRAPPER_FLAG_SEP +syn keyword cmakeKWtarget_precompile_headers contained + \ INTERFACE + \ PRIVATE + \ PUBLIC + syn keyword cmakeKWtarget_sources contained \ ALIAS \ IMPORTED @@ -3166,6 +3175,7 @@ syn keyword cmakeCommand \ target_link_directories \ target_link_libraries \ target_link_options + \ target_precompile_headers \ target_sources \ try_compile \ try_run @@ -3322,6 +3332,7 @@ hi def link cmakeKWtarget_include_directories ModeMsg hi def link cmakeKWtarget_link_directories ModeMsg hi def link cmakeKWtarget_link_libraries ModeMsg hi def link cmakeKWtarget_link_options ModeMsg +hi def link cmakeKWtarget_precompile_headers ModeMsg hi def link cmakeKWtarget_sources ModeMsg hi def link cmakeKWtry_compile ModeMsg hi def link cmakeKWtry_run ModeMsg diff --git a/CMakeLists.txt b/CMakeLists.txt index da99a6ee8d6..18b8d7d6e33 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -264,7 +264,6 @@ macro(CMAKE_SETUP_TESTING) ${CMake_BINARY_DIR}/Testing/HTML/TestingResults/Icons/Logo.gif COPYONLY) endif() mark_as_advanced(DART_ROOT) - mark_as_advanced(CURL_TESTING) endmacro() @@ -368,7 +367,7 @@ macro (CMAKE_BUILD_UTILITIES) # Setup third-party libraries. # Everything in the tree should be able to include files from the # Utilities directory. - if (CMAKE_SYSTEM_NAME STREQUAL "AIX" AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU") + if ((CMAKE_SYSTEM_NAME STREQUAL "AIX" OR CMAKE_SYSTEM_NAME STREQUAL "OS400") AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU") # using -isystem option generate error "template with C linkage" include_directories("${CMake_SOURCE_DIR}/Utilities/std") else() @@ -671,10 +670,6 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE) set(LIBRARY_OUTPUT_PATH "" CACHE INTERNAL "Where to put the libraries for CMake") - # The CMake executables usually do not need any rpath to run in the build or - # install tree. - set(CMAKE_SKIP_RPATH ON CACHE INTERNAL "CMake does not need RPATHs.") - # Load install destinations. include(Source/CMakeInstallDestinations.cmake) @@ -714,19 +709,6 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE) # build the utilities (a macro defined in this file) CMAKE_BUILD_UTILITIES() - # On NetBSD ncurses is required, since curses doesn't have the wsyncup() - # function. ncurses is installed via pkgsrc, so the library is in /usr/pkg/lib, - # which isn't in the default linker search path. So without RPATH ccmake - # doesn't run and the build doesn't succeed since ccmake is executed for - # generating the documentation. - if(BUILD_CursesDialog) - get_filename_component(_CURSES_DIR "${CURSES_LIBRARY}" PATH) - set(CURSES_NEED_RPATH FALSE) - if(NOT "${_CURSES_DIR}" STREQUAL "/lib" AND NOT "${_CURSES_DIR}" STREQUAL "/usr/lib" AND NOT "${_CURSES_DIR}" STREQUAL "/lib64" AND NOT "${_CURSES_DIR}" STREQUAL "/usr/lib64") - set(CURSES_NEED_RPATH TRUE) - endif() - endif() - if(BUILD_QtDialog) if(APPLE) set(CMAKE_BUNDLE_VERSION @@ -739,28 +721,15 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE) set(CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}CMake.app/Contents") endif() - - set(QT_NEED_RPATH FALSE) - if(NOT "${QT_LIBRARY_DIR}" STREQUAL "/lib" AND NOT "${QT_LIBRARY_DIR}" STREQUAL "/usr/lib" AND NOT "${QT_LIBRARY_DIR}" STREQUAL "/lib64" AND NOT "${QT_LIBRARY_DIR}" STREQUAL "/usr/lib64") - set(QT_NEED_RPATH TRUE) - endif() endif() - - # The same might be true on other systems for other libraries. - # Then only enable RPATH if we have are building at least with cmake 2.4, - # since this one has much better RPATH features than cmake 2.2. - # The executables are then built with the RPATH for the libraries outside - # the build tree, which is both the build and the install RPATH. - if (UNIX) - if( CMAKE_USE_SYSTEM_CURL OR CMAKE_USE_SYSTEM_ZLIB - OR CMAKE_USE_SYSTEM_EXPAT OR CURSES_NEED_RPATH OR QT_NEED_RPATH) - set(CMAKE_SKIP_RPATH OFF CACHE INTERNAL "CMake built with RPATH.") - set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE) - set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE) - endif() - endif () - + if(UNIX) + # Install executables with the RPATH set for libraries outside the build tree. + # This is also suitable for binaries in the build tree. Avoid re-link on install. + set(CMAKE_INSTALL_RPATH_USE_LINK_PATH ON CACHE BOOL "Install with RPATH set to find custom-built libraries.") + set(CMAKE_BUILD_WITH_INSTALL_RPATH ON CACHE BOOL "Build with RPATH set to match install-tree RPATH.") + mark_as_advanced(CMAKE_INSTALL_RPATH_USE_LINK_PATH CMAKE_BUILD_WITH_INSTALL_RPATH) + endif() # add the uninstall support configure_file( diff --git a/CTestCustom.cmake.in b/CTestCustom.cmake.in index 823ee3cb7c3..fb8e099a6f0 100644 --- a/CTestCustom.cmake.in +++ b/CTestCustom.cmake.in @@ -49,6 +49,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION "WarningMessagesDialog\\.cxx" "warning.*directory name.*CMake-Xcode.*/bin/.*does not exist.*" "stl_deque.h:1051" + "Tests/CMakeLib/testCTestResourceSpec.cxx:.*warning: missing initializer for member.*cmCTestResourceSpec::.*" # GCC 4.8 disagrees with later compilers on C++11 initializer list conversion "(Lexer|Parser).*warning.*conversion.*may (alter its value|change the sign)" "(Lexer|Parser).*warning.*(statement is unreachable|will never be executed)" "(Lexer|Parser).*warning.*variable.*was set but never used" @@ -71,6 +72,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION "cm(StringCommand|CTestTestHandler)\\.cxx.*warning.*rand.*isn.*t random" # we do not do crypto "cm(StringCommand|CTestTestHandler)\\.cxx.*warning.*srand.*seed choices are.*poor" # we do not do crypto "IPA warning: function.*multiply defined in" + "LICENSE WARNING" # PGI license expiry. Not useful in nightly testing. # Ignore compiler summary warning, assuming prior text has matched some # other warning expression: diff --git a/CompileFlags.cmake b/CompileFlags.cmake index 91f2adffe1c..053259f47c8 100644 --- a/CompileFlags.cmake +++ b/CompileFlags.cmake @@ -54,12 +54,20 @@ if(CMAKE_SYSTEM_PROCESSOR MATCHES "^parisc") endif() # Workaround for TOC Overflow on ppc64 +set(bigTocFlag "") if(CMAKE_SYSTEM_NAME STREQUAL "AIX" AND CMAKE_SYSTEM_PROCESSOR MATCHES "powerpc") - set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-bbigtoc") + set(bigTocFlag "-Wl,-bbigtoc") elseif(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SYSTEM_PROCESSOR MATCHES "ppc64") - set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,--no-multi-toc") + set(bigTocFlag "-Wl,--no-multi-toc") +endif() +if(bigTocFlag) + include(CheckCXXLinkerFlag) + check_cxx_linker_flag(${bigTocFlag} BIG_TOC_FLAG_SUPPORTED) + if(BIG_TOC_FLAG_SUPPORTED) + set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${bigTocFlag}") + endif() endif() if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND diff --git a/Copyright.txt b/Copyright.txt index f2362144a1c..b867d01785a 100644 --- a/Copyright.txt +++ b/Copyright.txt @@ -1,5 +1,5 @@ CMake - Cross Platform Makefile Generator -Copyright 2000-2019 Kitware, Inc. and Contributors +Copyright 2000-2020 Kitware, Inc. and Contributors All rights reserved. Redistribution and use in source and binary forms, with or without @@ -99,6 +99,7 @@ The following individuals and institutions are among the Contributors: * Sebastian Holtermann * Stephen Kelly * Sylvain Joubert +* The Qt Company Ltd. * Thomas Sondergaard * Tobias Hunger * Todd Gamblin diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index aba374261e2..92797480a18 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -68,6 +68,9 @@ The options are: order-only dependencies to ensure the byproducts will be available before their dependents build. + The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other + :prop_sf:`GENERATED` files during ``make clean``. + ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, @@ -112,24 +115,42 @@ The options are: build time. ``DEPENDS`` - Specify files on which the command depends. If any dependency is - an ``OUTPUT`` of another custom command in the same directory - (``CMakeLists.txt`` file) CMake automatically brings the other + Specify files on which the command depends. Each argument is converted + to a dependency as follows: + + 1. If the argument is the name of a target (created by the + :command:`add_custom_target`, :command:`add_executable`, or + :command:`add_library` command) a target-level dependency is + created to make sure the target is built before any target + using this custom command. Additionally, if the target is an + executable or library, a file-level dependency is created to + cause the custom command to re-run whenever the target is + recompiled. + + 2. If the argument is an absolute path, a file-level dependency + is created on that path. + + 3. If the argument is the name of a source file that has been + added to a target or on which a source file property has been set, + a file-level dependency is created on that source file. + + 4. If the argument is a relative path and it exists in the current + source directory, a file-level dependency is created on that + file in the current source directory. + + 5. Otherwise, a file-level dependency is created on that path relative + to the current binary directory. + + If any dependency is an ``OUTPUT`` of another custom command in the same + directory (``CMakeLists.txt`` file), CMake automatically brings the other custom command into the target in which this command is built. A target-level dependency is added if any dependency is listed as ``BYPRODUCTS`` of a target or any of its build events in the same directory to ensure the byproducts will be available. - If ``DEPENDS`` is not specified the command will run whenever + + If ``DEPENDS`` is not specified, the command will run whenever the ``OUTPUT`` is missing; if the command does not actually - create the ``OUTPUT`` then the rule will always run. - If ``DEPENDS`` specifies any target (created by the - :command:`add_custom_target`, :command:`add_executable`, or - :command:`add_library` command) a target-level dependency is - created to make sure the target is built before any target - using this custom command. Additionally, if the target is an - executable or library a file-level dependency is created to - cause the custom command to re-run whenever the target is - recompiled. + create the ``OUTPUT``, the rule will always run. Arguments to ``DEPENDS`` may use :manual:`generator expressions `. diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 2d5f5f08189..56ab414ddb1 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -49,6 +49,9 @@ The options are: order-only dependencies to ensure the byproducts will be available before their dependents build. + The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other + :prop_sf:`GENERATED` files during ``make clean``. + ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 7a3393b4d4f..5c67b2c7068 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -23,6 +23,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. [STOP_TIME ] [RETURN_VALUE ] [CAPTURE_CMAKE_ERROR ] + [REPEAT :] [QUIET] ) @@ -95,6 +96,25 @@ The options are: and then the ``--test-load`` command-line argument to :manual:`ctest(1)`. See also the ``TestLoad`` setting in the :ref:`CTest Test Step`. +``REPEAT :`` + Run tests repeatedly based on the given ```` up to ```` times. + The modes are: + + ``UNTIL_FAIL`` + Require each test to run ```` times without failing in order to pass. + This is useful in finding sporadic failures in test cases. + + ``UNTIL_PASS`` + Allow each test to run up to ```` times in order to pass. + Repeats tests if they fail for any reason. + This is useful in tolerating sporadic failures in test cases. + + ``AFTER_TIMEOUT`` + Allow each test to run up to ```` times in order to pass. + Repeats tests only if they timeout. + This is useful in tolerating sporadic timeouts in test cases + on busy machines. + ``SCHEDULE_RANDOM `` Launch tests in a random order. This may be useful for detecting implicit test dependencies. diff --git a/Help/command/file.rst b/Help/command/file.rst index b186177eb68..df7d8bad922 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -540,7 +540,7 @@ are only traversed if ``FOLLOW_SYMLINKS`` is given or policy By default ``GLOB_RECURSE`` omits directories from result list - setting ``LIST_DIRECTORIES`` to true adds directories to result list. If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to -``OLD`` then ``LIST_DIRECTORIES`` treats symlinks as directories. +``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories. Examples of recursive globbing include:: diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index ae2afb2905d..a01a1042c90 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -47,7 +47,7 @@ of undocumented behavior that may change in future releases. .. code-block:: cmake - foreach(loop_var IN [LISTS []] [ITEMS []]) + foreach( IN [LISTS []] [ITEMS []]) In this variant, ```` is a whitespace or semicolon separated list of list-valued variables. The ``foreach`` @@ -82,3 +82,46 @@ yields -- X=6 -- X=7 -- X=8 + + +.. code-block:: cmake + + foreach(... IN ZIP_LISTS ) + +In this variant, ```` is a whitespace or semicolon +separated list of list-valued variables. The ``foreach`` +command iterates over each list simultaneously setting the +iteration variables as follows: + +- if the only ``loop_var`` given, then it sets a series of + ``loop_var_N`` variables to the current item from the + corresponding list; +- if multiple variable names passed, their count should match + the lists variables count; +- if any of the lists are shorter, the corresponding iteration + variable is not defined for the current iteration. + +.. code-block:: cmake + + list(APPEND English one two three four) + list(APPEND Bahasa satu dua tiga) + + foreach(num IN ZIP_LISTS English Bahasa) + message(STATUS "num_0=${num_0}, num_1=${num_1}") + endforeach() + + foreach(en ba IN ZIP_LISTS English Bahasa) + message(STATUS "en=${en}, ba=${ba}") + endforeach() + +yields +:: + + -- num_0=one, num_1=satu + -- num_0=two, num_1=dua + -- num_0=three, num_1=tiga + -- num_0=four, num_1= + -- en=one, ba=satu + -- en=two, ba=dua + -- en=three, ba=tiga + -- en=four, ba= diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 05e5d79ac6d..3f6f2f9564e 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -91,6 +91,12 @@ just terminate execution of the macro; rather, control is returned from the scope of the macro call. To avoid confusion, it is recommended to avoid :command:`return()` in macros altogether. +Unlike a function, the :variable:`CMAKE_CURRENT_FUNCTION`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` variables are not +set for macro. + .. _`Argument Caveats`: Argument Caveats diff --git a/Help/command/mark_as_advanced.rst b/Help/command/mark_as_advanced.rst index 5712fb4202d..e52e623a7f5 100644 --- a/Help/command/mark_as_advanced.rst +++ b/Help/command/mark_as_advanced.rst @@ -22,3 +22,9 @@ If neither ``FORCE`` nor ``CLEAR`` is specified, new values will be marked as advanced, but if a variable already has an advanced/non-advanced state, it will not be changed. + +.. note:: + + Policy :policy:`CMP0102` affects the behavior of the ``mark_as_advanced`` + call. When set to ``NEW``, variables passed to this command which are not + already in the cache are ignored. See policy :policy:`CMP0102`. diff --git a/Help/command/message.rst b/Help/command/message.rst index c614286c110..6bc0e4cfc65 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([] "message text" ...) + + `Reporting checks`_ + message( "message text" ...) + + +General messages +^^^^^^^^^^^^^^^^ .. code-block:: cmake - message([] "message to display" ...) + message([] "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 ```` keyword determines the type of message: +The optional ```` 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 ` 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 ` ``--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( "message" ...) + +where ```` 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 395145619fa..b6093d3b71f 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__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__INCLUDE_BEFORE`. If the :variable:`CMAKE_PROJECT_INCLUDE` or :variable:`CMAKE_PROJECT__INCLUDE` variables are set, the files diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst index 9271cd56c83..c5401e6ec88 100644 --- a/Help/command/target_compile_features.rst +++ b/Help/command/target_compile_features.rst @@ -8,9 +8,9 @@ Add expected compiler features to a target. target_compile_features( [...]) Specifies compiler features required when compiling a given target. If the -feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES` variable -or :variable:`CMAKE_CXX_COMPILE_FEATURES` variable, -then an error will be reported by CMake. If the use of the feature requires +feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES`, +:variable:`CMAKE_CUDA_COMPILE_FEATURES`, or :variable:`CMAKE_CXX_COMPILE_FEATURES` +variables, then an error will be reported by CMake. If the use of the feature requires an additional compiler flag, such as ``-std=gnu++11``, the flag will be added automatically. diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst index 1e378893348..cede0f25576 100644 --- a/Help/cpack_gen/dmg.rst +++ b/Help/cpack_gen/dmg.rst @@ -54,10 +54,12 @@ on macOS: Directory where license and menu files for different languages are stored. Setting this causes CPack to look for a ``.menu.txt`` and - ``.license.txt`` file for every language defined in - ``CPACK_DMG_SLA_LANGUAGES``. If both this variable and + ``.license.txt`` or ``.license.rtf`` file for every + language defined in ``CPACK_DMG_SLA_LANGUAGES``. If both this variable and ``CPACK_RESOURCE_FILE_LICENSE`` are set, CPack will only look for the menu - files and use the same license file for all languages. + files and use the same license file for all languages. If both + ``.license.txt`` and ``.license.rtf`` exist, the ``.txt`` + file will be used. .. variable:: CPACK_DMG_SLA_LANGUAGES @@ -81,6 +83,13 @@ on macOS: ``.menu.txt`` and ``.license.txt`` in the directory specified by the :variable:`CPACK_DMG_SLA_DIR` variable. +.. variable:: CPACK_DMG__FILE_NAME + + File name when packaging ```` as its own DMG + (``CPACK_COMPONENTS_GROUPING`` set to IGNORE). + + - Default: ``CPACK_PACKAGE_FILE_NAME-`` + .. variable:: CPACK_COMMAND_HDIUTIL Path to the ``hdiutil(1)`` command used to operate on disk image files on diff --git a/Help/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst index feccd3db097..4a9ab99b316 100644 --- a/Help/cpack_gen/ifw.rst +++ b/Help/cpack_gen/ifw.rst @@ -1,43 +1,38 @@ CPack IFW Generator ------------------- -See :module:`CPackIFW` for details on the CPackIFW module. - -.. _QtIFW: http://doc.qt.io/qtinstallerframework/index.html - - Overview ^^^^^^^^ -CPack ``IFW`` generator helps you to create online and offline -binary cross-platform installers with a graphical user interface. - -CPack IFW generator prepares project installation and generates configuration -and meta information for QtIFW_ tools. +This :manual:`cpack generator ` generates +configuration and meta information for the `Qt Installer Framework +`_ (QtIFW). -The QtIFW_ provides a set of tools and utilities to create -installers for the supported desktop Qt platforms: Linux, Microsoft Windows, -and macOS. +QtIFW provides tools and utilities to create installers for +the platforms supported by `Qt `_: Linux, +Microsoft Windows, and macOS. -You should also install QtIFW_ to use CPack ``IFW`` generator. +To make use of this generator, QtIFW should also be installed. +The module :module:`CPackIFW` looks for the location of the +QtIFW command-line utilities. Hints ^^^^^ -Generally, the CPack ``IFW`` generator automatically finds QtIFW_ tools, -but if you don't use a default path for installation of the QtIFW_ tools, +Generally, the CPack ``IFW`` generator automatically finds QtIFW tools, +but if you don't use a default path for installation of the QtIFW tools, the path may be specified in either a CMake or an environment variable: .. variable:: CPACK_IFW_ROOT - An CMake variable which specifies the location of the QtIFW_ tool suite. + An CMake variable which specifies the location of the QtIFW tool suite. The variable will be cached in the ``CPackConfig.cmake`` file and used at CPack runtime. .. variable:: QTIFWDIR - An environment variable which specifies the location of the QtIFW_ tool + An environment variable which specifies the location of the QtIFW tool suite. .. note:: @@ -53,7 +48,7 @@ Internationalization Some variables and command arguments support internationalization via CMake script. This is an optional feature. -Installers created by QtIFW_ tools have built-in support for +Installers created by QtIFW tools have built-in support for internationalization and many phrases are localized to many languages, but this does not apply to the description of the your components and groups that will be distributed. @@ -185,7 +180,7 @@ Package Filename of the generated maintenance tool. The platform-specific executable file extension is appended. - By default used QtIFW_ defaults (``maintenancetool``). + By default used QtIFW defaults (``maintenancetool``). .. variable:: CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR @@ -197,19 +192,19 @@ Package Filename for the configuration of the generated maintenance tool. - By default used QtIFW_ defaults (``maintenancetool.ini``). + By default used QtIFW defaults (``maintenancetool.ini``). .. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS Set to ``ON`` if the installation path can contain non-ASCII characters. - Is ``ON`` for QtIFW_ less 2.0 tools. + Is ``ON`` for QtIFW less 2.0 tools. .. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH Set to ``OFF`` if the installation path cannot contain space characters. - Is ``ON`` for QtIFW_ less 2.0 tools. + Is ``ON`` for QtIFW less 2.0 tools. .. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT @@ -266,14 +261,14 @@ Components Additional prepared repository dirs that will be used to resolve and repack dependent components. This feature available only - since QtIFW_ 3.1. + since QtIFW 3.1. Tools """"" .. variable:: CPACK_IFW_FRAMEWORK_VERSION - The version of used QtIFW_ tools. + The version of used QtIFW tools. .. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index cd2aea682f9..a310e9f363a 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst @@ -128,3 +128,28 @@ 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``. + +.. 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. + +.. variable:: CPACK_NSIS_MUI_HEADERIMAGE + + The image to display on the header of installers pages. diff --git a/Help/cpack_gen/packagemaker.rst b/Help/cpack_gen/packagemaker.rst index e9464b749a9..c2a450e6cb0 100644 --- a/Help/cpack_gen/packagemaker.rst +++ b/Help/cpack_gen/packagemaker.rst @@ -3,6 +3,11 @@ CPack PackageMaker Generator PackageMaker CPack generator (macOS). +.. deprecated:: 3.17 + + Xcode no longer distributes the PackageMaker tools. + This CPack generator will be removed in a future version of CPack. + Variables specific to CPack PackageMaker generator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -15,9 +20,60 @@ macOS using PackageMaker: compatible with. Different versions of macOS support different features. For example, CPack can only build component-based installers for macOS 10.4 or newer, and can only build installers that download - component son-the-fly for macOS 10.5 or newer. If left blank, this value + components on-the-fly for macOS 10.5 or newer. If left blank, this value will be set to the minimum version of macOS that supports the requested features. Set this variable to some value (e.g., 10.4) only if you want to guarantee that your installer will work on that version of macOS, and don't mind missing extra features available in the installer shipping with later versions of macOS. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND + + Adds a background to Distribtion XML if specified. The value contains the + path to image in ``Resources`` directory. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT + + Adds an ``alignment`` attribute to the background in Distribution XML. + Refer to Apple documentation for valid values. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_SCALING + + Adds a ``scaling`` attribute to the background in Distribution XML. + Refer to Apple documentation for valid values. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE + + Adds a ``mime-type`` attribute to the background in Distribution XML. + The option contains MIME type of an image. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_UTI + + Adds an ``uti`` attribute to the background in Distribution XML. + The option contains UTI type of an image. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA + + Adds a background for the Dark Aqua theme to Distribution XML if + specified. The value contains the path to image in ``Resources`` + directory. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_ALIGNMENT + + Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT` option, + but for the dark theme. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_SCALING + + Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_SCALING` option, + but for the dark theme. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_MIME_TYPE + + Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE` option, + but for the dark theme. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_UTI + + Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_UTI` option, + but for the dark theme. diff --git a/Help/cpack_gen/productbuild.rst b/Help/cpack_gen/productbuild.rst index d22fcd48a52..82b79aeacfc 100644 --- a/Help/cpack_gen/productbuild.rst +++ b/Help/cpack_gen/productbuild.rst @@ -58,7 +58,6 @@ macOS using ProductBuild: component name. No ``postinstall`` script is added if this variable is not defined for a given component. - .. variable:: CPACK_PRODUCTBUILD_RESOURCES_DIR If specified the productbuild generator copies files from this directory @@ -66,3 +65,54 @@ macOS using ProductBuild: before the :variable:`CPACK_RESOURCE_FILE_WELCOME`, :variable:`CPACK_RESOURCE_FILE_README`, and :variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND + + Adds a background to Distribtion XML if specified. The value contains the + path to image in ``Resources`` directory. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT + + Adds an ``alignment`` attribute to the background in Distribution XML. + Refer to Apple documentation for valid values. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_SCALING + + Adds a ``scaling`` attribute to the background in Distribution XML. + Refer to Apple documentation for valid values. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE + + Adds a ``mime-type`` attribute to the background in Distribution XML. + The option contains MIME type of an image. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_UTI + + Adds an ``uti`` attribute to the background in Distribution XML. + The option contains UTI type of an image. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA + + Adds a background for the Dark Aqua theme to Distribution XML if + specified. The value contains the path to image in ``Resources`` + directory. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_ALIGNMENT + + Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT` option, + but for the dark theme. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_SCALING + + Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_SCALING` option, + but for the dark theme. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_MIME_TYPE + + Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE` option, + but for the dark theme. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_UTI + + Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_UTI` option, + but for the dark theme. diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 44e22734774..a1c1a6fada0 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -14,6 +14,11 @@ Review a Merge Request The `CMake Review Process`_ requires a maintainer to issue the ``Do: merge`` command to integrate a merge request. Please check at least the following: +* If the MR source branch (or part of it) should be backported + to the ``release`` branch (and is already based on a commit + contained in the ``release`` branch), add a ``Backport: release`` or + ``Backport: release:`` trailing line to the MR description. + * If the MR source branch is not named well for the change it makes (e.g. it is just ``master`` or the patch changed during review), add a ``Topic-rename: `` trailing line to the MR description @@ -38,9 +43,10 @@ command to integrate a merge request. Please check at least the following: of various nightly builders.) * Ensure that the MR targets the ``master`` branch. A MR intended for - the ``release`` branch should be based on ``release`` but still merged - to ``master`` first (via ``Do: merge``). A maintainer may then merge - the MR topic to ``release`` manually. + the ``release`` branch should be based on ``release`` but still target + ``master``. Use the above-mentioned ``Backport: release`` line to tell + ``Do: merge`` to merge to both. If a MR is merged without the backport + line, a maintainer may still merge the MR topic to ``release`` manually. Maintain Current Release ======================== @@ -51,6 +57,12 @@ using a local branch named ``release-$ver``, where ``$ver`` is the version number of the current release in the form ``$major.$minor``. It is always merged into ``master`` before publishing. +To merge an open MR to the ``release`` branch, edit its description to +use the ``Backport: release`` line mentioned above and then ``Do: merge`` +normally. To update the ``release`` branch manually (e.g. to merge a +``$topic`` branch that was merged without the backport line), use the +following procedure. + Before merging a ``$topic`` branch into ``release``, verify that the ``$topic`` branch has already been merged to ``master`` via the usual ``Do: merge`` process. Then, to merge the ``$topic`` branch into diff --git a/Help/dev/review.rst b/Help/dev/review.rst index cbde6feead5..8ec41d29c6e 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -53,6 +53,10 @@ in GitLab to track the state of a MR: to a period of inactivity. See the `Expire`_ step. Use this label after closing a MR for this reason. +* ``workflow:external-discussion`` indicates that the MR has been closed + pending discussion elsewhere. See the `External Discussion`_ step. + Use this label after closing a MR for this reason. + The workflow status labels are intended to be mutually exclusive, so please remove any existing workflow label when adding one. @@ -429,6 +433,21 @@ Additionally, ``Do: merge`` extracts configuration from trailing lines in the MR description (the following have no effect if used in a MR comment instead): +* ``Backport: release[:]``: merge the topic branch into + the ``release`` branch to backport the change. This is allowed + only if the topic branch is based on a commit in ``release`` already. + If only part of the topic branch should be backported, specify it as + ``:``. The ```` may use `git rev-parse`_ + syntax to reference commits relative to the topic ``HEAD``. + See additional `backport instructions`_ for details. + For example: + + ``Backport: release`` + Merge the topic branch head into both ``release`` and ``master``. + ``Backport: release:HEAD~1^2`` + Merge the topic branch head's parent's second parent commit into + the ``release`` branch. Merge the topic branch head to ``master``. + * ``Topic-rename: ``: substitute ```` for the name of the MR topic branch in the constructed merge commit message. It is also used in merge commits constructed by ``Do: stage``. @@ -436,6 +455,8 @@ comment instead): rename set in the MR description. .. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members +.. _`backport instructions`: https://gitlab.kitware.com/utils/git-workflow/wikis/Backport-topics +.. _`git rev-parse`: https://git-scm.com/docs/git-rev-parse Close ----- diff --git a/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst new file mode 100644 index 00000000000..e9e0810650d --- /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/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst new file mode 100644 index 00000000000..4f91e9a42dc --- /dev/null +++ b/Help/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -0,0 +1,10 @@ +CMAKE__COMPILER_LAUNCHER +------------------------------ + +.. include:: ENV_VAR.txt + +Default compiler launcher to use for the specified language. Will only be used +by CMake to initialize the variable on the first configuration. Afterwards, it +is available through the cache setting of the variable of the same name. For +any configuration run (including the first), the environment variable will be +ignored if the :variable:`CMAKE__COMPILER_LAUNCHER` variable is defined. diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst new file mode 100644 index 00000000000..1f68535ff81 --- /dev/null +++ b/Help/generator/Ninja Multi-Config.rst @@ -0,0 +1,121 @@ +Ninja Multi-Config +------------------ + +Generates multiple ``build-.ninja`` files. + +This generator is very much like the :generator:`Ninja` generator, but with +some key differences. Only these differences will be discussed in this +document. + +Unlike the :generator:`Ninja` generator, ``Ninja Multi-Config`` generates +multiple configurations at once with :variable:`CMAKE_CONFIGURATION_TYPES` +instead of only one configuration with :variable:`CMAKE_BUILD_TYPE`. One +``build-.ninja`` file will be generated for each of these +configurations (with ```` being the configuration name.) These files +are intended to be run with ``ninja -f build-.ninja``. A +``build.ninja`` file is also generated, using the configuration from either +:variable:`CMAKE_DEFAULT_BUILD_TYPE` or the first item from +:variable:`CMAKE_CONFIGURATION_TYPES`. + +``cmake --build . --config `` will always use ``build-.ninja`` +to build. If no ``--config`` argument is specified, ``cmake --build .`` will +default to ``build-Debug.ninja``, unless a ``build.ninja`` is generated (see +below), in which case that will be used instead. + +Each ``build-.ninja`` file contains ```` targets as well as +``:`` targets, where ```` is the same as the +configuration specified in ``build-.ninja`` Additionally, if +cross-config mode is enabled, ``build-.ninja`` may contain +``:`` targets, where ```` is a cross-config, +as well as ``:all``, which builds the target in all cross-configs. See +below for how to enable cross-config mode. + +The ``Ninja Multi-Config`` generator recognizes the following variables: + +:variable:`CMAKE_CONFIGURATION_TYPES` + Specifies the total set of configurations to build. See the variable's + documentation for more information. + +:variable:`CMAKE_CROSS_CONFIGS` + Specifies a :ref:`semicolon-separated list ` of + configurations available from all ``build-.ninja`` files. + This variable activates cross-config mode. + Targets from each config specified in this variable can be built from any + ``build-.ninja`` file. Custom commands will use the configuration + native to ``build-.ninja``. If it is set to ``all``, all + configurations from :variable:`CMAKE_CONFIGURATION_TYPES` are cross-configs. + If it is not specified, or empty, each ``build-.ninja`` file will + only contain build rules for its own configuration. + + The value of this variable must be a subset of + :variable:`CMAKE_CONFIGURATION_TYPES`. + +:variable:`CMAKE_DEFAULT_BUILD_TYPE` + Specifies the configuration to use by default in a ``build.ninja`` file. If + this variable is specified, ``build.ninja`` uses build rules from + ``build-.ninja`` by default. All custom commands are executed with + this configuration. If the variable is not specified, the first item from + :variable:`CMAKE_CONFIGURATION_TYPES` is used instead. + + The value of this variable must be one of the items from + :variable:`CMAKE_CONFIGURATION_TYPES`. + +:variable:`CMAKE_DEFAULT_CONFIGS` + Specifies a :ref:`semicolon-separated list ` of + configurations to build for a target in ``build.ninja`` + if no ``:`` suffix is specified. If it is set to ``all``, all + configurations from :variable:`CMAKE_CROSS_CONFIGS` are used. If + it is not specified, it defaults to + :variable:`CMAKE_DEFAULT_BUILD_TYPE`. + + For example, if you set + :variable:`CMAKE_DEFAULT_BUILD_TYPE` to ``Release``, but + set :variable:`CMAKE_DEFAULT_CONFIGS` to ``Debug`` or ``all``, + all ```` aliases in ``build.ninja`` will resolve to + ``:Debug`` or ``:all``, but custom commands will still use + the ``Release`` configuration. + + The value of this variable must be a subset of + :variable:`CMAKE_CROSS_CONFIGS` or be the same as + :variable:`CMAKE_DEFAULT_BUILD_TYPE`. It must not be + specified if :variable:`CMAKE_DEFAULT_BUILD_TYPE` or + :variable:`CMAKE_CROSS_CONFIGS` is not used. + +Consider the following example: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.16) + project(MultiConfigNinja C) + + add_executable(generator generator.c) + add_custom_command(OUTPUT generated.c COMMAND generator generated.c) + add_library(generated ${CMAKE_BINARY_DIR}/generated.c) + +Now assume you configure the project with ``Ninja Multi-Config`` and run one of +the following commands: + +.. code-block:: shell + + ninja -f build-Debug.ninja generated + # OR + cmake --build . --config Debug --target generated + +This would build the ``Debug`` configuration of ``generator``, which would be +used to generate ``generated.c``, which would be used to build the ``Debug`` +configuration of ``generated``. + +But if :variable:`CMAKE_CROSS_CONFIGS` is set to ``all``, and you run the +following instead: + +.. code-block:: shell + + ninja -f build-Release.ninja generated:Debug + # OR + cmake --build . --config Release --target generated:Debug + +This would build the ``Release`` configuration of ``generator``, which would be +used to generate ``generated.c``, which would be used to build the ``Debug`` +configuration of ``generated``. This is useful for running a release-optimized +version of a generator utility while still building the debug version of the +targets built with the generated code. diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst index c75d2c4cf3f..275055d73aa 100644 --- a/Help/generator/Ninja.rst +++ b/Help/generator/Ninja.rst @@ -1,7 +1,7 @@ Ninja ----- -Generates build.ninja files. +Generates ``build.ninja`` files. A ``build.ninja`` file is generated into the build tree. Use the ninja program to build the project through the ``all`` target and install the @@ -38,3 +38,9 @@ features have not been integrated into upstream Ninja. Kitware maintains a branch of Ninja with the required features on `github.com/Kitware/ninja`_. .. _`github.com/Kitware/ninja`: https://github.com/Kitware/ninja/tree/features-for-fortran#readme + +See Also +^^^^^^^^ + +The :generator:`Ninja Multi-Config` generator is similar to the ``Ninja`` +generator, but generates multiple configurations at once. diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt index eca79d9df7b..4d8a3ada877 100644 --- a/Help/guide/tutorial/Complete/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/CMakeLists.txt @@ -3,6 +3,8 @@ cmake_minimum_required(VERSION 3.15) # set the project name and version project(Tutorial VERSION 1.0) +set(CMAKE_DEBUG_POSTFIX d) + add_library(tutorial_compiler_flags INTERFACE) target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) @@ -37,6 +39,8 @@ add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) +set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX}) + target_link_libraries(Tutorial PUBLIC MathFunctions) # add the binary tree to the search path for include files diff --git a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt index dfa84c94137..c911625b801 100644 --- a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt @@ -17,7 +17,7 @@ if(USE_MYMATH) # first we add the executable that generates the table add_executable(MakeTable MakeTable.cxx) - target_link_libraries(MakeTable tutorial_compiler_flags) + target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) # add the command to generate the source code add_custom_command( diff --git a/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake b/Help/guide/tutorial/Complete/MultiCPackConfig.cmake similarity index 99% rename from Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake rename to Help/guide/tutorial/Complete/MultiCPackConfig.cmake index 403b633e114..c2583dfff54 100644 --- a/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake +++ b/Help/guide/tutorial/Complete/MultiCPackConfig.cmake @@ -1,4 +1,3 @@ - include("release/CPackConfig.cmake") set(CPACK_INSTALL_CMAKE_PROJECTS diff --git a/Help/guide/tutorial/Complete/tutorial.cxx b/Help/guide/tutorial/Complete/tutorial.cxx index 586d183a7b7..a4f44d54fc2 100644 --- a/Help/guide/tutorial/Complete/tutorial.cxx +++ b/Help/guide/tutorial/Complete/tutorial.cxx @@ -1,6 +1,5 @@ // A simple program that computes the square root of a number #include -#include #include #include "MathFunctions.h" @@ -9,6 +8,7 @@ int main(int argc, char* argv[]) { if (argc < 2) { + // report version std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." << Tutorial_VERSION_MINOR << std::endl; std::cout << "Usage: " << argv[0] << " number" << std::endl; @@ -18,8 +18,8 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // calculate square root const double outputValue = mathfunctions::sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; return 0; diff --git a/Help/guide/tutorial/Consumer/CMakeLists.txt b/Help/guide/tutorial/Consumer/CMakeLists.txt deleted file mode 100644 index a0e4598bc22..00000000000 --- a/Help/guide/tutorial/Consumer/CMakeLists.txt +++ /dev/null @@ -1,51 +0,0 @@ -cmake_minimum_required(VERSION 3.10) - -if(NOT DEFINED CMAKE_CXX_STANDARD) - set(CMAKE_CXX_STANDARD 11) - set(CMAKE_CXX_STANDARD_REQUIRED True) -endif() - - -function(find_external_dependency name) - set(${name}_ROOT "" CACHE PATH "Root directory to find ${name}") - mark_as_advanced(${name}_DIR) - find_package(${name} PATHS ${${name}_ROOT} REQUIRED) -endfunction() - - -project(Consumer) - -find_external_dependency(MathFunctions) - -add_library(consumer consumer.cxx) -target_link_libraries(consumer PUBLIC MathFunctions) - -# install the consumer library -install(TARGETS consumer DESTINATION bin EXPORT ConsumerTargets) - -# install the configuration targets -install(EXPORT ConsumerTargets - FILE ConsumerTargets.cmake - DESTINATION lib/cmake/Consumer -) - -include(CMakePackageConfigHelpers) -# generate the config file that is includes the exports -configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in - "${CMAKE_CURRENT_BINARY_DIR}/ConsumerConfig.cmake" - INSTALL_DESTINATION "lib/cmake/example" - NO_SET_AND_CHECK_MACRO - NO_CHECK_REQUIRED_COMPONENTS_MACRO - ) - -# install the configuration file -install(FILES - ${CMAKE_CURRENT_BINARY_DIR}/ConsumerConfig.cmake - DESTINATION lib/cmake/Consumer - ) - -# generate the export targets for the build tree -# needs to be after the install(TARGETS ) command -export(EXPORT ConsumerTargets - FILE "${CMAKE_CURRENT_BINARY_DIR}/ConsumerTargets.cmake" -) diff --git a/Help/guide/tutorial/Consumer/Config.cmake.in b/Help/guide/tutorial/Consumer/Config.cmake.in deleted file mode 100644 index 0b3f1e4ef04..00000000000 --- a/Help/guide/tutorial/Consumer/Config.cmake.in +++ /dev/null @@ -1,14 +0,0 @@ - -@PACKAGE_INIT@ - -include(CMakeFindDependencyMacro) - -function(find_external_dependency name) - set(${name}_ROOT "" CACHE PATH "Root directory to find ${name}") - mark_as_advanced(${name}_DIR) - find_dependency(${name} PATHS ${${name}_ROOT} REQUIRED) -endfunction() - -find_external_dependency(MathFunctions) - -include ( "${CMAKE_CURRENT_LIST_DIR}/ConsumerTargets.cmake" ) diff --git a/Help/guide/tutorial/Consumer/consumer.cxx b/Help/guide/tutorial/Consumer/consumer.cxx deleted file mode 100644 index ae7877b5ab3..00000000000 --- a/Help/guide/tutorial/Consumer/consumer.cxx +++ /dev/null @@ -1,11 +0,0 @@ -// A simple function that computes the square root of a number -#include -#include -#include - -#include "MathFunctions.h" - -double string_square_root(std::string const& value) -{ - return mathfunctions::sqrt(std::stod(value)); -} diff --git a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt index e6cb8bacaf8..32f5e084ada 100644 --- a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt @@ -15,7 +15,7 @@ if(USE_MYMATH) # first we add the executable that generates the table add_executable(MakeTable MakeTable.cxx) - target_link_libraries(MakeTable tutorial_compiler_flags) + target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) # add the command to generate the source code add_custom_command( diff --git a/Help/guide/tutorial/MultiPackage/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt similarity index 85% rename from Help/guide/tutorial/MultiPackage/CMakeLists.txt rename to Help/guide/tutorial/Step12/CMakeLists.txt index 01d417ad4f1..eca79d9df7b 100644 --- a/Help/guide/tutorial/MultiPackage/CMakeLists.txt +++ b/Help/guide/tutorial/Step12/CMakeLists.txt @@ -1,11 +1,19 @@ -cmake_minimum_required(VERSION 3.10) +cmake_minimum_required(VERSION 3.15) # set the project name and version project(Tutorial VERSION 1.0) -set(CMAKE_CXX_STANDARD 11) -set(CMAKE_CXX_STANDARD_REQUIRED True) +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$") +set(msvc_cxx "$") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$>" + "$<${msvc_cxx}:$>" +) # control where the static and shared libraries are built so that on windows # we don't need to tinker with the path to run the executable diff --git a/Help/guide/tutorial/Step12/CTestConfig.cmake b/Help/guide/tutorial/Step12/CTestConfig.cmake new file mode 100644 index 00000000000..73efdb1f6e0 --- /dev/null +++ b/Help/guide/tutorial/Step12/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/MultiPackage/Config.cmake.in b/Help/guide/tutorial/Step12/Config.cmake.in similarity index 100% rename from Help/guide/tutorial/MultiPackage/Config.cmake.in rename to Help/guide/tutorial/Step12/Config.cmake.in diff --git a/Help/guide/tutorial/MultiPackage/License.txt b/Help/guide/tutorial/Step12/License.txt similarity index 100% rename from Help/guide/tutorial/MultiPackage/License.txt rename to Help/guide/tutorial/Step12/License.txt diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt similarity index 87% rename from Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt rename to Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt index a2df2a732b3..720ee64376b 100644 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt @@ -17,6 +17,7 @@ if(USE_MYMATH) # first we add the executable that generates the table add_executable(MakeTable MakeTable.cxx) + target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) # add the command to generate the source code add_custom_command( @@ -41,19 +42,18 @@ if(USE_MYMATH) POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} ) + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) target_link_libraries(MathFunctions PRIVATE SqrtLibrary) endif() +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) + # define the symbol stating we are using the declspec(dllexport) when # building on windows target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") -# setup the version numbering -set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0") -set_property(TARGET MathFunctions PROPERTY SOVERSION "1") - # install rules -install(TARGETS MathFunctions +install(TARGETS MathFunctions tutorial_compiler_flags DESTINATION lib EXPORT MathFunctionsTargets) install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx similarity index 100% rename from Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx rename to Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx similarity index 100% rename from Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx rename to Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h similarity index 100% rename from Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h rename to Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx similarity index 90% rename from Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx rename to Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx index 5e622beb595..8153f18bed9 100644 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx @@ -17,11 +17,10 @@ double mysqrt(double x) // use the table to help find an initial value double result = x; if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; result = sqrtTable[static_cast(x)]; } - // if we have both log and exp then use them - // do ten iterations for (int i = 0; i < 10; ++i) { if (result <= 0) { diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h similarity index 100% rename from Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h rename to Help/guide/tutorial/Step12/MathFunctions/mysqrt.h diff --git a/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in b/Help/guide/tutorial/Step12/TutorialConfig.h.in similarity index 68% rename from Help/guide/tutorial/MultiPackage/TutorialConfig.h.in rename to Help/guide/tutorial/Step12/TutorialConfig.h.in index 8cd2fc9c633..7e4d7fa1fa0 100644 --- a/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step12/TutorialConfig.h.in @@ -1,3 +1,3 @@ -// the configured version number +// the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/MultiPackage/tutorial.cxx b/Help/guide/tutorial/Step12/tutorial.cxx similarity index 90% rename from Help/guide/tutorial/MultiPackage/tutorial.cxx rename to Help/guide/tutorial/Step12/tutorial.cxx index f97805b1ce6..a4f44d54fc2 100644 --- a/Help/guide/tutorial/MultiPackage/tutorial.cxx +++ b/Help/guide/tutorial/Step12/tutorial.cxx @@ -8,6 +8,7 @@ int main(int argc, char* argv[]) { if (argc < 2) { + // report version std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." << Tutorial_VERSION_MINOR << std::endl; std::cout << "Usage: " << argv[0] << " number" << std::endl; @@ -15,7 +16,7 @@ int main(int argc, char* argv[]) } // convert input to double - double inputValue = std::stod(argv[1]); + const double inputValue = std::stod(argv[1]); const double outputValue = mathfunctions::sqrt(inputValue); diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index d74d16047b8..a844cbf8433 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -45,7 +45,8 @@ 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.txt`` provides more flexibility. -First, modify the ``CMakeLists.txt`` file to set the version number. +First, modify the ``CMakeLists.txt`` file to use the :command:`project` command +to set the project name and version number. .. literalinclude:: Step2/CMakeLists.txt :language: cmake @@ -102,9 +103,10 @@ 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.txt`` file to 11 -and ``CMAKE_CXX_STANDARD_REQUIRED`` to True: +in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this +tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the +``CMakeLists.txt`` file to 11 and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to +True: .. literalinclude:: Step2/CMakeLists.txt :language: cmake @@ -113,7 +115,8 @@ and ``CMAKE_CXX_STANDARD_REQUIRED`` to True: Build and Test -------------- -Run **cmake** or **cmake-gui** to configure the project and then build it +Run the :manual:`cmake ` executable or the +:manual:`cmake-gui ` to configure the project and then build it with your chosen build tool. For example, from the command line we could navigate to the @@ -156,11 +159,11 @@ 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.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: +To make use of the new library we will add an :command:`add_subdirectory` +call in the 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 @@ -180,7 +183,7 @@ of the top-level ``CMakeLists.txt`` 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 +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.txt`` file. @@ -189,10 +192,11 @@ occurrence. The first step is to add an option to the top-level :start-after: # should we use our own math functions :end-before: # add the MathFunctions library -This option will be displayed in the CMake GUI and ccmake with a default -value of ON that can be changed by the user. This setting will be stored in -the cache so that the user does not need to set the value each time they run -CMake on a build directory. +This option will be displayed in the :manual:`cmake-gui ` and +:manual:`ccmake ` +with a default value of ON that can be changed by the user. This setting will +be stored in 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.txt`` @@ -234,11 +238,13 @@ Since the source code now requires ``USE_MYMATH`` we can add it to **Exercise**: Why is it important that we configure ``TutorialConfig.h.in`` after the option for ``USE_MYMATH``? What would happen if we inverted the two? -Run **cmake** or **cmake-gui** to configure the project and then build it +Run the :manual:`cmake ` executable or the +:manual:`cmake-gui ` to configure the project and then build it with your chosen build tool. Then run the built Tutorial executable. -Use ccmake or the CMake GUI to update the value of ``USE_MYMATH``. Rebuild and -run the tutorial again. Which function gives better results, sqrt or mysqrt? +Use the :manual:`ccmake ` executable or the :manual:`cmake-gui ` +to update the value of ``USE_MYMATH``. Rebuild and run the tutorial again. +Which function gives better results, sqrt or mysqrt? Adding Usage Requirements for Library (Step 3) ============================================== @@ -248,19 +254,20 @@ link and include line while also giving more control over the transitive property of targets inside CMake. The primary commands that leverage usage requirements are: - - ``target_compile_definitions`` - - ``target_compile_options`` - - ``target_include_directories`` - - ``target_link_libraries`` + - :command:`target_compile_definitions` + - :command:`target_compile_options` + - :command:`target_include_directories` + - :command:`target_link_libraries` Let's refactor our code from `Adding a Library (Step 2)`_ to use the modern CMake approach of usage requirements. We first state that anybody linking to MathFunctions needs to include the current source directory, while -MathFunctions itself doesn't. So this can become an ``INTERFACE`` usage +MathFunctions itself doesn't. So this can become an ``INTERFACE`` usage requirement. Remember ``INTERFACE`` means things that consumers require but the producer -doesn't. Add the following lines to the end of ``MathFunctions/CMakeLists.txt``: +doesn't. Add the following lines to the end of +``MathFunctions/CMakeLists.txt``: .. literalinclude:: Step4/MathFunctions/CMakeLists.txt :language: cmake @@ -281,9 +288,10 @@ And here: :language: cmake :start-after: # so that we will find TutorialConfig.h -Once this is done, run **cmake** or **cmake-gui** to configure the project -and then build it with your chosen build tool or by using ``cmake --build .`` -from the build directory. +Once this is done, run the :manual:`cmake ` executable or the +:manual:`cmake-gui ` to configure the project and then build it +with your chosen build tool or by using ``cmake --build .`` from the build +directory. Installing and Testing (Step 4) =============================== @@ -312,16 +320,17 @@ And to the end of the top-level ``CMakeLists.txt`` we add: That is all that is needed to create a basic local install of the tutorial. -Run **cmake** or **cmake-gui** to configure the project and then build it -with your chosen build tool. Run the install step by typing -``cmake --install .`` (introduced in 3.15, older versions of CMake must use -``make install``) from the command line, or build the ``INSTALL`` target from -an IDE. This will install the appropriate header files, libraries, and -executables. - -The CMake variable ``CMAKE_INSTALL_PREFIX`` is used to determine the root of -where the files will be installed. If using ``cmake --install`` a custom -installation directory can be given via ``--prefix`` argument. For +Run the :manual:`cmake ` executable or the +:manual:`cmake-gui ` to configure the project and then build it +with your chosen build tool. Run the install step by using the ``install`` +option of the :manual:`cmake ` command (introduced in 3.15, older +versions of CMake must use ``make install``) from the command line, or build +the ``INSTALL`` target from an IDE. This will install the appropriate header +files, libraries, and executables. + +The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the +root of where the files will be installed. If using ``cmake --install`` a +custom installation directory can be given via the ``--prefix`` argument. For multi-configuration tools, use the ``--config`` argument to specify the configuration. @@ -339,25 +348,25 @@ the application is working correctly. :start-after: # enable testing The first test simply verifies that the application runs, does not segfault or -otherwise crash, and has a zero return value. This is the basic form of a CTest -test. +otherwise crash, and has a zero return value. This is the basic form of a +CTest 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 usage message is printed when an incorrect number of -arguments are provided. +The next test makes use of the :prop_test:`PASS_REGULAR_EXPRESSION` test +property to verify that the output of the test contains certain strings. In +this case, 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 verifies that the computed square root is correct for given input. For each invocation of ``do_test``, another test is added to the project with a name, input, and expected results based on the passed arguments. -Rebuild the application and then cd to the binary directory and run -``ctest -N`` and ``ctest -VV``. For multi-config generators (e.g. Visual -Studio), the configuration type must be specified. To run tests in Debug mode, -for example, use ``ctest -C Debug -VV`` from the build directory (not the -Debug subdirectory!). Alternatively, build the ``RUN_TESTS`` target from the -IDE. +Rebuild the application and then cd to the binary directory and run the +:manual:`ctest ` executable: ``ctest -N`` and ``ctest -VV``. For +multi-config generators (e.g. Visual Studio), the configuration type must be +specified. To run tests in Debug mode, for example, use ``ctest -C Debug -VV`` +from the build directory (not the Debug subdirectory!). Alternatively, build +the ``RUN_TESTS`` target from the IDE. Adding System Introspection (Step 5) ==================================== @@ -370,7 +379,7 @@ 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`` module in the top-level +these functions using the :module:`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. @@ -388,22 +397,29 @@ from ``mysqrt.cxx``: #cmakedefine HAVE_LOG #cmakedefine HAVE_EXP -Modify ``mysqrt.cxx`` to include cmath. Next, in that same file in the -``mysqrt`` function we can provide an alternate implementation based on -``log`` and ``exp`` if they are available on the system using the following -code (don't forget the ``#endif`` before returning the result!): +If ``log`` and ``exp`` are available on the system, then we will use them to +compute the square root in the ``mysqrt`` function. Add the following code to +the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the +``#endif`` before returning the result!): .. literalinclude:: Step6/MathFunctions/mysqrt.cxx :language: c++ :start-after: // if we have both log and exp then use them :end-before: // do ten iterations -Run **cmake** or **cmake-gui** to configure the project and then build it +We will also need to modify ``mysqrt.cxx`` to include ``cmath``. + +.. literalinclude:: Step6/MathFunctions/mysqrt.cxx + :language: c++ + :end-before: #include + +Run the :manual:`cmake ` executable or the +:manual:`cmake-gui ` to configure the project and then build it with your chosen build tool and run the Tutorial executable. 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``. +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.txt`` so ``mysqrt.cxx`` knows where this file is located: @@ -415,10 +431,10 @@ knows where this file is located: PRIVATE ${CMAKE_BINARY_DIR} ) -After making this update, go ahead and build the project again and run the built -Tutorial executable. If ``log`` and ``exp`` are still not being used, open the -generated ``TutorialConfig.h`` file from the build directory. Maybe they aren't -available on the current system? +After making this update, go ahead and build the project again and run the +built Tutorial executable. If ``log`` and ``exp`` are still not being used, +open the generated ``TutorialConfig.h`` file from the build directory. Maybe +they aren't available on the current system? Which function gives better results now, sqrt or mysqrt? @@ -427,7 +443,7 @@ Specify Compile Definition Is there a better place for us to save the ``HAVE_LOG`` and ``HAVE_EXP`` values other than in ``TutorialConfig.h``? Let's try to use -``target_compile_definitions``. +:command:`target_compile_definitions`. First, remove the defines from ``TutorialConfig.h.in``. We no longer need to include ``TutorialConfig.h`` from ``mysqrt.cxx`` or the extra include in @@ -460,8 +476,8 @@ First, let's remove the check for the ``log`` and ``exp`` functions in ``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove :code:`#include `. -In the ``MathFunctions`` subdirectory, a new source file named ``MakeTable.cxx`` -has been provided to generate the table. +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. @@ -510,7 +526,8 @@ Now let's use the generated table. First, modify ``mysqrt.cxx`` to include :language: c++ :start-after: // a hack square root calculation using simple operations -Run **cmake** or **cmake-gui** to configure the project and then build it +Run the :manual:`cmake ` executable or the +:manual:`cmake-gui ` to configure the project and then build it with your chosen build tool. When this project is built it will first build the ``MakeTable`` executable. @@ -530,26 +547,28 @@ previously in `Installing and Testing (Step 4)`_ , where we were installing the binaries that we had built from the source code. In this example we will be building installation packages that support binary installations and package management features. To accomplish this we will use -CPack to create platform specific installers. Specifically we need to add -a few lines to the bottom of our top-level ``CMakeLists.txt`` file. +CPack to create platform specific installers. Specifically we need to add a +few lines to the bottom of our top-level ``CMakeLists.txt`` file. .. literalinclude:: Step8/CMakeLists.txt :language: cmake :start-after: # setup installer That is all there is to it. We start by including -``InstallRequiredSystemLibraries``. This module will include any runtime -libraries that are needed by the project for the current platform. Next we -set some CPack variables to where we have stored the license and version +:module:`InstallRequiredSystemLibraries`. This module will include any runtime +libraries that are needed by the project for the current platform. Next we set +some CPack variables to where we have stored the license and version information for this project. The version information was set earlier in this tutorial and the ``license.txt`` has been included in the top-level source directory for this step. -Finally we include the CPack module which will use these variables and some -other properties of the current system to setup an installer. +Finally we include the :module:`CPack module ` which will use these +variables and some other properties of the current system to setup an +installer. -The next step is to build the project in the usual manner and then run -CPack on it. To build a binary distribution, from the binary directory run: +The next step is to build the project in the usual manner and then run the +:manual:`cpack ` executable. To build a binary distribution, from the +binary directory run: .. code-block:: console @@ -571,16 +590,17 @@ To create a source distribution you would type: Alternatively, run ``make package`` or right click the ``Package`` target and ``Build Project`` from an IDE. -Run the installer found in the binary directory. Then run the -installed executable and verify that it works. +Run the installer found in the binary directory. Then run the installed +executable and verify that it works. Adding Support for a Dashboard (Step 8) ======================================= -Adding support for submitting our test results to a dashboard is very easy. We +Adding support for submitting our test results to a dashboard is simple. We already defined a number of tests for our project in `Testing Support`_. Now we just have to run those tests and submit them to a dashboard. To include support -for dashboards we include the CTest module in our top-level ``CMakeLists.txt``. +for dashboards we include the :module:`CTest` module in our top-level +``CMakeLists.txt``. Replace: @@ -596,8 +616,8 @@ With: # enable dashboard scripting include(CTest) -The CTest module will automatically call ``enable_testing()``, so -we can remove it from our CMake files. +The :module:`CTest` module will automatically call ``enable_testing()``, so we +can remove it from our CMake files. We will also need to create a ``CTestConfig.cmake`` file in the top-level directory where we can specify the name of the project and where to submit the @@ -606,9 +626,11 @@ dashboard. .. literalinclude:: Step9/CTestConfig.cmake :language: cmake -CTest will read in this file when it runs. To create a simple dashboard you can -run **cmake** or **cmake-gui** to configure the project, but do not build it -yet. Instead, change directory to the binary tree, and then run:: +The :manual:`ctest ` executable will read in this file when it runs. +To create a simple dashboard you can run the :manual:`cmake ` +executable or the :manual:`cmake-gui ` to configure the project, +but do not build it yet. Instead, change directory to the binary tree, and then +run: ctest [-VV] -D Experimental @@ -619,26 +641,26 @@ 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 -public dashboard. The results of your dashboard will be uploaded to Kitware's -public dashboard here: https://my.cdash.org/index.php?project=CMakeTutorial. +The :manual:`ctest ` executable will build and test the project and +submit the results to Kitware's public dashboard: +https://my.cdash.org/index.php?project=CMakeTutorial. 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`` -or ``OBJECT``) are built. +In this section we will show how the :variable:`BUILD_SHARED_LIBS` variable can +be used to control the default behavior of :command:`add_library`, +and allow control 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 -optionally select if the value should be On or Off. +To accomplish this we need to add :variable:`BUILD_SHARED_LIBS` to the +top-level ``CMakeLists.txt``. We use the :command:`option` command as it allows +users to optionally select if the value should be ON or OFF. Next we are going to refactor MathFunctions to become a real library that encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling code to do this logic. This will also mean that ``USE_MYMATH`` will not control -building MathFuctions, but instead will control the behavior of this library. +building MathFunctions, but instead will control the behavior of this library. The first step is to update the starting section of the top-level ``CMakeLists.txt`` to look like: @@ -680,8 +702,8 @@ Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: At this point, if you build everything, you will notice that linking fails 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. +explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of +SqrtLibrary to be True no matter the build type. .. literalinclude:: Step10/MathFunctions/CMakeLists.txt :language: cmake @@ -694,35 +716,39 @@ Using CMake documentation can you find a helper module to simplify this? Adding Generator Expressions (Step 10) ====================================== -Generator expressions are evaluated during build system generation to produce -information specific to each build configuration. +:manual:`Generator expressions ` are evaluated +during build system generation to produce information specific to each build +configuration. -Generator expressions are allowed in the context of many target properties, -such as ``LINK_LIBRARIES``, ``INCLUDE_DIRECTORIES``, ``COMPILE_DEFINITIONS`` -and others. They may also be used when using commands to populate those -properties, such as ``target_link_libraries()``, -``target_include_directories()``, -``target_compile_definitions()`` and others. +:manual:`Generator expressions ` are allowed in +the context of many target properties, such as :prop_tgt:`LINK_LIBRARIES`, +:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and others. +They may also be used when using commands to populate those properties, such as +:command:`target_link_libraries`, :command:`target_include_directories`, +:command:`target_compile_definitions` and others. -Generator expressions may be used to enable conditional linking, conditional -definitions used when compiling, conditional include directories and more. -The conditions may be based on the build configuration, target properties, -platform information or any other queryable information. +:manual:`Generator expressions ` may be used +to enable conditional linking, conditional definitions used when compiling, +conditional include directories and more. The conditions may be based on the +build configuration, target properties, platform information or any other +queryable information. -There are different types of generator expressions including Logical, -Informational, and Output expressions. +There are different types of +:manual:`generator expressions ` including +Logical, Informational, and Output expressions. Logical expressions are used to create conditional output. The basic expressions are the 0 and 1 expressions. A ``$<0:...>`` results in the empty 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 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 -of using ``CMAKE_CXX_STANDARD``. +A common usage of +:manual:`generator expressions ` is to +conditionally add compiler 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 of using :variable:`CMAKE_CXX_STANDARD`. So the following code: @@ -739,11 +765,10 @@ Would be replaced with: :end-before: # add compiler warning flags just when building this project via -Next we add the desired compiler warning flags that we want for our -project. As warning flags vary based on the compiler we use -the ``COMPILE_LANG_AND_ID`` generator expression to control which -flags to apply given a language and a set of compiler ids as seen -below: +Next we add the desired compiler warning flags that we want for our project. As +warning flags vary based on the compiler we use the ``COMPILE_LANG_AND_ID`` +generator expression to control which flags to apply given a language and a set +of compiler ids as seen below: .. literalinclude:: Step11/CMakeLists.txt :language: cmake @@ -755,8 +780,8 @@ Looking at this we see that the warning flags are encapsulated inside a project will not inherit our warning flags. -**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that -all targets have a ``target_link_libraries()`` call to ``tutorial_compiler_flags``. +**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that all targets have +a :command:`target_link_libraries` call to ``tutorial_compiler_flags``. Adding Export Configuration (Step 11) @@ -771,12 +796,12 @@ The next step is to add the necessary information so that other CMake projects can use our project, be it from a build directory, a local install or when packaged. -The first step is to update our ``install(TARGETS)`` commands to not only -specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword +The first step is to update our :command:`install(TARGETS)` commands to not +only specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword generates and installs a CMake file containing code to import all targets -listed in the install command from the installation tree. So let's go ahead -and explicitly ``EXPORT`` the MathFunctions library by updating the -``install`` command in ``MathFunctions/CMakeLists.txt`` to look like: +listed in the install command from the installation tree. So let's go ahead and +explicitly ``EXPORT`` the MathFunctions library by updating the ``install`` +command in ``MathFunctions/CMakeLists.txt`` to look like: .. literalinclude:: Complete/MathFunctions/CMakeLists.txt :language: cmake @@ -806,12 +831,12 @@ you will see that CMake will generate an error that looks like: What CMake is trying to say is that during generating the export information it will export a path that is intrinsically tied to the current machine and will not be valid on other machines. The solution to this is to update the -MathFunctions ``target_include_directories`` to understand that it needs +MathFunctions :command:`target_include_directories` to understand that it needs different ``INTERFACE`` locations when being used from within the build directory and from an install / package. This means converting the -``target_include_directories`` call for MathFunctions to look like: +:command:`target_include_directories` call for MathFunctions to look like: -.. literalinclude:: Complete/MathFunctions/CMakeLists.txt +.. literalinclude:: Step12/MathFunctions/CMakeLists.txt :language: cmake :start-after: # to find MathFunctions.h, while we don't. :end-before: # should we use our own math functions @@ -821,16 +846,16 @@ 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 :command:`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 +.. literalinclude:: Step12/Config.cmake.in Then, to properly configure and install that file, add the following to the bottom of the top-level ``CMakeLists.txt``: -.. literalinclude:: Complete/CMakeLists.txt +.. literalinclude:: Step12/CMakeLists.txt :language: cmake :start-after: # install the configuration targets :end-before: # generate the export @@ -840,7 +865,7 @@ 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.txt``: -.. literalinclude:: Complete/CMakeLists.txt +.. literalinclude:: Step12/CMakeLists.txt :language: cmake :start-after: # needs to be after the install(TARGETS ) command @@ -848,55 +873,81 @@ With this export call we now generate a ``Targets.cmake``, allowing the configured ``MathFunctionsConfig.cmake`` in the build directory to be used by other projects, without needing it to be installed. -Import a CMake Project (Consumer) -================================= +Packaging Debug and Release (Step 12) +===================================== -This example shows how a project can find other CMake packages that -generate ``Config.cmake`` files. +**Note:** This example is valid for single-configuration generators and will +not work for multi-configuration generators (e.g. Visual Studio). -It also shows how to state a project's external dependencies when generating -a ``Config.cmake``. +By default, CMake's model is that a build directory only contains a single +configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. It is +possible, however, to setup CPack to bundle multiple build directories and +construct a package that contains multiple configurations of the same project. -Packaging Debug and Release (MultiPackage) -========================================== +First, we want to ensure that the debug and release builds use different names +for the executables and libraries that will be installed. Let's use `d` as the +postfix for the debug executable and libraries. -By default CMake's model is that a build directory only contains a single -configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. +Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level +``CMakeLists.txt`` file: -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. +.. literalinclude:: Complete/CMakeLists.txt + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: target_compile_features(tutorial_compiler_flags + +And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable: + +.. literalinclude:: Complete/CMakeLists.txt + :language: cmake + :start-after: # add the executable + :end-before: # add the binary tree to the search path for include files + +Let's also add version numbering to the MathFunctions library. In +``MathFunctions/CMakeLists.txt``, set the :prop_tgt:`VERSION` and +:prop_tgt:`SOVERSION` properties: -First we need to construct a directory called ``multi_config``, which -will contain all the builds that we want to package together. +.. literalinclude:: Complete/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # setup the version numbering + :end-before: # install rules -Second create a ``debug`` and ``release`` directory underneath -``multi_config``. At the end you should have a layout that looks like: +From the ``Step12`` directory, create ``debug`` and ``release`` +subbdirectories. The layout will look like: .. code-block:: none - ─ multi_config - ├── debug - └── release + - Step12 + - debug + - release -Now we need to setup debug and release builds, which would roughly entail -the following: +Now we need to setup debug and release builds. We can use +:variable:`CMAKE_BUILD_TYPE` to set the configuration type: .. code-block:: console cd debug - cmake -DCMAKE_BUILD_TYPE=Debug ../../MultiPackage/ + cmake -DCMAKE_BUILD_TYPE=Debug .. cmake --build . cd ../release - cmake -DCMAKE_BUILD_TYPE=Release ../../MultiPackage/ + cmake -DCMAKE_BUILD_TYPE=Release .. cmake --build . - cd .. +Now that both the debug and release builds are complete, we can use a custom +configuration file to package both builds into a single release. In the +``Step12`` directory, create a file called ``MultiCPackConfig.cmake``. In this +file, first include the default configuration file that was created by the +:manual:`cmake ` executable. + +Next, use the ``CPACK_INSTALL_CMAKE_PROJECTS`` variable to specify which +projects to install. In this case, we want to install both debug and release. + +.. literalinclude:: Complete/MultiCPackConfig.cmake + :language: cmake -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. +From the ``Step12`` directory, run :manual:`cpack ` specifying our +custom configuration file with the ``config`` option: .. code-block:: console - cpack --config ../../MultiPackage/MultiCPackConfig.cmake + cpack --config MultiCPackConfig.cmake diff --git a/Help/guide/user-interaction/GUI-Add-Entry.png b/Help/guide/user-interaction/GUI-Add-Entry.png new file mode 100644 index 00000000000..1e9be7efad8 Binary files /dev/null and b/Help/guide/user-interaction/GUI-Add-Entry.png differ diff --git a/Help/guide/user-interaction/GUI-Choose-Generator.png b/Help/guide/user-interaction/GUI-Choose-Generator.png new file mode 100644 index 00000000000..19ad2c0140e Binary files /dev/null and b/Help/guide/user-interaction/GUI-Choose-Generator.png differ diff --git a/Help/guide/user-interaction/GUI-Configure-Dialog.png b/Help/guide/user-interaction/GUI-Configure-Dialog.png new file mode 100644 index 00000000000..9839cacfa07 Binary files /dev/null and b/Help/guide/user-interaction/GUI-Configure-Dialog.png differ diff --git a/Help/guide/user-interaction/GUI-Source-Binary.png b/Help/guide/user-interaction/GUI-Source-Binary.png new file mode 100644 index 00000000000..e33835468ab Binary files /dev/null and b/Help/guide/user-interaction/GUI-Source-Binary.png differ diff --git a/Help/guide/user-interaction/index.rst b/Help/guide/user-interaction/index.rst new file mode 100644 index 00000000000..3a1038fa753 --- /dev/null +++ b/Help/guide/user-interaction/index.rst @@ -0,0 +1,686 @@ +User Interaction Guide +********************** + +.. only:: html + + .. contents:: + +Introduction +============ + +Where a software package supplies a CMake-based buildsystem +with the source of their software, the consumer of the +software is required to run a CMake user interaction tool +in order to build it. + +Well-behaved CMake-based buildsystems do not create any +output in the source directory, so typically, the user +performs an out-of-source build and performs the build +there. First, CMake must be instructed to generate a +suitable buildsystem, then the user invokes a build tool +to process that generated buildsystem. The generated +buildsystem is specific to the machine used to generate +it and is not redistributable. Each consumer of a provided +source software package is required to use CMake to +generate a buildsystem specific to their system. + +Generated buildsystems should generally be treated as +read-only. The CMake files as a primary artifact should +completely specify the buildsystem and there should be no +reason to populate properties manually in an IDE for +example after generating the buildsystem. CMake will +periodically rewrite the generated buildsystem, so +modifications by users will be overwritten. + +The features and user interfaces described in this manual +are available for all CMake-based build systems by virtue +of providing CMake files. + +The CMake tooling may report errors to the user when +processing provided CMake files, such as reporting that +the compiler is not supported, or the compiler does not +support a required compile option, or a dependency can +not be found. These errors must be resolved by the user +by choosing a different compiler, +:guide:`installing dependencies `, +or instructing CMake where to find them, etc. + +Command Line cmake tool +----------------------- + +A simple but typical use of :manual:`cmake(1)` with a fresh +copy of software source code is to create a build directory +and invoke cmake there: + +.. code-block:: console + + $ cd some_software-1.4.2 + $ mkdir build + $ cd build + $ cmake .. -DCMAKE_INSTALL_PREFIX=/opt/the/prefix + $ cmake --build . + $ cmake --build . --target install + +It is recommended to build in a separate directory to the +source because that keeps the source directory pristine, +allows for building a single source with multiple +toolchains, and allows easy clearing of build artifacts by +simply deleting the build directory. + +The CMake tooling may report warnings which are intended +for the provider of the software, not intended for the +consumer of the software. Such warnings end with "This +warning is for project developers". Users may disable +such warnings by passing the ``-Wno-dev`` flag to +:manual:`cmake(1)`. + +cmake-gui tool +-------------- + +Users more accustomed to GUI interfaces may use the +:manual:`cmake-gui(1)` tool to invoke CMake and generate +a buildsystem. + +The source and binary directories must first be +populated. It is always advised to use different +directories for the source and the build. + +.. image:: /guide/user-interaction/GUI-Source-Binary.png + +Generating a Buildsystem +======================== + +There are several user interface tools which may be used +to generate a buildsystem from CMake files. The +:manual:`ccmake(1)` and :manual:`cmake-gui(1)` tools guide +the user through setting the various necessary options. +The :manual:`cmake(1)` tool can be invoked to specify +options on the command line. This manual describes options +which may be set using any of the user interface tools, +though the mode of setting an option is different for each +tool. + +Command line environment +------------------------ + +When invoking :manual:`cmake(1)` with a command line +buildsystem such as ``Makefiles`` or ``Ninja``, it is +necessary to use the correct build environment to +ensure that build tools are available. CMake must be +able to find the appropriate +:variable:`build tool `, +compiler, linker and other tools as needed. + +On Linux systems, the appropriate tools are often +provided in system-wide locations and may be readily +installed through the system package manager. Other +toolchains provided by the user or installed in +non-default locations can also be used. + +When cross-compiling, some platforms may require +environment variables to be set or may provide +scripts to set the environment. + +Visual Studio ships multiple command prompts and +``vcvarsall.bat`` scripts for setting up the +correct environments for command line buildsystems. While +not strictly necessary to use a corresponding +command line environment when using a Visual Studio +generator, doing so has no disadvantages. + +When using Xcode, there can be more than one Xcode +version installed. Which one to use can be selected +in a number of different ways, but the most common +methods are: + +* Setting the default version in the preferences + of the Xcode IDE. +* Setting the default version via the ``xcode-select`` + command line tool. +* Overriding the default version by setting the + ``DEVELOPER_DIR`` environment variable when running + CMake and the build tool. + +Command line ``-G`` option +-------------------------- + +CMake chooses a generator by default based on the +platform. Usually, the default generator is sufficient +to allow the user to proceed to build the software. + +The user may override the default generator with +the ``-G`` option: + +.. code-block:: console + + $ cmake .. -G Ninja + +The output of ``cmake --help`` includes a list of +:manual:`generators ` available +for the user to choose from. Note that generator +names are case sensitive. + +On Unix-like systems (including Mac OS X), the +:generator:`Unix Makefiles` generator is used by +default. A variant of that generator can also be used +on Windows in various environments, such as the +:generator:`NMake Makefiles` and +:generator:`MinGW Makefiles` generator. These generators +generate a ``Makefile`` variant which can be executed +with ``make``, ``gmake``, ``nmake`` or similar tools. +See the individual generator documentation for more +information on targeted environments and tools. + +The :generator:`Ninja` generator is available on all +major platforms. ``ninja`` is a build tool similar +in use-cases to ``make``, but with a focus on +performance and efficiency. + +On Windows, :manual:`cmake(1)` can be used to generate +solutions for the Visual Studio IDE. Visual Studio +versions may be specified by the product name of the +IDE, which includes a four-digit year. Aliases are +provided for other means by which Visual Studio +versions are sometimes referred to, such as two +digits which correspond to the product version of the +VisualC++ compiler, or a combination of the two: + +.. code-block:: console + + $ cmake .. -G "Visual Studio 2019" + $ cmake .. -G "Visual Studio 16" + $ cmake .. -G "Visual Studio 16 2019" + +Visual Studio generators can target different architectures. +One can specify the target architecture using the `-A` option: + +.. code-block:: console + + cmake .. -G "Visual Studio 2019" -A x64 + cmake .. -G "Visual Studio 16" -A ARM + cmake .. -G "Visual Studio 16 2019" -A ARM64 + +On Apple, the :generator:`Xcode` generator may be used to +generate project files for the Xcode IDE. + +Some IDEs such as KDevelop4, QtCreator and CLion have +native support for CMake-based buildsystems. Those IDEs +provide user interface for selecting an underlying +generator to use, typically a choice between a ``Makefile`` +or a ``Ninja`` based generator. + +Note that it is not possible to change the generator +with ``-G`` after the first invocation of CMake. To +change the generator, the build directory must be +deleted and the build must be started from scratch. + +When generating Visual Studio project and solutions +files several other options are available to use when +initially running :manual:`cmake(1)`. + +The Visual Studio toolset can be specified with the +``-T`` option: + +.. code-block:: console + + $ # Build with the clang-cl toolset + $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T LLVM + $ # Build targeting Windows XP + $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T v120_xp + +Whereas the ``-A`` option specifies the _target_ +architecture, the ``-T`` option can be used to specify +details of the toolchain used. For example, `-Thost=x64` +can be given to select the 64-bit version of the host +tools. The following demonstrates how to use 64-bit +tools and also build for a 64-bit target architecture: + +.. code-block:: console + + $ cmake .. -G "Visual Studio 16 2019" -A x64 -Thost=x64 + +Choosing a generator in cmake-gui +--------------------------------- + +The "Configure" button triggers a new dialog to +select the CMake generator to use. + +.. image:: /guide/user-interaction/GUI-Configure-Dialog.png + +All generators available on the command line are also +available in :manual:`cmake-gui(1)`. + +.. image:: /guide/user-interaction/GUI-Choose-Generator.png + +When choosing a Visual Studio generator, further options +are available to set an architecture to generate for. + +.. image:: /manual/VS-Choose-Arch.png + +.. _`Setting Build Variables`: + +Setting Build Variables +======================= + +Software projects often require variables to be +set on the command line when invoking CMake. Some of +the most commonly used CMake variables are listed in +the table below: + +========================================== ============================================================ + Variable Meaning +========================================== ============================================================ + :variable:`CMAKE_PREFIX_PATH` Path to search for + :guide:`dependent packages ` + :variable:`CMAKE_MODULE_PATH` Path to search for additional CMake modules + :variable:`CMAKE_BUILD_TYPE` Build configuration, such as + ``Debug`` or ``Release``, determining + debug/optimization flags. This is only + relevant for single-configuration buildsystems such + as ``Makefile`` and ``Ninja``. Multi-configuration + buildsystems such as those for Visual Studio and Xcode + ignore this setting. + :variable:`CMAKE_INSTALL_PREFIX` Location to install the + software to with the + ``install`` build target + :variable:`CMAKE_TOOLCHAIN_FILE` File containing cross-compiling + data such as + :manual:`toolchains and sysroots `. + :variable:`BUILD_SHARED_LIBS` Whether to build shared + instead of static libraries + for :command:`add_library` + commands used without a type + :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` Generate a ``compile_commands.json`` + file for use with clang-based tools +========================================== ============================================================ + +Other project-specific variables may be available +to control builds, such as enabling or disabling +components of the project. + +There is no convention provided by CMake for how +such variables are named between different +provided buildsystems, except that variables with +the prefix ``CMAKE_`` usually refer to options +provided by CMake itself and should not be used +in third-party options, which should use +their own prefix instead. The +:manual:`cmake-gui(1)` tool can display options +in groups defined by their prefix, so it makes +sense for third parties to ensure that they use a +self-consistent prefix. + +Setting variables on the command line +------------------------------------- + +CMake variables can be set on the command line either +when creating the initial build: + +.. code-block:: console + + $ mkdir build + $ cd build + $ cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug + +or later on a subsequent invocation of +:manual:`cmake(1)`: + +.. code-block:: console + + $ cd build + $ cmake . -DCMAKE_BUILD_TYPE=Debug + +The ``-U`` flag may be used to unset variables +on the :manual:`cmake(1)` command line: + +.. code-block:: console + + $ cd build + $ cmake . -UMyPackage_DIR + +A CMake buildsystem which was initially created +on the command line can be modified using the +:manual:`cmake-gui(1)` and vice-versa. + +The :manual:`cmake(1)` tool allows specifying a +file to use to populate the initial cache using +the ``-C`` option. This can be useful to simplify +commands and scripts which repeatedly require the +same cache entries. + +Setting variables with cmake-gui +-------------------------------- + +Variables may be set in the cmake-gui using the "Add Entry" +button. This triggers a new dialog to set the value of +the variable. + +.. image:: /guide/user-interaction/GUI-Add-Entry.png + +The main view of the :manual:`cmake-gui(1)` user interface +can be used to edit existing variables. + +The CMake Cache +--------------- + +When CMake is executed, it needs to find the locations of +compilers, tools and dependencies. It also needs to be +able to consistently re-generate a buildsystem to use the +same compile/link flags and paths to dependencies. Such +parameters are also required to be configurable by the +user because they are paths and options specific to the +users system. + +When it is first executed, CMake generates a +``CMakeCache.txt`` file in the build directory containing +key-value pairs for such artifacts. The cache file can be +viewed or edited by the user by running the +:manual:`cmake-gui(1)` or :manual:`ccmake(1)` tool. The +tools provide an interactive interface for re-configuring +the provided software and re-generating the buildsystem, +as is needed after editing cached values. Each cache +entry may have an associated short help text which is +displayed in the user interface tools. + +The cache entries may also have a type to signify how it +should be presented in the user interface. For example, +a cache entry of type ``BOOL`` can be edited by a +checkbox in a user interface, a ``STRING`` can be edited +in a text field, and a ``FILEPATH`` while similar to a +``STRING`` should also provide a way to locate filesystem +paths using a file dialog. An entry of type ``STRING`` +may provide a restricted list of allowed values which are +then provided in a drop-down menu in the +:manual:`cmake-gui(1)` user interface (see the +:prop_cache:`STRINGS` cache property). + +The CMake files shipped with a software package may also +define boolean toggle options using the :command:`option` +command. The command creates a cache entry which has a +help text and a default value. Such cache entries are +typically specific to the provided software and affect +the configuration of the build, such as whether tests +and examples are built, whether to build with exceptions +enabled etc. + +Invoking the Buildsystem +======================== + +After generating the buildsystem, the software can be +built by invoking the particular build tool. In the +case of the IDE generators, this can involve loading +the generated project file into the IDE to invoke the +build. + +CMake is aware of the specific build tool needed to invoke +a build so in general, to build a buildsystem or project +from the command line after generating, the following +command may be invoked in the build directory: + +.. code-block:: console + + $ cmake --build . + +The ``--build`` flag enables a particular mode of +operation for the :manual:`cmake(1)` tool. It invokes +the :variable:`CMAKE_MAKE_PROGRAM` command associated +with the :manual:`generator `, or +the build tool configured by the user. + +The ``--build`` mode also accepts the parameter +``--target`` to specify a particular target to build, +for example a particular library, executable or +custom target, or a particular special target like +``install``: + +.. code-block:: console + + $ cmake --build . --target myexe + +The ``--build`` mode also accepts a ``--config`` parameter +in the case of multi-config generators to specify which +particular configuration to build: + +.. code-block:: console + + $ cmake --build . --target myexe --config Release + +The ``--config`` option has no effect if the generator +generates a buildsystem specific to a configuration which +is chosen when invoking cmake with the +:variable:`CMAKE_BUILD_TYPE` variable. + +Some buildsystems omit details of command lines invoked +during the build. The ``--verbose`` flag can be used to +cause those command lines to be shown: + +.. code-block:: console + + $ cmake --build . --target myexe --verbose + +The ``--build`` mode can also pass particular command +line options to the underlying build tool by listing +them after ``--``. This can be useful to specify +options to the build tool, such as to continue the +build after a failed job, where CMake does not +provide a high-level user interface. + +For all generators, it is possible to run the underlying +build tool after invoking CMake. For example, ``make`` +may be executed after generating with the +:generator:`Unix Makefiles` generator to invoke the build, +or ``ninja`` after generating with the :generator:`Ninja` +generator etc. The IDE buildsystems usually provide +command line tooling for building a project which can +also be invoked. + +Selecting a Target +------------------ + +Each executable and library described in the CMake files +is a build target, and the buildsystem may describe +custom targets, either for internal use, or for user +consumption, for example to create documentation. + +CMake provides some built-in targets for all buildsystems +providing CMake files. + +``all`` + The default target used by ``Makefile`` and ``Ninja`` + generators. Builds all targets in the buildsystem, + except those which are excluded by their + :prop_tgt:`EXCLUDE_FROM_ALL` target property or + :prop_dir:`EXCLUDE_FROM_ALL` directory property. The + name ``ALL_BUILD`` is used for this purpose for the + Xcode and Visual Studio generators. +``help`` + Lists the targets available for build. This target is + available when using the :generator:`Unix Makefiles` or + :generator:`Ninja` generator, and the exact output is + tool-specific. +``clean`` + Delete built object files and other output files. The + ``Makefile`` based generators create a ``clean`` target + per directory, so that an individual directory can be + cleaned. The ``Ninja`` tool provides its own granular + ``-t clean`` system. +``test`` + Runs tests. This target is only automatically available + if the CMake files provide CTest-based tests. See also + `Running Tests`_. +``install`` + Installs the software. This target is only automatically + available if the software defines install rules with the + :command:`install` command. See also + `Software Installation`_. +``package`` + Creates a binary package. This target is only + automatically available if the CMake files provide + CPack-based packages. +``package_source`` + Creates a source package. This target is only + automatically available if the CMake files provide + CPack-based packages. + +For ``Makefile`` based systems, ``/fast`` variants of binary +build targets are provided. The ``/fast`` variants are used +to build the specified target without regard for its +dependencies. The dependencies are not checked and +are not rebuilt if out of date. The :generator:`Ninja` +generator is sufficiently fast at dependency checking that +such targets are not provided for that generator. + +``Makefile`` based systems also provide build-targets to +preprocess, assemble and compile individual files in a +particular directory. + +.. code-block:: console + + $ make foo.cpp.i + $ make foo.cpp.s + $ make foo.cpp.o + +The file extension is built into the name of the target +because another file with the same name but a different +extension may exist. However, build-targets without the +file extension are also provided. + +.. code-block:: console + + $ make foo.i + $ make foo.s + $ make foo.o + +In buildsystems which contain ``foo.c`` and ``foo.cpp``, +building the ``foo.i`` target will preprocess both files. + +Specifying a Build Program +-------------------------- + +The program invoked by the ``--build`` mode is determined +by the :variable:`CMAKE_MAKE_PROGRAM` variable. For most +generators, the particular program does not need to be +configured. + +===================== =========================== =========================== + Generator Default make program Alternatives +===================== =========================== =========================== + XCode ``xcodebuild`` + Unix Makefiles ``make`` + NMake Makefiles ``nmake`` ``jom`` + NMake Makefiles JOM ``jom`` ``nmake`` + MinGW Makefiles ``mingw32-make`` + MSYS Makefiles ``make`` + Ninja ``ninja`` + Visual Studio ``msbuild`` + Watcom WMake ``wmake`` +===================== =========================== =========================== + +The ``jom`` tool is capable of reading makefiles of the +``NMake`` flavor and building in parallel, while the +``nmake`` tool always builds serially. After generating +with the :generator:`NMake Makefiles` generator a user +can run ``jom`` instead of ``nmake``. The ``--build`` +mode would also use ``jom`` if the +:variable:`CMAKE_MAKE_PROGRAM` was set to ``jom`` while +using the :generator:`NMake Makefiles` generator, and +as a convenience, the :generator:`NMake Makefiles JOM` +generator is provided to find ``jom`` in the normal way +and use it as the :variable:`CMAKE_MAKE_PROGRAM`. For +completeness, ``nmake`` is an alternative tool which +can process the output of the +:generator:`NMake Makefiles JOM` generator, but doing +so would be a pessimisation. + +Software Installation +===================== + +The :variable:`CMAKE_INSTALL_PREFIX` variable can be +set in the CMake cache to specify where to install the +provided software. If the provided software has install +rules, specified using the :command:`install` command, +they will install artifacts into that prefix. On Windows, +the default installation location corresponds to the +``ProgramFiles`` system directory which may be +architecture specific. On Unix hosts, ``/usr/local`` is +the default installation location. + +The :variable:`CMAKE_INSTALL_PREFIX` variable always +refers to the installation prefix on the target +filesystem. + +In cross-compiling or packaging scenarios where the +sysroot is read-only or where the sysroot should otherwise +remain pristine, the :variable:`CMAKE_STAGING_PREFIX` +variable can be set to a location to actually install +the files. + +The commands: + +.. code-block:: console + + $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local \ + -DCMAKE_SYSROOT=$HOME/root \ + -DCMAKE_STAGING_PREFIX=/tmp/package + $ cmake --build . + $ cmake --build . --target install + +result in files being installed to paths such +as ``/tmp/package/lib/libfoo.so`` on the host machine. +The ``/usr/local`` location on the host machine is +not affected. + +Some provided software may specify ``uninstall`` rules, +but CMake does not generate such rules by default itself. + +Running Tests +============= + +The :manual:`ctest(1)` tool is shipped with the CMake +distribution to execute provided tests and report +results. The ``test`` build-target is provided to run +all available tests, but the :manual:`ctest(1)` tool +allows granular control over which tests to run, how to +run them, and how to report results. Executing +:manual:`ctest(1)` in the build directory is equivalent +to running the ``test`` target: + +.. code-block:: console + + $ ctest + +A regular expression can be passed to run only tests +which match the expression. To run only tests with +``Qt`` in their name: + +.. code-block:: console + + $ ctest -R Qt + +Tests can be excluded by regular expression too. To +run only tests without ``Qt`` in their name: + +.. code-block:: console + + $ ctest -E Qt + +Tests can be run in parallel by passing ``-j`` arguments +to :manual:`ctest(1)`: + +.. code-block:: console + + $ ctest -R Qt -j8 + +The environment variable :envvar:`CTEST_PARALLEL_LEVEL` +can alternatively be set to avoid the need to pass +``-j``. + +By default :manual:`ctest(1)` does not print the output +from the tests. The command line argument ``-V`` (or +``--verbose``) enables verbose mode to print the +output from all tests. +The ``--output-on-failure`` option prints the test +output for failing tests only. The environment variable +:envvar:`CTEST_OUTPUT_ON_FAILURE` +can be set to ``1`` as an alternative to passing the +``--output-on-failure`` option to :manual:`ctest(1)`. diff --git a/Help/guide/using-dependencies/index.rst b/Help/guide/using-dependencies/index.rst new file mode 100644 index 00000000000..6fdcc551eb9 --- /dev/null +++ b/Help/guide/using-dependencies/index.rst @@ -0,0 +1,200 @@ +Using Dependencies Guide +************************ + +.. only:: html + + .. contents:: + +Introduction +============ + +For developers wishing to use CMake to consume a third +party binary package, there are multiple possibilities +regarding how to optimally do so, depending on how +CMake-aware the third-party library is. + +CMake files provided with a software package contain +instructions for finding each build dependency. Some +build dependencies are optional in that the build may +succeed with a different feature set if the dependency +is missing, and some dependencies are required. CMake +searches well-known locations for each dependency, and +the provided software may supply additional hints or +locations to CMake to find each dependency. + +If a required dependency is not found by +:manual:`cmake(1)`, the cache is populated with an entry +which contains a ``NOTFOUND`` value. This value can be +replaced by specifying it on the command line, or in +the :manual:`ccmake(1)` or :manual:`cmake-gui(1)` tool. +See the :guide:`User Interaction Guide` for +more about setting cache entries. + +Libraries providing Config-file packages +---------------------------------------- + +The most convenient way for a third-party to provide library +binaries for use with CMake is to provide +:ref:`Config File Packages`. These packages are text files +shipped with the library which instruct CMake how to use the +library binaries and associated headers, helper tools and +CMake macros provided by the library. + +The config files can usually be found in a directory whose +name matches the pattern ``lib/cmake/``, though +they may be in other locations instead. The +```` corresponds to use in CMake code with the +:command:`find_package` command such as +``find_package(PackageName REQUIRED)``. + +The ``lib/cmake/`` directory will contain a +file which is either named ``Config.cmake`` +or ``-config.cmake``. This is the entry point +to the package for CMake. A separate optional file named +``ConfigVersion.cmake`` may also exist in the +directory. This file is used by CMake to determine whether +the version of the third party package satisfies uses of the +:command:`find_package` command which specify version +constraints. It is optional to specify a version when using +:command:`find_package`, even if a ``ConfigVersion`` file is +present. + +If the ``Config.cmake`` file is found and the +optionally-specified version is satisfied, then the CMake +:command:`find_package` command considers the package to be +found and the entire library package is assumed to be +complete as designed. + +There may be additional files providing CMake macros or +:ref:`imported targets` for you to use. CMake does not +enforce any naming convention for these +files. They are related to the primary ``Config`` file by +use of the CMake :command:`include` command. + +:guide:`Invoking CMake ` with the +intent of using a package of third party binaries requires +that cmake :command:`find_package` commands succeed in finding +the package. If the location of the package is in a directory +known to CMake, the :command:`find_package` call should +succeed. The directories known to cmake are platform-specific. +For example, packages installed on Linux with a standard +system package manager will be found in the ``/usr`` prefix +automatically. Packages installed in ``Program Files`` on +Windows will similarly be found automatically. + +Packages which are not found automatically are in locations +not predictable to CMake such as ``/opt/mylib`` or +``$HOME/dev/prefix``. This is a normal situation and CMake +provides several ways for users to specify where to find +such libraries. + +The :variable:`CMAKE_PREFIX_PATH` variable may be +:ref:`set when invoking CMake `. +It is treated as a list of paths to search for +:ref:`Config File Packages`. A package installed in +``/opt/somepackage`` will typically install config files +such as +``/opt/somepackage/lib/cmake/somePackage/SomePackageConfig.cmake``. +In that case, ``/opt/somepackage`` should be added to +:variable:`CMAKE_PREFIX_PATH`. + +The environment variable ``CMAKE_PREFIX_PATH`` may also be +populated with prefixes to search for packages. Like the +``PATH`` environment variable, this is a list and needs to use +the platform-specific environment variable list item separator +(``:`` on Unix and ``;`` on Windows). + +The :variable:`CMAKE_PREFIX_PATH` variable provides convenience +in cases where multiple prefixes need to be specified, or when +multiple different package binaries are available in the same +prefix. Paths to packages may also be specified by setting +variables matching ``_DIR``, such as +``SomePackage_DIR``. Note that this is not a prefix but should +be a full path to a directory containing a config-style package +file, such as ``/opt/somepackage/lib/cmake/SomePackage/`` in +the above example. + +Imported Targets from Packages +------------------------------ + +A third-party package which provides config-file packages may +also provide :ref:`Imported targets`. These will be +specified in files containing configuration-specific file +paths relevant to the package, such as debug and release +versions of libraries. + +Often the third-party package documentation will point out the +names of imported targets available after a successful +``find_package`` for a library. Those imported target names +can be used with the :command:`target_link_libraries` command. + +A complete example which makes a simple use of a third party +library might look like: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.10) + project(MyExeProject VERSION 1.0.0) + + find_package(SomePackage REQUIRED) + add_executable(MyExe main.cpp) + target_link_libraries(MyExe PRIVATE SomePrefix::LibName) + +See :manual:`cmake-buildsystem(7)` for further information +about developing a CMake buildsystem. + +Libraries not Providing Config-file Packages +-------------------------------------------- + +Third-party libraries which do not provide config-file packages +can still be found with the :command:`find_package` command, if +a ``FindSomePackage.cmake`` file is available. + +These module-file packages are different to config-file packages +in that: + +#. They should not be provided by the third party, except + perhaps in the form of documentation +#. The availability of a ``Find.cmake`` file does + not indicate the availability of the binaries themselves. +#. CMake does not search the :variable:`CMAKE_PREFIX_PATH` for + ``Find.cmake`` files. Instead CMake searches + for such files in the :variable:`CMAKE_MODULE_PATH` + variable. It is common for users to set the + :variable:`CMAKE_MODULE_PATH` when running CMake, and it is + common for CMake projects to append to + :variable:`CMAKE_MODULE_PATH` to allow use of local + module-file packages. +#. CMake ships ``Find.cmake`` files for some + :manual:`third party packages ` + for convenience in cases where the third party does + not provide config-file packages directly. These files are + a maintenance burden for CMake, so new Find modules are + generally not added to CMake anymore. Third-parties should + provide config file packages instead of relying on a Find + module to be provided by CMake. + +Module-file packages may also provide :ref:`Imported targets`. +A complete example which finds such a package might look +like: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.10) + project(MyExeProject VERSION 1.0.0) + + find_package(PNG REQUIRED) + + # Add path to a FindSomePackage.cmake file + list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake") + find_package(SomePackage REQUIRED) + + add_executable(MyExe main.cpp) + target_link_libraries(MyExe PRIVATE + PNG::PNG + SomePrefix::LibName + ) + +The :variable:`_ROOT` variable is also +searched as a prefix for :command:`find_package` calls using +module-file packages such as ``FindSomePackage``. diff --git a/Help/index.rst b/Help/index.rst index cc6cee64482..4d9a9c80f5c 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -1,5 +1,34 @@ .. title:: CMake Reference Documentation +Introduction +############ + +CMake is a tool to manage building of source code. Originally, CMake was +designed as a generator for various dialects of ``Makefile``, today +CMake generates modern buildsystems such as ``Ninja`` as well as project +files for IDEs such as Visual Studio and Xcode. + +CMake is widely used for the C and C++ languages, but it may be used to +build source code of other languages too. + +People encountering CMake for the first time may have different initial +goals. To learn how to build a source code package downloaded from the +internet, start with the :guide:`User Interaction Guide`. +This will detail the steps needed to run the :manual:`cmake(1)` or +:manual:`cmake-gui(1)` executable and how to choose a generator, and +how to complete the build. + +The :guide:`Using Dependencies Guide` is aimed at developers +wishing to get started using a third-party library. + +For developers starting a project using CMake, the :guide:`CMake Tutorial` +is a suitable starting point. The :manual:`cmake-buildsystem(7)` +manual is aimed at developers expanding their knowledge of maintaining +a buildsystem and becoming familiar with the build targets that +can be represented in CMake. The :manual:`cmake-packages(7)` manual +explains how to create packages which can easily be consumed by +third-party CMake-based buildsystems. + Command-Line Tools ################## @@ -53,6 +82,8 @@ Reference Manuals :maxdepth: 1 /guide/tutorial/index + /guide/user-interaction/index + /guide/using-dependencies/index .. only:: html or text diff --git a/Help/manual/ID_RESERVE.txt b/Help/manual/ID_RESERVE.txt new file mode 100644 index 00000000000..be2b163d348 --- /dev/null +++ b/Help/manual/ID_RESERVE.txt @@ -0,0 +1,7 @@ +.. note:: + + CMake reserves identifiers that: + + * begin with ``CMAKE_`` (upper-, lower-, or mixed-case), or + * begin with ``_CMAKE_`` (upper-, lower-, or mixed-case), or + * begin with ``_`` followed by the name of any :manual:`CMake Command `. diff --git a/Help/manual/VS-Choose-Arch.png b/Help/manual/VS-Choose-Arch.png new file mode 100644 index 00000000000..816b0f42617 Binary files /dev/null and b/Help/manual/VS-Choose-Arch.png differ diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index a14e3222c04..05dc038be8d 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -19,11 +19,11 @@ While features are typically specified in programming language standards, CMake provides a primary user interface based on granular handling of the features, not the language standard that introduced the feature. -The :prop_gbl:`CMAKE_C_KNOWN_FEATURES` and -:prop_gbl:`CMAKE_CXX_KNOWN_FEATURES` global properties contain all the +The :prop_gbl:`CMAKE_C_KNOWN_FEATURES`, :prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES`, +and :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES` global properties contain all the features known to CMake, regardless of compiler support for the feature. -The :variable:`CMAKE_C_COMPILE_FEATURES` and -:variable:`CMAKE_CXX_COMPILE_FEATURES` variables contain all features +The :variable:`CMAKE_C_COMPILE_FEATURES`, :variable:`CMAKE_CUDA_COMPILE_FEATURES` +, and :variable:`CMAKE_CXX_COMPILE_FEATURES` variables contain all features CMake knows are known to the compiler, regardless of language standard or compile flags needed to use them. @@ -368,8 +368,9 @@ versions specified for each: * all compilers and versions listed above with only meta-features for C++. * ``TI``: Texas Instruments compiler. -CMake is currently aware of the :prop_tgt:`CUDA standards ` -from the following :variable:`compiler ids _COMPILER_ID>` as of the +CMake is currently aware of the :prop_tgt:`CUDA standards ` and +their associated meta-features (e.g. ``cuda_std_11``) available from the +following :variable:`compiler ids _COMPILER_ID>` as of the versions specified for each: * ``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 96ceb945a80..adfc39e9f16 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -23,10 +23,12 @@ 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 /envvar/CMAKE_GENERATOR_TOOLSET + /envvar/CMAKE_LANG_COMPILER_LAUNCHER /envvar/CMAKE_MSVCIDE_RUN_PATH /envvar/CMAKE_NO_VERBOSE /envvar/CMAKE_OSX_ARCHITECTURES diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 04b6ed2598b..12eecd99328 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -199,6 +199,7 @@ The reply index file contains a JSON object: "root": "/prefix/share/cmake-3.14" }, "generator": { + "multiConfig": false, "name": "Unix Makefiles" } }, @@ -267,6 +268,9 @@ The members are: A JSON object describing the CMake generator used for the build. It has members: + ``multiConfig`` + A boolean specifying whether the generator supports multiple output + configurations. ``name`` A string specifying the name of the generator. ``platform`` diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 75f4bd48a2a..691481b9920 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. ``$`` 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-generators.7.rst b/Help/manual/cmake-generators.7.rst index 41f76522019..6f88c0a0931 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -52,13 +52,14 @@ Makefile Generators /generator/Unix Makefiles /generator/Watcom WMake -Ninja Generator -^^^^^^^^^^^^^^^ +Ninja Generators +^^^^^^^^^^^^^^^^ .. toctree:: :maxdepth: 1 /generator/Ninja + /generator/Ninja Multi-Config .. _`IDE Build Tool Generators`: diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 4ca8e3a2658..b7f0861cf65 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -567,6 +567,8 @@ The :manual:`cmake-variables(7)` manual documents the many variables that are provided by CMake or have meaning to CMake when set by project code. +.. include:: ID_RESERVE.txt + .. _`CMake Language Environment Variables`: Environment Variables diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index c60dc4010f7..be64112c75a 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -122,6 +122,7 @@ They are normally called through the :command:`find_package` command. /module/FindCABLE /module/FindCoin3D /module/FindCups + /module/FindCUDAToolkit /module/FindCURL /module/FindCurses /module/FindCVS diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 44ea1a8fd04..c2562509776 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,18 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.17 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0102: mark_as_advanced() does nothing if a cache entry does not exist. + CMP0101: target_compile_options honors BEFORE keyword in all scopes. + CMP0100: Let AUTOMOC and AUTOUIC process .hh header files. + CMP0099: Link properties are transitive over private dependency on static libraries. + CMP0098: FindFLEX runs flex in CMAKE_CURRENT_BINARY_DIR when executing. + Policies Introduced by CMake 3.16 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index e7043714c7a..060a072bfa1 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -22,10 +22,13 @@ Properties of Global Scope /prop_gbl/AUTOMOC_TARGETS_FOLDER /prop_gbl/AUTORCC_SOURCE_GROUP /prop_gbl/CMAKE_C_KNOWN_FEATURES + /prop_gbl/CMAKE_CUDA_KNOWN_FEATURES /prop_gbl/CMAKE_CXX_KNOWN_FEATURES /prop_gbl/CMAKE_ROLE /prop_gbl/DEBUG_CONFIGURATIONS /prop_gbl/DISABLED_FEATURES + /prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS + /prop_gbl/ECLIPSE_EXTRA_NATURES /prop_gbl/ENABLED_FEATURES /prop_gbl/ENABLED_LANGUAGES /prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS @@ -36,12 +39,10 @@ Properties of Global Scope /prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE /prop_gbl/GLOBAL_DEPENDS_NO_CYCLES /prop_gbl/IN_TRY_COMPILE + /prop_gbl/JOB_POOLS /prop_gbl/PACKAGES_FOUND /prop_gbl/PACKAGES_NOT_FOUND - /prop_gbl/JOB_POOLS /prop_gbl/PREDEFINED_TARGETS_FOLDER - /prop_gbl/ECLIPSE_EXTRA_NATURES - /prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS /prop_gbl/REPORT_UNDEFINED_PROPERTIES /prop_gbl/RULE_LAUNCH_COMPILE /prop_gbl/RULE_LAUNCH_CUSTOM @@ -103,6 +104,7 @@ Properties on Targets :maxdepth: 1 /prop_tgt/ADDITIONAL_CLEAN_FILES + /prop_tgt/AIX_EXPORT_ALL_SYMBOLS /prop_tgt/ALIASED_TARGET /prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS /prop_tgt/ANDROID_API @@ -129,20 +131,20 @@ Properties on Targets /prop_tgt/AUTOGEN_ORIGIN_DEPENDS /prop_tgt/AUTOGEN_PARALLEL /prop_tgt/AUTOGEN_TARGET_DEPENDS + /prop_tgt/AUTOMOC /prop_tgt/AUTOMOC_COMPILER_PREDEFINES /prop_tgt/AUTOMOC_DEPEND_FILTERS /prop_tgt/AUTOMOC_EXECUTABLE /prop_tgt/AUTOMOC_MACRO_NAMES /prop_tgt/AUTOMOC_MOC_OPTIONS /prop_tgt/AUTOMOC_PATH_PREFIX - /prop_tgt/AUTOMOC + /prop_tgt/AUTORCC + /prop_tgt/AUTORCC_EXECUTABLE + /prop_tgt/AUTORCC_OPTIONS /prop_tgt/AUTOUIC /prop_tgt/AUTOUIC_EXECUTABLE /prop_tgt/AUTOUIC_OPTIONS /prop_tgt/AUTOUIC_SEARCH_PATHS - /prop_tgt/AUTORCC - /prop_tgt/AUTORCC_EXECUTABLE - /prop_tgt/AUTORCC_OPTIONS /prop_tgt/BINARY_DIR /prop_tgt/BUILD_RPATH /prop_tgt/BUILD_RPATH_USE_ORIGIN @@ -172,6 +174,7 @@ Properties on Targets /prop_tgt/CUDA_PTX_COMPILATION /prop_tgt/CUDA_SEPARABLE_COMPILATION /prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS + /prop_tgt/CUDA_RUNTIME_LIBRARY /prop_tgt/CUDA_EXTENSIONS /prop_tgt/CUDA_STANDARD /prop_tgt/CUDA_STANDARD_REQUIRED @@ -182,7 +185,9 @@ Properties on Targets /prop_tgt/DEFINE_SYMBOL /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY /prop_tgt/DEPLOYMENT_ADDITIONAL_FILES + /prop_tgt/DEPRECATION /prop_tgt/DISABLE_PRECOMPILE_HEADERS + /prop_tgt/DOTNET_TARGET_FRAMEWORK /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString /prop_tgt/ENABLE_EXPORTS @@ -251,6 +256,7 @@ Properties on Targets /prop_tgt/IOS_INSTALL_COMBINED /prop_tgt/JOB_POOL_COMPILE /prop_tgt/JOB_POOL_LINK + /prop_tgt/JOB_POOL_PRECOMPILE_HEADER /prop_tgt/LABELS /prop_tgt/LANG_CLANG_TIDY /prop_tgt/LANG_COMPILER_LAUNCHER @@ -279,6 +285,8 @@ Properties on Targets /prop_tgt/LINK_WHAT_YOU_USE /prop_tgt/LOCATION_CONFIG /prop_tgt/LOCATION + /prop_tgt/MACHO_COMPATIBILITY_VERSION + /prop_tgt/MACHO_CURRENT_VERSION /prop_tgt/MACOSX_BUNDLE_INFO_PLIST /prop_tgt/MACOSX_BUNDLE /prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST @@ -348,6 +356,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 @@ -396,6 +405,7 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS /prop_tgt/XCTEST @@ -442,8 +452,8 @@ Properties on Source Files :maxdepth: 1 /prop_sf/ABSTRACT - /prop_sf/AUTOUIC_OPTIONS /prop_sf/AUTORCC_OPTIONS + /prop_sf/AUTOUIC_OPTIONS /prop_sf/COMPILE_DEFINITIONS /prop_sf/COMPILE_FLAGS /prop_sf/COMPILE_OPTIONS diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index f233d0884a5..e8badd4b87f 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -233,6 +233,9 @@ value to those supported compilers when compiling: set(CMAKE_CXX_COMPILER QCC) set(CMAKE_CXX_COMPILER_TARGET ${arch}) + set(CMAKE_SYSROOT $ENV{QNX_TARGET}) + + Cross Compiling for Windows CE ------------------------------ diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 53b7f8ddd5f..fc277394982 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -14,6 +14,7 @@ For general information on variables, see the :ref:`Variables ` section in the cmake-language manual. +.. include:: ID_RESERVE.txt Variables that Provide Information ================================== @@ -37,17 +38,24 @@ Variables that Provide Information /variable/CMAKE_CROSSCOMPILING_EMULATOR /variable/CMAKE_CTEST_COMMAND /variable/CMAKE_CURRENT_BINARY_DIR + /variable/CMAKE_CURRENT_FUNCTION + /variable/CMAKE_CURRENT_FUNCTION_LIST_DIR + /variable/CMAKE_CURRENT_FUNCTION_LIST_FILE + /variable/CMAKE_CURRENT_FUNCTION_LIST_LINE /variable/CMAKE_CURRENT_LIST_DIR /variable/CMAKE_CURRENT_LIST_FILE /variable/CMAKE_CURRENT_LIST_LINE /variable/CMAKE_CURRENT_SOURCE_DIR + /variable/CMAKE_DEBUG_TARGET_PROPERTIES /variable/CMAKE_DIRECTORY_LABELS /variable/CMAKE_DL_LIBS + /variable/CMAKE_DOTNET_TARGET_FRAMEWORK /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION /variable/CMAKE_EDIT_COMMAND /variable/CMAKE_EXECUTABLE_SUFFIX /variable/CMAKE_EXTRA_GENERATOR /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES + /variable/CMAKE_FIND_DEBUG_MODE /variable/CMAKE_FIND_PACKAGE_NAME /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION /variable/CMAKE_FIND_PACKAGE_SORT_ORDER @@ -59,6 +67,7 @@ Variables that Provide Information /variable/CMAKE_IMPORT_LIBRARY_SUFFIX /variable/CMAKE_JOB_POOL_COMPILE /variable/CMAKE_JOB_POOL_LINK + /variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR /variable/CMAKE_LANG_COMPILER_RANLIB @@ -70,7 +79,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 @@ -155,7 +163,6 @@ Variables that Change Behavior /variable/CMAKE_CODELITE_USE_TARGETS /variable/CMAKE_COLOR_MAKEFILE /variable/CMAKE_CONFIGURATION_TYPES - /variable/CMAKE_DEBUG_TARGET_PROPERTIES /variable/CMAKE_DEPENDS_IN_PROJECT_ONLY /variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName /variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES @@ -206,6 +213,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 @@ -214,6 +225,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 @@ -239,6 +251,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 @@ -248,6 +261,7 @@ Variables that Change Behavior /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS /variable/PackageName_ROOT @@ -309,6 +323,7 @@ Variables that Control the Build .. toctree:: :maxdepth: 1 + /variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS /variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS /variable/CMAKE_ANDROID_API /variable/CMAKE_ANDROID_API_MIN @@ -357,9 +372,14 @@ Variables that Control the Build /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_CONFIG_POSTFIX + /variable/CMAKE_CROSS_CONFIGS + /variable/CMAKE_CTEST_ARGUMENTS /variable/CMAKE_CUDA_SEPARABLE_COMPILATION /variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS + /variable/CMAKE_CUDA_RUNTIME_LIBRARY /variable/CMAKE_DEBUG_POSTFIX + /variable/CMAKE_DEFAULT_BUILD_TYPE + /variable/CMAKE_DEFAULT_CONFIGS /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS @@ -466,6 +486,7 @@ Variables for Languages /variable/CMAKE_COMPILER_IS_GNUCC /variable/CMAKE_COMPILER_IS_GNUCXX /variable/CMAKE_COMPILER_IS_GNUG77 + /variable/CMAKE_CUDA_COMPILE_FEATURES /variable/CMAKE_CUDA_HOST_COMPILER /variable/CMAKE_CUDA_EXTENSIONS /variable/CMAKE_CUDA_STANDARD diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 4ab55a0d0f4..28a081f969f 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. @@ -226,6 +241,12 @@ Options Print extra information during the cmake run like stack traces with :command:`message(SEND_ERROR)` calls. +``--debug-find`` + Put cmake find in a debug mode. + + Print extra find call information during the cmake run to standard + error. Output is designed for human consumption and not for parsing. + ``--trace`` Put cmake in trace mode. @@ -236,6 +257,74 @@ Options Like ``--trace``, but with variables expanded. +``--trace-format=`` + Put cmake in trace mode and sets the trace output format. + + ```` can be one of the following values. + + ``human`` + Prints each trace line in a human-readable format. This is the + default format. + + ``json-v1`` + Prints each line as a separate JSON document. Each document is + separated by a newline ( ``\n`` ). It is guaranteed that no + newline characters will be present inside a JSON document. + + JSON trace format: + + .. code-block:: json + + { + "file": "/full/path/to/the/CMake/file.txt", + "line": 0, + "cmd": "add_executable", + "args": ["foo", "bar"], + "time": 1579512535.9687231, + "frame": 2 + } + + The members are: + + ``file`` + The full path to the CMake source file where the function + was called. + + ``line`` + The line in ``file`` of the function call. + + ``cmd`` + The name of the function that was called. + + ``args`` + A string list of all function parameters. + + ``time`` + Timestamp (seconds since epoch) of the function call. + + ``frame`` + Stack frame depth of the function that was called. + + Additionally, the first JSON document outputted contains the + ``version`` key for the current major and minor version of the + + JSON trace format: + + .. code-block:: json + + { + "version": { + "major": 1, + "minor": 0 + } + } + + The members are: + + ``version`` + Indicates the version of the JSON format. The version has a + major and minor components following semantic version conventions. + ``--trace-source=`` Put cmake in trace mode, but output only lines of a specified file. @@ -539,22 +628,38 @@ Available commands are: 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt ``remove [-f] ...`` - Remove the file(s). If any of the listed files already do not - exist, the command returns a non-zero exit code, but no message - is logged. The ``-f`` option changes the behavior to return a + .. deprecated:: 3.17 + + Remove the file(s). The planned behaviour was that if any of the + listed files already do not exist, the command returns a non-zero exit code, + but no message is logged. The ``-f`` option changes the behavior to return a zero exit code (i.e. success) in such situations instead. ``remove`` does not follow symlinks. That means it remove only symlinks and not files it point to. + The implementation was buggy and always returned 0. It cannot be fixed without + breaking backwards compatibility. Use ``rm`` instead. + ``remove_directory ...`` - Remove ```` directories and their contents. If a directory does + .. deprecated:: 3.17 + + Remove ```` directories and their contents. If a directory does not exist it will be silently ignored. If ```` is a symlink to a directory, just the symlink will be removed. + Use ``rm`` instead. ``rename `` Rename a file or directory (on one volume). If file with the ```` name already exists, then it will be silently replaced. +``rm [-rRf] ...`` + Remove the files ```` or directories ``dir``. + Use ``-r`` or ``-R`` to remove directories and their contents recursively. + If any of the listed files/directories do not exist, the command returns a + non-zero exit code, but no message is logged. The ``-f`` option changes + the behavior to return a zero exit code (i.e. success) in such + situations instead. + ``server`` Launch :manual:`cmake-server(7)` mode. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index e29ebcaf6a9..6503f0e2992 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -261,10 +261,27 @@ Options fail, subsequent calls to CTest with the ``--rerun-failed`` option will run the set of tests that most recently failed (if any). -``--repeat-until-fail `` - Require each test to run ```` times without failing in order to pass. +``--repeat :`` + Run tests repeatedly based on the given ```` up to ```` times. + The modes are: + + ``until-fail`` + Require each test to run ```` times without failing in order to pass. + This is useful in finding sporadic failures in test cases. + + ``until-pass`` + Allow each test to run up to ```` times in order to pass. + Repeats tests if they fail for any reason. + This is useful in tolerating sporadic failures in test cases. + + ``after-timeout`` + Allow each test to run up to ```` times in order to pass. + Repeats tests only if they timeout. + This is useful in tolerating sporadic timeouts in test cases + on busy machines. - This is useful in finding sporadic failures in test cases. +``--repeat-until-fail `` + Equivalent to ``--repeat until-fail:``. ``--max-width `` Set the max width for a test name to output. @@ -353,6 +370,14 @@ See `Build and Test Mode`_. This option will not run any tests, it will simply print the list of all labels associated with the test set. +``--no-tests=<[error|ignore]>`` + Regard no tests found either as error or ignore it. + + If no tests were found, the default behavior of CTest is to always log an + error message but to return an error code in script mode only. This option + unifies the behavior of CTest by either returning an error code if no tests + were found or by ignoring it. + .. include:: OPTIONS_HELP.txt .. _`Label and Subproject Summary`: @@ -1096,6 +1121,20 @@ Additional configuration settings include: * `CTest Script`_ variable: none * :module:`CTest` module variable: ``VALGRIND_COMMAND_OPTIONS`` +``DrMemoryCommand`` + Specify a ``MemoryCheckCommand`` that is known to be a command-line + compatible with DrMemory. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``DRMEMORY_COMMAND`` + +``DrMemoryCommandOptions`` + Specify command-line options to the ``DrMemoryCommand`` tool. + They will be placed prior to the test command line. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``DRMEMORY_COMMAND_OPTIONS`` + .. _`CTest Submit Step`: CTest Submit Step @@ -1292,6 +1331,15 @@ the running machine. This allows CTest to internally keep track of which resources are in use and which are free, scheduling tests in a way that prevents them from trying to claim resources that are not available. +When the resource allocation feature is used, CTest will not oversubscribe +resources. For example, if a resource has 8 slots, CTest will not run tests +that collectively use more than 8 slots at a time. This has the effect of +limiting how many tests can run at any given time, even if a high ``-j`` +argument is used, if those tests all use some slots from the same resource. +In addition, it means that a single test that uses more of a resource than is +available on a machine will not run at all (and will be reported as +``Not Run``). + A common use case for this feature is for tests that require the use of a GPU. Multiple tests can simultaneously allocate memory from a GPU, but if too many tests try to do this at once, some of them will fail to allocate, resulting in diff --git a/Help/module/FindCUDAToolkit.rst b/Help/module/FindCUDAToolkit.rst new file mode 100644 index 00000000000..5f01d68846b --- /dev/null +++ b/Help/module/FindCUDAToolkit.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindCUDAToolkit.cmake diff --git a/Help/policy/CMP0098.rst b/Help/policy/CMP0098.rst new file mode 100644 index 00000000000..6d1443b764c --- /dev/null +++ b/Help/policy/CMP0098.rst @@ -0,0 +1,30 @@ +CMP0098 +------- + +:module:`FindFLEX` runs ``flex`` in directory +:variable:`CMAKE_CURRENT_BINARY_DIR` when executing. + +The module provides a ``FLEX_TARGET`` macro which generates FLEX output. +In CMake 3.16 and below the macro would generate a custom command that runs +``flex`` in the current source directory. CMake 3.17 and later prefer to +run it in the build directory and use :variable:`CMAKE_CURRENT_BINARY_DIR` +as the ``WORKING_DIRECTORY`` of its :command:`add_custom_command` invocation. +This ensures that any implicitly generated file is written relative to the +build tree rather than the source tree, unless the generated file is +provided as absolute path. + +This policy provides compatibility for projects that have not been updated +to expect the new behavior. + +The ``OLD`` behavior for this policy is for ``FLEX_TARGET`` to use +the current source directory for the ``WORKING_DIRECTORY`` and where +to generate implicit files. The ``NEW`` behavior of this policy is to +use the current binary directory for the ``WORKING_DIRECTORY`` relative to +which implicit files are generated unless provided as absolute path. + +This policy was introduced in CMake version 3.17. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0099.rst b/Help/policy/CMP0099.rst new file mode 100644 index 00000000000..c897e7ba2bd --- /dev/null +++ b/Help/policy/CMP0099.rst @@ -0,0 +1,24 @@ +CMP0099 +------- + +Target link properties :prop_tgt:`INTERFACE_LINK_OPTIONS`, +:prop_tgt:`INTERFACE_LINK_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_DEPENDS` +are now transitive over private dependencies of static libraries. + +In CMake 3.16 and below the interface link properties attached to libraries +are not propagated for private dependencies of static libraries. +Only the libraries themselves are propagated to link the dependent binary. +CMake 3.17 and later prefer to propagate all interface link properties. +This policy provides compatibility for projects that have not been updated +to expect the new behavior. + +The ``OLD`` behavior for this policy is to not propagate interface link +properties. The ``NEW`` behavior of this policy is to propagate interface link +properties. + +This policy was introduced in CMake version 3.17. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0100.rst b/Help/policy/CMP0100.rst new file mode 100644 index 00000000000..b24d013a962 --- /dev/null +++ b/Help/policy/CMP0100.rst @@ -0,0 +1,40 @@ +CMP0100 +------- + +Let :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` process +header files that end with a ``.hh`` extension. + +Since version 3.17, CMake processes header files that end with a +``.hh`` extension in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. +In earlier CMake versions, these header files were ignored by +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +This policy affects how header files that end with a ``.hh`` extension +get treated in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The ``OLD`` behavior for this policy is to ignore ``.hh`` header files +in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The ``NEW`` behavior for this policy is to process ``.hh`` header files +in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` just like other header files. + +.. note:: + + To silence the ``CMP0100`` warning source files can be excluded from + :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing by setting the + source file properties :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` or + :prop_sf:`SKIP_AUTOGEN`. + + .. code-block:: cmake + + # Source skip example: + set_property(SOURCE /path/to/file1.hh PROPERTY SKIP_AUTOMOC ON) + set_property(SOURCE /path/to/file2.hh PROPERTY SKIP_AUTOUIC ON) + set_property(SOURCE /path/to/file3.hh PROPERTY SKIP_AUTOGEN ON) + +This policy was introduced in CMake version 3.17.0. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0101.rst b/Help/policy/CMP0101.rst new file mode 100644 index 00000000000..9941acfc642 --- /dev/null +++ b/Help/policy/CMP0101.rst @@ -0,0 +1,20 @@ +CMP0101 +------- + +:command:`target_compile_options` now honors ``BEFORE`` keyword in all scopes. + +In CMake 3.16 and below the :command:`target_compile_options` ignores the +``BEFORE`` keyword in private scope. CMake 3.17 and later honors +``BEFORE`` keyword in all scopes. This policy provides compatibility for +projects that have not been updated to expect the new behavior. + +The ``OLD`` behavior for this policy is to not honor ``BEFORE`` keyword in +private scope. The ``NEW`` behavior of this policy is to honor +``BEFORE`` keyword in all scopes. + +This policy was introduced in CMake version 3.17. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0102.rst b/Help/policy/CMP0102.rst new file mode 100644 index 00000000000..9859006ea09 --- /dev/null +++ b/Help/policy/CMP0102.rst @@ -0,0 +1,25 @@ +CMP0102 +------- + +The :command:`mark_as_advanced` command no longer creates a cache entry if one +does not already exist. + +In CMake 3.16 and below, if a variable was not defined at all or just defined +locally, the :command:`mark_as_advanced` command would create a new cache +entry with an ``UNINITIALIZED`` type and no value. When a :command:`find_path` +(or other similar ``find_`` command) would next run, it would find this +undefined cache entry and set it up with an empty string value. This process +would end up deleting the local variable in the process (due to the way the +cache works), effectively clearing any stored ``find_`` results that were only +available in the local scope. + +The ``OLD`` behavior for this policy is to create the empty cache definition. +The ``NEW`` behavior of this policy is to ignore variables which do not +already exist in the cache. + +This policy was introduced in CMake version 3.17. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst new file mode 100644 index 00000000000..44e37fe1c58 --- /dev/null +++ b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst @@ -0,0 +1,30 @@ +CMAKE_CUDA_KNOWN_FEATURES +------------------------- + +List of CUDA features known to this version of CMake. + +The features listed in this global property may be known to be available to the +CUDA compiler. If the feature is available with the C++ compiler, it will +be listed in the :variable:`CMAKE_CUDA_COMPILE_FEATURES` variable. + +The features listed here may be used with the :command:`target_compile_features` +command. See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + + +The features known to this version of CMake are: + +``cuda_std_03`` + Compiler mode is at least CUDA/C++ 03. + +``cuda_std_11`` + Compiler mode is at least CUDA/C++ 11. + +``cuda_std_14`` + Compiler mode is at least CUDA/C++ 14. + +``cuda_std_17`` + Compiler mode is at least CUDA/C++ 17. + +``cuda_std_20`` + Compiler mode is at least CUDA/C++ 20. diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst index d430ee264f0..48ff70c7b3e 100644 --- a/Help/prop_sf/GENERATED.rst +++ b/Help/prop_sf/GENERATED.rst @@ -4,16 +4,29 @@ GENERATED Is this source file generated as part of the build or CMake process. Tells the internal CMake engine that a source file is generated by an outside -process such as another build step, or the execution of CMake itself. This -information is then used to exempt the file from any existence or validity -checks. Generated files are created by the execution of commands such as -:command:`add_custom_command` and :command:`file(GENERATE)`. - -When a generated file created by an :command:`add_custom_command` command -is explicitly listed as a source file for any target in the same -directory scope (which usually means the same ``CMakeLists.txt`` file), -CMake will automatically create a dependency to make sure the file is -generated before building that target. +process such as another build step, or the execution of CMake itself. +This information is then used to exempt the file from any existence or +validity checks. + +Any file that is + +- created by the execution of commands such as + :command:`add_custom_command` and :command:`file(GENERATE)` +- listed as one of the ``BYPRODUCTS`` of an :command:`add_custom_command` + or :command:`add_custom_target` command, or +- created by a CMake ``AUTOGEN`` operation such as :prop_tgt:`AUTOMOC`, + :prop_tgt:`AUTORCC`, or :prop_tgt:`AUTOUIC` + +will be marked with the ``GENERATED`` property. + +When a generated file created as the ``OUTPUT`` of an +:command:`add_custom_command` command is explicitly listed as a source file +for any target in the same directory scope (which usually means the same +``CMakeLists.txt`` file), CMake will automatically create a dependency to +make sure the file is generated before building that target. + +The :ref:`Makefile Generators` will remove ``GENERATED`` files during +``make clean``. Generated sources may be hidden in some IDE tools, while in others they might be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC` diff --git a/Help/prop_tgt/AIX_EXPORT_ALL_SYMBOLS.rst b/Help/prop_tgt/AIX_EXPORT_ALL_SYMBOLS.rst new file mode 100644 index 00000000000..15ddc0b2d95 --- /dev/null +++ b/Help/prop_tgt/AIX_EXPORT_ALL_SYMBOLS.rst @@ -0,0 +1,12 @@ +AIX_EXPORT_ALL_SYMBOLS +---------------------- + +On AIX, CMake automatically exports all symbols from shared libraries, and +from executables with the :prop_tgt:`ENABLE_EXPORTS` target property set. +Explicitly disable this boolean property to suppress the behavior and +export no symbols by default. In this case it is expected that the project +will use other means to export some symbols. + +This property is initialized by the value of +the :variable:`CMAKE_AIX_EXPORT_ALL_SYMBOLS` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/AUTOGEN_PARALLEL.rst b/Help/prop_tgt/AUTOGEN_PARALLEL.rst index 07fbc5a5efe..968b619e8af 100644 --- a/Help/prop_tgt/AUTOGEN_PARALLEL.rst +++ b/Help/prop_tgt/AUTOGEN_PARALLEL.rst @@ -4,9 +4,9 @@ AUTOGEN_PARALLEL Number of parallel ``moc`` or ``uic`` processes to start when using :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. -The custom `_autogen` target starts a number of threads of which +The custom ``_autogen`` target starts a number of threads of which each one parses a source file and on demand starts a ``moc`` or ``uic`` -process. :prop_tgt:`AUTOGEN_PARALLEL` controls how many parallel threads +process. ``AUTOGEN_PARALLEL`` controls how many parallel threads (and therefore ``moc`` or ``uic`` processes) are started. - An empty (or unset) value or the string ``AUTO`` sets the number of @@ -14,7 +14,7 @@ process. :prop_tgt:`AUTOGEN_PARALLEL` controls how many parallel threads - A positive non zero integer value sets the exact thread/process count. - Otherwise a single thread/process is started. -By default :prop_tgt:`AUTOGEN_PARALLEL` is initialized from +By default ``AUTOGEN_PARALLEL`` is initialized from :variable:`CMAKE_AUTOGEN_PARALLEL`. See the :manual:`cmake-qt(7)` manual for more information on using CMake diff --git a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst index d5c5e147d4b..92b52a3e18d 100644 --- a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -33,4 +33,4 @@ If :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` depends on a file that is either :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` or - a file that isn't in the origin target's sources -it must added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`. +it must be added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index f6dfabdd3c7..c18859b5692 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -172,7 +172,7 @@ variables. If the call is in a different context than the then the version variables might not be available to the :prop_tgt:`AUTOMOC` enabled target. In that case the version variables can be forwarded from the -`find_package(Qt[45]...)` calling context to the :command:`add_executable` +``find_package(Qt[45]...)`` calling context to the :command:`add_executable` or :command:`add_library` calling context as directory properties. The following Qt5 example demonstrates the procedure. diff --git a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst index 69957bf1825..6eda26c4f66 100644 --- a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst +++ b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst @@ -26,6 +26,9 @@ See :prop_tgt:`AUTOGEN_TARGET_DEPENDS` for reference. By default :prop_tgt:`AUTOMOC_DEPEND_FILTERS` is initialized from :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS`, which is empty by default. +From Qt 5.15.0 on this variable is ignored as moc is able to output the correct +dependencies. + See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst b/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst index ebd5c4951b3..330849bee23 100644 --- a/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst +++ b/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst @@ -1,7 +1,7 @@ AUTOMOC_MOC_OPTIONS ------------------- -Additional options for moc when using :prop_tgt:`AUTOMOC` +Additional options for ``moc`` when using :prop_tgt:`AUTOMOC` This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` for this target. In this case, it holds additional command line @@ -9,7 +9,9 @@ options which will be used when ``moc`` is executed during the build, i.e. it is equivalent to the optional ``OPTIONS`` argument of the :module:`qt4_wrap_cpp() ` macro. -By default it is empty. +This property is initialized by the value of the +:variable:`CMAKE_AUTOMOC_MOC_OPTIONS` variable if it is set when a target +is created, or an empty string otherwise. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst index e2ebb3ffc11..3e3059d7aa3 100644 --- a/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst +++ b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst @@ -21,11 +21,11 @@ with Qt. Reproducible builds ^^^^^^^^^^^^^^^^^^^ -For reproducible builds is is recommended to keep headers that are ``moc`` +For reproducible builds it is recommended to keep headers that are ``moc`` compiled in one of the target :command:`include directories ` and set :prop_tgt:`AUTOMOC_PATH_PREFIX` to ``ON`` (which is the default). This ensures -that +that: - ``moc`` output files are identical on different build setups, - ``moc`` output files will compile correctly when the source and/or diff --git a/Help/prop_tgt/AUTORCC.rst b/Help/prop_tgt/AUTORCC.rst index cca3e583fb7..9a98f440ce9 100644 --- a/Help/prop_tgt/AUTORCC.rst +++ b/Help/prop_tgt/AUTORCC.rst @@ -31,9 +31,10 @@ Modifiers The ``rcc`` executable will be detected automatically, but can be forced to a certain binary by setting this target property. -:prop_sf:`AUTORCC_OPTIONS`: -Additional command line options for ``rcc`` can be set via this ``.qrc`` -source file property. +:prop_tgt:`AUTORCC_OPTIONS`: +Additional command line options for ``rcc`` can be set via this target +property. The corresponding :prop_sf:`AUTORCC_OPTIONS` source file property +can be used to specify options to be applied only to a specific ``.qrc`` file. :prop_sf:`SKIP_AUTORCC`: ``.qrc`` files can be excluded from :prop_tgt:`AUTORCC` processing by diff --git a/Help/prop_tgt/AUTORCC_OPTIONS.rst b/Help/prop_tgt/AUTORCC_OPTIONS.rst index d6ade5adbf0..5261aff230c 100644 --- a/Help/prop_tgt/AUTORCC_OPTIONS.rst +++ b/Help/prop_tgt/AUTORCC_OPTIONS.rst @@ -8,11 +8,9 @@ when ``rcc`` is executed during the build via :prop_tgt:`AUTORCC`, i.e. it is equivalent to the optional ``OPTIONS`` argument of the :module:`qt4_add_resources() ` macro. -By default it is empty. - This property is initialized by the value of the :variable:`CMAKE_AUTORCC_OPTIONS` variable if it is set when a target is -created. +created, or an empty string otherwise. The options set on the target may be overridden by :prop_sf:`AUTORCC_OPTIONS` set on the ``.qrc`` source file. diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index 5cf87552ced..cd24f5e5905 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -52,8 +52,11 @@ Modifiers The ``uic`` executable will be detected automatically, but can be forced to a certain binary using this target property. -:prop_sf:`AUTOUIC_OPTIONS`: Additional command line options for ``uic`` can -be set via this source file property on a ``.ui`` file. +:prop_tgt:`AUTOUIC_OPTIONS`: +Additional command line options for ``uic`` can be set via this target +property. The corresponding :prop_sf:`AUTOUIC_OPTIONS` source file property +can be used to specify options to be applied only to a specific +``.ui`` file. :prop_sf:`SKIP_AUTOUIC`: Source files can be excluded from :prop_tgt:`AUTOUIC` processing by setting diff --git a/Help/prop_tgt/AUTOUIC_OPTIONS.rst b/Help/prop_tgt/AUTOUIC_OPTIONS.rst index 3f613b952cb..425ea1c7998 100644 --- a/Help/prop_tgt/AUTOUIC_OPTIONS.rst +++ b/Help/prop_tgt/AUTOUIC_OPTIONS.rst @@ -8,11 +8,9 @@ This property holds additional command line options which will be used when equivalent to the optional ``OPTIONS`` argument of the :module:`qt4_wrap_ui() ` macro. -By default it is empty. - This property is initialized by the value of the :variable:`CMAKE_AUTOUIC_OPTIONS` variable if it is set when a target is -created. +created, or an empty string otherwise. The options set on the target may be overridden by :prop_sf:`AUTOUIC_OPTIONS` set on the ``.ui`` source file. diff --git a/Help/prop_tgt/COMPILE_FEATURES.rst b/Help/prop_tgt/COMPILE_FEATURES.rst index 195215e3c81..46aec4ff411 100644 --- a/Help/prop_tgt/COMPILE_FEATURES.rst +++ b/Help/prop_tgt/COMPILE_FEATURES.rst @@ -4,7 +4,8 @@ COMPILE_FEATURES Compiler features enabled for this target. The list of features in this property are a subset of the features listed -in the :variable:`CMAKE_CXX_COMPILE_FEATURES` variable. +in the :variable:`CMAKE_C_COMPILE_FEATURES`, :variable:`CMAKE_CUDA_COMPILE_FEATURES`, and +:variable:`CMAKE_CXX_COMPILE_FEATURES` variables. Contents of ``COMPILE_FEATURES`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for diff --git a/Help/prop_tgt/CUDA_RUNTIME_LIBRARY-VALUES.txt b/Help/prop_tgt/CUDA_RUNTIME_LIBRARY-VALUES.txt new file mode 100644 index 00000000000..a6d7050a922 --- /dev/null +++ b/Help/prop_tgt/CUDA_RUNTIME_LIBRARY-VALUES.txt @@ -0,0 +1,9 @@ +``None`` + Link with ``-cudart=none`` or equivalent flag(s) to use no CUDA + runtime library. +``Shared`` + Link with ``-cudart=shared`` or equivalent flag(s) to use a + dynamically-linked CUDA runtime library. +``Static`` + Link with ``-cudart=static`` or equivalent flag(s) to use a + statically-linked CUDA runtime library. diff --git a/Help/prop_tgt/CUDA_RUNTIME_LIBRARY.rst b/Help/prop_tgt/CUDA_RUNTIME_LIBRARY.rst new file mode 100644 index 00000000000..07827655d08 --- /dev/null +++ b/Help/prop_tgt/CUDA_RUNTIME_LIBRARY.rst @@ -0,0 +1,21 @@ +CUDA_RUNTIME_LIBRARY +-------------------- + +Select the CUDA runtime library for use by compilers targeting the CUDA language. + +The allowed case insensitive values are: + +.. include:: CUDA_RUNTIME_LIBRARY-VALUES.txt + +Contents of ``CUDA_RUNTIME_LIBRARY`` may use +:manual:`generator expressions `. + +If this property is not set then CMake uses the default value +``Static`` to select the CUDA runtime library. + +.. note:: + + This property has effect only when the ``CUDA`` language is enabled. To + control the CUDA runtime linking when only using the CUDA SDK with the + ``C`` or ``C++`` language we recommend using the :module:`FindCUDAToolkit` + module. diff --git a/Help/prop_tgt/DEPRECATION.rst b/Help/prop_tgt/DEPRECATION.rst new file mode 100644 index 00000000000..fef2e2e3aa0 --- /dev/null +++ b/Help/prop_tgt/DEPRECATION.rst @@ -0,0 +1,7 @@ +DEPRECATION +----------- + +Deprecation message from imported target's developer. + +``DEPRECATION`` is the message regarding a deprecation status to be displayed +to downstream users of a target. diff --git a/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK.rst b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK.rst new file mode 100644 index 00000000000..8698eb67b98 --- /dev/null +++ b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK.rst @@ -0,0 +1,13 @@ +DOTNET_TARGET_FRAMEWORK +----------------------- + +Specify the .NET target framework. + +Used to specify the .NET target framework for C++/CLI and C#. For +example: ``netcoreapp2.1``. + +This property is only evaluated for :ref:`Visual Studio Generators` +VS 2010 and above. + +Can be initialized for all targets using the variable +:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK`. diff --git a/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst index c100326b910..b33f4fb4809 100644 --- a/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst +++ b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -3,11 +3,13 @@ DOTNET_TARGET_FRAMEWORK_VERSION Specify the .NET target framework version. -Used to specify the .NET target framework version for C++/CLI. For -example: ``v4.5``. +Used to specify the .NET target framework version for C++/CLI and C#. +For example: ``v4.5``. This property is only evaluated for :ref:`Visual Studio Generators` VS 2010 and above. -Can be initialized for all targets using the variable -:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION`. +To initialize this variable for all targets set +:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK` or +:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION`. If both are set, +the latter is ignored. diff --git a/Help/prop_tgt/INSTALL_NAME_DIR.rst b/Help/prop_tgt/INSTALL_NAME_DIR.rst index 2216072acb1..747615ac8e5 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 `. +In particular, the ``$`` generator expression can be used to set the +directory relative to the install-time prefix. diff --git a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst index d8be9548a3d..d16a7a1c61e 100644 --- a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst @@ -3,8 +3,12 @@ INSTALL_RPATH_USE_LINK_PATH Add paths to linker search and installed rpath. -``INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``True`` will -append directories in the linker search path and outside the project -to the :prop_tgt:`INSTALL_RPATH`. This property is initialized by the value of -the variable ``CMAKE_INSTALL_RPATH_USE_LINK_PATH`` if it is set when a -target is created. +``INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``True`` +will append to the runtime search path (rpath) of installed binaries +any directories outside the project that are in the linker search path or +contain linked library files. The directories are appended after the +value of the :prop_tgt:`INSTALL_RPATH` target property. + +This property is initialized by the value of the variable +:variable:`CMAKE_INSTALL_RPATH_USE_LINK_PATH` if it is set when a target is +created. diff --git a/Help/prop_tgt/JOB_POOL_PRECOMPILE_HEADER.rst b/Help/prop_tgt/JOB_POOL_PRECOMPILE_HEADER.rst new file mode 100644 index 00000000000..ece28a4e815 --- /dev/null +++ b/Help/prop_tgt/JOB_POOL_PRECOMPILE_HEADER.rst @@ -0,0 +1,21 @@ +JOB_POOL_PRECOMPILE_HEADER +-------------------------- + +Ninja only: Pool used for generating pre-compiled headers. + +The number of parallel compile processes could be limited by defining +pools with the global :prop_gbl:`JOB_POOLS` +property and then specifying here the pool name. + +For instance: + +.. code-block:: cmake + + set_property(TARGET myexe PROPERTY JOB_POOL_PRECOMPILE_HEADER two_jobs) + +This property is initialized by the value of +:variable:`CMAKE_JOB_POOL_PRECOMPILE_HEADER`. + +If neither :prop_tgt:`JOB_POOL_PRECOMPILE_HEADER` nor +:variable:`CMAKE_JOB_POOL_PRECOMPILE_HEADER` are set then +:prop_tgt:`JOB_POOL_COMPILE` will be used for this task. diff --git a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst index 23af503af18..a6f2b24f62f 100644 --- a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -2,7 +2,7 @@ ------------------------ This property is implemented only when ```` is ``C``, ``CXX``, -``Fortran``, or ``CUDA``. +``Fortran``, ``OBJC``, ``OBJCXX``, or ``CUDA``. Specify a :ref:`semicolon-separated list ` containing a command line for a compiler launching tool. The :ref:`Makefile Generators` and the diff --git a/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt b/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt index 1fdb6ad0e22..476e4a68612 100644 --- a/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt +++ b/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt @@ -1,9 +1,9 @@ .. note:: A call to :command:`target_link_libraries( ...)` may update this property on ````. If ```` was not created in the same - directory as the call then :command:`target_link_libraries` will add a - suffix of the form ``::@`` to each entry, where the - ``::@`` is a separator and the ```` is unspecified. + directory as the call then :command:`target_link_libraries` will wrap each + entry with the form ``::@(directory-id);...;::@``, where the ``::@`` is + literal and the ``(directory-id)`` is unspecified. This tells the generators that the named libraries must be looked up in the scope of the caller rather than in the scope in which the ```` was created. Valid directory ids are stripped on export diff --git a/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst b/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst new file mode 100644 index 00000000000..f3fedbabe86 --- /dev/null +++ b/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst @@ -0,0 +1,14 @@ +MACHO_COMPATIBILITY_VERSION +--------------------------- + +What compatibility version number is this target for Mach-O binaries. + +For shared libraries on Mach-O systems (e.g. macOS, iOS) +the ``MACHO_COMPATIBILITY_VERSION`` property correspond to +``compatibility version`` and :prop_tgt:`MACHO_CURRENT_VERSION` to +``current version``. +See the :prop_tgt:`FRAMEWORK` target property for an example. + +Versions of Mach-O binaries may be checked with the ``otool -L `` +command. If ``MACHO_COMPATIBILITY_VERSION`` is not set, the value of +the :prop_tgt:`SOVERSION` property will be used. diff --git a/Help/prop_tgt/MACHO_CURRENT_VERSION.rst b/Help/prop_tgt/MACHO_CURRENT_VERSION.rst new file mode 100644 index 00000000000..4a1d3f06383 --- /dev/null +++ b/Help/prop_tgt/MACHO_CURRENT_VERSION.rst @@ -0,0 +1,13 @@ +MACHO_CURRENT_VERSION +--------------------- + +What current version number is this target for Mach-O binaries. + +For shared libraries on Mach-O systems (e.g. macOS, iOS) +the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` property correspond to +``compatibility version`` and ``MACHO_CURRENT_VERSION`` to ``current version``. +See the :prop_tgt:`FRAMEWORK` target property for an example. + +Versions of Mach-O binaries may be checked with the ``otool -L `` +command. If ``MACHO_CURRENT_VERSION`` is not set, the value of +the :prop_tgt:`VERSION` property will be used. diff --git a/Help/prop_tgt/SOVERSION.rst b/Help/prop_tgt/SOVERSION.rst index b07c17cfe02..d6f8a941f7a 100644 --- a/Help/prop_tgt/SOVERSION.rst +++ b/Help/prop_tgt/SOVERSION.rst @@ -21,7 +21,9 @@ Mach-O Versions ^^^^^^^^^^^^^^^ For shared libraries and executables on Mach-O systems (e.g. macOS, iOS), -the ``SOVERSION`` property corresponds to *compatibility version* and -:prop_tgt:`VERSION` to *current version*. See the :prop_tgt:`FRAMEWORK` target -property for an example. Versions of Mach-O binaries may be checked with the -``otool -L `` command. +the ``SOVERSION`` property is a fallback to +:prop_tgt:`MACHO_COMPATIBILITY_VERSION` property which corresponds to +*compatiblity version* and :prop_tgt:`VERSION` is a fallback to +:prop_tgt:`MACHO_CURRENT_VERSION` which corresponds to *current version*. +See the :prop_tgt:`FRAMEWORK` target property for an example. Versions +of Mach-O binaries may be checked with the ``otool -L `` command. diff --git a/Help/prop_tgt/VERSION.rst b/Help/prop_tgt/VERSION.rst index ff3b3030fa9..f592f4a6114 100644 --- a/Help/prop_tgt/VERSION.rst +++ b/Help/prop_tgt/VERSION.rst @@ -23,7 +23,9 @@ Mach-O Versions ^^^^^^^^^^^^^^^ For shared libraries and executables on Mach-O systems (e.g. macOS, iOS), -the :prop_tgt:`SOVERSION` property correspond to *compatibility version* and -``VERSION`` to *current version*. See the :prop_tgt:`FRAMEWORK` target +the ``VERSION`` property is a fallback to :prop_tgt:`MACHO_CURRENT_VERSION` +property which corresponds to *current version* and :prop_tgt:`SOVERSION` +is a fallback to :prop_tgt:`MACHO_COMPATIBILITY_VERSION` which corresponds +to *compatiblity version*. See the :prop_tgt:`FRAMEWORK` target property for an example. Versions of Mach-O binaries may be checked with the ``otool -L `` command. 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 00000000000..1bc361c3da4 --- /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/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst index 9f5a313d341..6cb8f861cd1 100644 --- a/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst +++ b/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -3,8 +3,9 @@ VS_DOTNET_TARGET_FRAMEWORK_VERSION Specify the .NET target framework version. -Used to specify the .NET target framework version for C++/CLI. For +Used to specify the .NET target framework version for C++/CLI. For example, "v4.5". This property is deprecated and should not be used anymore. Use +:prop_tgt:`DOTNET_TARGET_FRAMEWORK` or :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` instead. diff --git a/Help/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY.rst b/Help/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY.rst new file mode 100644 index 00000000000..7ffa74bb438 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY.rst @@ -0,0 +1,13 @@ +XCODE_SCHEME_WORKING_DIRECTORY +------------------------------ + +Specify the ``Working Directory`` a of the `Run` and `Profile` +action in the generated Xcode scheme. In case the value contains +generator expressions those are evaluated. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_WORKING_DIRECTORY` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst index 0d1cc1ed688..e2d67882176 100644 --- a/Help/release/3.16.rst +++ b/Help/release/3.16.rst @@ -277,3 +277,29 @@ Other Changes * When using :variable:`CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS` on Windows the auto-generated exports are now updated only when the object files providing the symbols are updated. + +Updates +======= + +Changes made since CMake 3.16.0 include the following. + +3.16.2 +------ + +* CMake 3.16.0 and 3.16.1 processed ``.hh`` files with :prop_tgt:`AUTOMOC`. + This was a behavior change from CMake 3.15 and below that can break + existing projects, so it has been reverted as of 3.16.2. + +3.16.5 +------ + +* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3` + modules no longer create cache entries for ``Python{,2,3}_LIBRARY_RELEASE`` + and ``Python{,2,3}_LIBRARY_DEBUG``. Those values are always computed from + other results and so should not be cached. The entries were created by + CMake 3.16.0 through 3.16.4 but were always ``FORCE``-set and could not + be meaningfully edited by users. + + Additionally, the modules no longer expose their internal ``_Python*`` + cache entries publicly. CMake 3.16.0 through 3.16.4 accidentally + made them visible as advanced cache entries. diff --git a/Help/release/3.17.rst b/Help/release/3.17.rst new file mode 100644 index 00000000000..c2cfdf03f73 --- /dev/null +++ b/Help/release/3.17.rst @@ -0,0 +1,321 @@ +CMake 3.17 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.16 include the following. + +New Features +============ + +Generators +---------- + +* :manual:`cmake(1)` gained a :generator:`Ninja Multi-Config` generator, + which is similar to the :generator:`Ninja` generator but can be used to build + multiple configurations at once. + +* :ref:`Visual Studio Generators` learned to support per-config sources. + Previously only :ref:`Command-Line Build Tool Generators` supported them. + +* :ref:`Visual Studio Generators` for VS 2010 and above now support + specifying the ``VCTargetsPath`` value for project files in + :variable:`CMAKE_GENERATOR_TOOLSET` setting. + +* :ref:`Visual Studio Generators` for VS 2010 and above learned to + support .NET Standard and .NET Core. See the + :prop_tgt:`DOTNET_TARGET_FRAMEWORK` target property and + associated :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK` variable. + +Languages +--------- + +* The :manual:`Compile Features ` functionality + now offers meta-features for the CUDA language standard levels + (e.g. ``cuda_std_03``, ``cuda_std_14``). See + :prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES`. + +Compilers +--------- + +* The IBM XL Fortran compiler is now supported by the :generator:`Ninja` + generator. + +Command-Line +------------ + +* :manual:`cmake(1)` gained a ``--debug-find`` command-line option to + enable additional human-readable output on where ``find_*`` commands search. + +* :manual:`cmake(1)` gained a ``--trace-format`` command-line option that + can be used to set the ``--trace`` output format. Currently, the old + human readable and the new JSON format are supported. The new JSON format + is easier to parse automatically than the existing format. + +* :manual:`cmake(1)` gained a ``-E rm`` command-line tool that can be + used to remove directories and files. This supersedes the existing + ``-E remove`` and ``-E remove_directory`` tools and has better semantics. + +Commands +-------- + +* The :command:`add_custom_command` command learned to interpret paths in + ``DEPENDS`` arguments that are specified relative to the current + binary directory. + +* The :command:`foreach` command learned a new ``ZIP_LISTS`` option to iterate + over multiple lists simultaneously. + +* The :command:`load_cache(READ_WITH_PREFIX)` command mode is now allowed + when using ``cmake -P`` to :ref:`Run a Script