diff options
Diffstat (limited to 'Help')
140 files changed, 3144 insertions, 458 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index aba3742..576ed5b 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -112,9 +112,11 @@ 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. Entries in the ``DEPENDS`` + argument list which may also be target names are assumed to be target names, + so only entries which contain a path separator are detected as file paths. + 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 diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 7a3393b..5c67b2c 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 <time-of-day>] [RETURN_VALUE <result-var>] [CAPTURE_CMAKE_ERROR <result-var>] + [REPEAT <mode>:<n>] [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 <mode>:<n>`` + Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times. + The modes are: + + ``UNTIL_FAIL`` + Require each test to run ``<n>`` 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 ``<n>`` 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 ``<n>`` times in order to pass. + Repeats tests only if they timeout. + This is useful in tolerating sporadic timeouts in test cases + on busy machines. + ``SCHEDULE_RANDOM <ON|OFF>`` 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 b186177..5877d43 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -54,7 +54,9 @@ Reading Read content from a file called ``<filename>`` and store it in a ``<variable>``. Optionally start from the given ``<offset>`` and read at most ``<max-in>`` bytes. The ``HEX`` option causes data to -be converted to a hexadecimal representation (useful for binary data). +be converted to a hexadecimal representation (useful for binary data). If the +``HEX`` option is specified, letters in the output (``a`` through ``f``) are in +lowercase. .. _STRINGS: @@ -540,7 +542,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 ae2afb2..a01a104 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 [<lists>]] [ITEMS [<items>]]) + foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]]) In this variant, ``<lists>`` 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(<loop_var>... IN ZIP_LISTS <lists>) + +In this variant, ``<lists>`` 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/install.rst b/Help/command/install.rst index 5affc5b..abf6b17 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -30,13 +30,20 @@ signatures that specify them. The common options are: ``DESTINATION`` Specify the directory on disk to which a file will be installed. - If a full path (with a leading slash or drive letter) is given - it is used directly. If a relative path is given it is interpreted - relative to the value of the :variable:`CMAKE_INSTALL_PREFIX` variable. + Arguments can be relative or absolute paths. + + If a relative path is given it is interpreted relative to the value + of the :variable:`CMAKE_INSTALL_PREFIX` variable. The prefix can be relocated at install time using the ``DESTDIR`` mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable documentation. + If an absolute path (with a leading slash or drive letter) is given + it is used verbatim. + + As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer + generators, it is preferable to use relative paths throughout. + ``PERMISSIONS`` Specify permissions for installed files. Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``, @@ -119,31 +126,38 @@ Installing Targets ) The ``TARGETS`` form specifies rules for installing targets from a -project. There are several kinds of target files that may be installed: +project. There are several kinds of target :ref:`Output Artifacts` +that may be installed: ``ARCHIVE`` - Static libraries are treated as ``ARCHIVE`` targets, except those - marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK`` - below.) For DLL platforms (all Windows-based systems including - Cygwin), the DLL import library is treated as an ``ARCHIVE`` target. - On AIX, the linker import file created for executables with - :prop_tgt:`ENABLE_EXPORTS` is treated as an ``ARCHIVE`` target. + Target artifacts of this kind include: + + * *Static libraries* + (except on macOS when marked as ``FRAMEWORK``, see below); + * *DLL import libraries* + (on all Windows-based systems including Cygwin; they have extension + ``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``); + * On AIX, the *linker import file* created for executables with + :prop_tgt:`ENABLE_EXPORTS` enabled. ``LIBRARY`` - Module libraries are always treated as ``LIBRARY`` targets. For non- - DLL platforms shared libraries are treated as ``LIBRARY`` targets, - except those marked with the ``FRAMEWORK`` property on macOS (see - ``FRAMEWORK`` below.) + Target artifacts of this kind include: + + * *Shared libraries*, except + + - DLLs (these go to ``RUNTIME``, see below), + - on macOS when marked as ``FRAMEWORK`` (see below). ``RUNTIME`` - Executables are treated as ``RUNTIME`` objects, except those marked - with the ``MACOSX_BUNDLE`` property on macOS (see ``BUNDLE`` below.) - For DLL platforms (all Windows-based systems including Cygwin), the - DLL part of a shared library is treated as a ``RUNTIME`` target. + Target artifacts of this kind include: + + * *Executables* + (except on macOS when marked as ``MACOSX_BUNDLE``, see ``BUNDLE`` below); + * DLLs (on all Windows-based systems including Cygwin; note that the + accompanying import libraries are of kind ``ARCHIVE``). ``OBJECTS`` - Object libraries (a simple group of object files) are always treated - as ``OBJECTS`` targets. + Object files associated with *object libraries*. ``FRAMEWORK`` Both static and shared libraries marked with the ``FRAMEWORK`` diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 05e5d79..3f6f2f9 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 5712fb4..e52e623 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 c614286..6bc0e4c 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -1,13 +1,33 @@ message ------- -Display a message to the user. +Log a message. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `General messages`_ + message([<mode>] "message text" ...) + + `Reporting checks`_ + message(<checkState> "message text" ...) + + +General messages +^^^^^^^^^^^^^^^^ .. code-block:: cmake - message([<mode>] "message to display" ...) + message([<mode>] "message text" ...) + +Record the specified message text in the log. If more than one message +string is given, they are concatenated into a single message with no +separator between the strings. -The optional ``<mode>`` keyword determines the type of message: +The optional ``<mode>`` keyword determines the type of message, which +influences the way the message is handled: ``FATAL_ERROR`` CMake Error, stop processing and generation. @@ -59,12 +79,104 @@ The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE`` messages one at a time on a status line and other messages in an interactive pop-up box. The ``--log-level`` command-line option to each of these tools can be used to control which messages will be shown. +To make a log level persist between CMake runs, the +:variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can be set instead. +Note that the command line option takes precedence over the cache variable. -Messages of log levels ``NOTICE`` and below will also have each line preceded +Messages of log levels ``NOTICE`` and below will have each line preceded by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to a single string by concatenating its list items). For ``STATUS`` to ``TRACE`` messages, this indenting content will be inserted after the hyphens. +Messages of log levels ``NOTICE`` and below can also have each line preceded +with context of the form ``[some.context.example]``. The content between the +square brackets is obtained by converting the :variable:`CMAKE_MESSAGE_CONTEXT` +list variable to a dot-separated string. The message context will always +appear before any indenting content but after any automatically added leading +hyphens. By default, message context is not shown, it has to be explicitly +enabled by giving the :manual:`cmake <cmake(1)>` ``--log-context`` +command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` +variable to true. See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for +usage examples. + CMake Warning and Error message text displays using a simple markup language. Non-indented text is formatted in line-wrapped paragraphs delimited by newlines. Indented text is considered pre-formatted. + + +Reporting checks +^^^^^^^^^^^^^^^^ + +A common pattern in CMake output is a message indicating the start of some +sort of check, followed by another message reporting the result of that check. +For example: + +.. code-block:: cmake + + message(STATUS "Looking for someheader.h") + #... do the checks, set checkSuccess with the result + if(checkSuccess) + message(STATUS "Looking for someheader.h - found") + else() + message(STATUS "Looking for someheader.h - not found") + endif() + +This can be more robustly and conveniently expressed using the ``CHECK_...`` +keyword form of the ``message()`` command: + +.. code-block:: cmake + + message(<checkState> "message" ...) + +where ``<checkState>`` must be one of the following: + + ``CHECK_START`` + Record a concise message about the check about to be performed. + + ``CHECK_PASS`` + Record a successful result for a check. + + ``CHECK_FAIL`` + Record an unsuccessful result for a check. + +When recording a check result, the command repeats the message from the most +recently started check for which no result has yet been reported, then some +separator characters and then the message text provided after the +``CHECK_PASS`` or ``CHECK_FAIL`` keyword. Check messages are always reported +at ``STATUS`` log level. + +Checks may be nested and every ``CHECK_START`` should have exactly one +matching ``CHECK_PASS`` or ``CHECK_FAIL``. +The :variable:`CMAKE_MESSAGE_INDENT` variable can also be used to add +indenting to nested checks if desired. For example: + +.. code-block:: cmake + + message(CHECK_START "Finding my things") + list(APPEND CMAKE_MESSAGE_INDENT " ") + unset(missingComponents) + + message(CHECK_START "Finding partA") + # ... do check, assume we find A + message(CHECK_PASS "found") + + message(CHECK_START "Finding partB") + # ... do check, assume we don't find B + list(APPEND missingComponents B) + message(CHECK_FAIL "not found") + + list(POP_BACK CMAKE_MESSAGE_INDENT) + if(missingComponents) + message(CHECK_FAIL "missing components: ${missingComponents}") + else() + message(CHECK_PASS "all components found") + endif() + +Output from the above would appear something like the following:: + + -- Finding my things + -- Finding partA + -- Finding partA - found + -- Finding partB + -- Finding partB - not found + -- Finding my things - missing components: B diff --git a/Help/command/project.rst b/Help/command/project.rst index 3951456..b6093d3 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -102,9 +102,12 @@ options are intended for use as default values in package metadata and documenta Code Injection ^^^^^^^^^^^^^^ -If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variable is set, the file -pointed to by that variable will be included as the first step of the +If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` or +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set, +the files they point to will be included as the first step of the ``project()`` command. +If both are set, then :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` will be +included before :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`. If the :variable:`CMAKE_PROJECT_INCLUDE` or :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files diff --git a/Help/command/string.rst b/Help/command/string.rst index 81a2061..cfcf914 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -11,8 +11,6 @@ Synopsis `Search and Replace`_ string(`FIND`_ <string> <substring> <out-var> [...]) string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...) - - `Regular Expressions`_ string(`REGEX MATCH`_ <match-regex> <out-var> <input>...) string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...) string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...) @@ -38,6 +36,7 @@ Synopsis `Generation`_ string(`ASCII`_ <number>... <out-var>) + string(`HEX`_ <string> <out-var>) string(`CONFIGURE`_ <string> <out-var> [...]) string(`MAKE_C_IDENTIFIER`_ <string> <out-var>) string(`RANDOM`_ [<option>...] <out-var>) @@ -47,6 +46,9 @@ Synopsis Search and Replace ^^^^^^^^^^^^^^^^^^ +Search and Replace With Plain Strings +""""""""""""""""""""""""""""""""""""" + .. _FIND: .. code-block:: cmake @@ -74,8 +76,8 @@ so strings containing multi-byte characters may lead to unexpected results. Replace all occurrences of ``<match_string>`` in the ``<input>`` with ``<replace_string>`` and store the result in the ``<output_variable>``. -Regular Expressions -^^^^^^^^^^^^^^^^^^^ +Search and Replace With Regular Expressions +""""""""""""""""""""""""""""""""""""""""""" .. _`REGEX MATCH`: @@ -87,6 +89,7 @@ Regular Expressions Match the ``<regular_expression>`` once and store the match in the ``<output_variable>``. All ``<input>`` arguments are concatenated before matching. +Regular expressions are specified in the subsection just below. .. _`REGEX MATCHALL`: @@ -353,6 +356,16 @@ Generation Convert all numbers into corresponding ASCII characters. +.. _HEX: + +.. code-block:: cmake + + string(HEX <string> <output_variable>) + +Convert each byte in the input ``<string>`` to its hexadecimal representation +and store the concatenated hex digits in the ``<output_variable>``. Letters in +the output (``a`` through ``f``) are in lowercase. + .. _CONFIGURE: .. code-block:: cmake diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst index 9271cd5..c5401e6 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(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...]) 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/archive.rst b/Help/cpack_gen/archive.rst index d455f4b..e9904ae 100644 --- a/Help/cpack_gen/archive.rst +++ b/Help/cpack_gen/archive.rst @@ -1,8 +1,8 @@ CPack Archive Generator ----------------------- -Archive CPack generator that supports packaging of sources and binaries in -different formats: +CPack generator for packaging files into an archive, which can have +any of the following formats: - 7Z - 7zip - (.7z) - TBZ2 (.tar.bz2) @@ -12,25 +12,42 @@ different formats: - TZST (.tar.zst) - ZIP (.zip) +When this generator is called from ``CPackSourceConfig.cmake`` (or through +the ``package_source`` target), then the generated archive will contain all +files in the project directory, except those specified in +:variable:`CPACK_SOURCE_IGNORE_FILES`. The following is one example of +packaging all source files of a project: + +.. code-block:: cmake + + set(CPACK_SOURCE_GENERATOR "TGZ") + set(CPACK_SOURCE_IGNORE_FILES + \\.git/ + build/ + ".*~$" + ) + set(CPACK_VERBATIM_VARIABLES YES) + include(CPack) + +When this generator is called from ``CPackConfig.cmake`` (or through the +``package`` target), then the generated archive will contain all files +that have been installed via CMake's :command:`install` command (and the +deprecated commands :command:`install_files`, :command:`install_programs`, +and :command:`install_targets`). + Variables specific to CPack Archive generator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. variable:: CPACK_ARCHIVE_FILE_NAME CPACK_ARCHIVE_<component>_FILE_NAME - Package file name without extension which is added automatically depending - on the archive format. - - * Mandatory : YES - * Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].<extension>`` with - spaces replaced by '-' + Package file name without extension. The extension is determined from the + archive format (see list above) and automatically appended to the file name. + The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces + replaced by '-'. .. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL - Enable component packaging for CPackArchive - - * Mandatory : NO - * Default : OFF - - If enabled (ON) multiple packages are generated. By default a single package - containing files of all components is generated. + Enable component packaging. If enabled (ON), then the archive generator + creates multiple packages. The default is OFF, which means that a single + package containing files of all components is generated. diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst index 1e37889..cede0f2 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 ``<language>.menu.txt`` and - ``<language>.license.txt`` file for every language defined in - ``CPACK_DMG_SLA_LANGUAGES``. If both this variable and + ``<language>.license.txt`` or ``<language>.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 + ``<language>.license.txt`` and ``<language>.license.rtf`` exist, the ``.txt`` + file will be used. .. variable:: CPACK_DMG_SLA_LANGUAGES @@ -81,6 +83,13 @@ on macOS: ``<language>.menu.txt`` and ``<language>.license.txt`` in the directory specified by the :variable:`CPACK_DMG_SLA_DIR` variable. +.. variable:: CPACK_DMG_<component>_FILE_NAME + + File name when packaging ``<component>`` as its own DMG + (``CPACK_COMPONENTS_GROUPING`` set to IGNORE). + + - Default: ``CPACK_PACKAGE_FILE_NAME-<component>`` + .. 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 feccd3d..d7c71b4 100644 --- a/Help/cpack_gen/ifw.rst +++ b/Help/cpack_gen/ifw.rst @@ -1,51 +1,28 @@ CPack IFW Generator ------------------- -See :module:`CPackIFW` for details on the CPackIFW module. +Configure and run the Qt Installer Framework to generate a Qt installer. -.. _QtIFW: http://doc.qt.io/qtinstallerframework/index.html +.. only:: html + .. contents:: Overview ^^^^^^^^ -CPack ``IFW`` generator helps you to create online and offline -binary cross-platform installers with a graphical user interface. +This :manual:`cpack generator <cpack-generators(7)>` generates +configuration and meta information for the `Qt Installer Framework +<http://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW), +and runs QtIFW tools to generate a Qt installer. -CPack IFW generator prepares project installation and generates configuration -and meta information for QtIFW_ tools. +QtIFW provides tools and utilities to create installers for +the platforms supported by `Qt <https://www.qt.io>`_: Linux, +Microsoft Windows, and macOS. -The QtIFW_ provides a set of tools and utilities to create -installers for the supported desktop Qt platforms: Linux, Microsoft Windows, -and macOS. - -You should also install QtIFW_ to use CPack ``IFW`` generator. - -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, -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. - - 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 - suite. - -.. note:: - The specified path should not contain "bin" at the end - (for example: "D:\\DevTools\\QtIFW2.0.5"). - -The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides -the value of the :variable:`QTIFWDIR` variable. +To make use of this generator, QtIFW needs to be installed. +The :module:`CPackIFW` module looks for the location of the +QtIFW command-line utilities, and defines several commands to +control the behavior of this generator. Internationalization ^^^^^^^^^^^^^^^^^^^^ @@ -53,7 +30,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. @@ -162,6 +139,8 @@ Package Default target directory for installation. By default used "@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`" + (variables embedded in '@' are expanded by the + `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_). You can use predefined variables. @@ -185,7 +164,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 +176,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,38 +245,60 @@ 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 -""""" +QtIFW Tools +""""""""""" .. variable:: CPACK_IFW_FRAMEWORK_VERSION - The version of used QtIFW_ tools. + The version of used QtIFW tools. -.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE +The following variables provide the locations of the QtIFW +command-line tools as discovered by the module :module:`CPackIFW`. +These variables are cached, and may be configured if needed. - The path to "binarycreator" command line client. +.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE - This variable is cached and may be configured if needed. + The path to ``binarycreator``. .. variable:: CPACK_IFW_REPOGEN_EXECUTABLE - The path to "repogen" command line client. - - This variable is cached and may be configured if needed. + The path to ``repogen``. .. variable:: CPACK_IFW_INSTALLERBASE_EXECUTABLE - The path to "installerbase" installer executable base. - - This variable is cached and may be configured if needed. + The path to ``installerbase``. .. variable:: CPACK_IFW_DEVTOOL_EXECUTABLE - The path to "devtool" command line client. + The path to ``devtool``. + +Hints for Finding QtIFW +""""""""""""""""""""""" + +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. + + 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 + suite. - This variable is cached and may be configured if needed. +.. note:: + The specified path should not contain "bin" at the end + (for example: "D:\\DevTools\\QtIFW2.0.5"). + +The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides +the value of the :variable:`QTIFWDIR` variable. Online installer @@ -335,5 +336,5 @@ Qt Installer Framework Manual: * Promoting Updates: http://doc.qt.io/qtinstallerframework/ifw-updates.html -Download Qt Installer Framework for you platform from Qt site: +Download Qt Installer Framework for your platform from Qt site: http://download.qt.io/official_releases/qt-installer-framework diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index cd2aea6..a310e9f 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 e9464b7..c2a450e 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 d22fcd4..82b79ae 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 44e2273..a1c1a6f 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:<commit-ish>`` 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: <topic>`` 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 cbde6fe..8ec41d2 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[:<commit-ish>]``: 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 + ``:<commit-ish>``. The ``<commit-ish>`` 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: <topic>``: substitute ``<topic>`` 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 0000000..e9e0810 --- /dev/null +++ b/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -0,0 +1,9 @@ +CMAKE_EXPORT_COMPILE_COMMANDS +----------------------------- + +.. include:: ENV_VAR.txt + +The default value for :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` when there +is no explicit configuration given on the first run while creating a new +build tree. On later runs in an existing build tree the value persists in +the cache as :variable:`CMAKE_EXPORT_COMPILE_COMMANDS`. diff --git a/Help/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst new file mode 100644 index 0000000..4f91e9a --- /dev/null +++ b/Help/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_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_<LANG>_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 0000000..11c59f2 --- /dev/null +++ b/Help/generator/Ninja Multi-Config.rst @@ -0,0 +1,120 @@ +Ninja Multi-Config +------------------ + +Generates multiple ``build-<Config>.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-<Config>.ninja`` file will be generated for each of these +configurations (with ``<Config>`` being the configuration name.) These files +are intended to be run with ``ninja -f build-<Config>.ninja``. No +``build.ninja`` file is generated by default (see below for how to generate +it.) + +``cmake --build . --config <Config>`` will always use ``build-<Config>.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-<Config>.ninja`` file contains ``<target>`` targets as well as +``<target>:<Config>`` targets, where ``<Config>`` is the same as the +configuration specified in ``build-<Config>.ninja`` Additionally, if +cross-config mode is enabled, ``build-<Config>.ninja`` may contain +``<target>:<OtherConfig>`` targets, where ``<OtherConfig>`` is a cross-config, +as well as ``<target>: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_NMC_CROSS_CONFIGS` + Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of + configurations available from all ``build-<Config>.ninja`` files. + This variable activates cross-config mode. + Targets from each config specified in this variable can be built from any + ``build-<Config>.ninja`` file. Custom commands will use the configuration + native to ``build-<Config>.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-<Config>.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_NMC_DEFAULT_BUILD_FILE_CONFIG` + Specifies the configuration to use by default in a ``build.ninja`` file. If + this variable is specified, a ``build.ninja`` file is generated which uses + build rules from ``build-<Config>.ninja`` by default. All custom commands are + executed with this configuration. If the variable is not specified, no + ``build.ninja`` file is generated. + + The value of this variable must be one of the items from + :variable:`CMAKE_CONFIGURATION_TYPES`. + +:variable:`CMAKE_NMC_DEFAULT_CONFIGS` + Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of + configurations to build for a target in ``build.ninja`` + if no ``:<Config>`` suffix is specified. If it is set to ``all``, all + configurations from :variable:`CMAKE_NMC_CROSS_CONFIGS` are used. If + it is not specified, it defaults to + :variable:`CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG`. + + For example, if you set + :variable:`CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG` to ``Release``, but + set :variable:`CMAKE_NMC_DEFAULT_CONFIGS` to ``Debug`` or ``all``, + all ``<target>`` aliases in ``build.ninja`` will resolve to + ``<target>:Debug`` or ``<target>:all``, but custom commands will still use + the ``Release`` configuration. + + The value of this variable must be a subset of + :variable:`CMAKE_NMC_CROSS_CONFIGS` or be the same as + :variable:`CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG`. It must not be + specified if :variable:`CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG` or + :variable:`CMAKE_NMC_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_NMC_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 c75d2c4..275055d 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 eca79d9..4d8a3ad 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 dfa84c9..c911625 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 index 403b633..c2583df 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 586d183..a4f44d5 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 <iostream> -#include <sstream> #include <string> #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 a0e4598..0000000 --- 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 0b3f1e4..0000000 --- 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 ae7877b..0000000 --- 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 <iostream> -#include <sstream> -#include <string> - -#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 e6cb8ba..32f5e08 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 index 01d417a..eca79d9 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 "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) # 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 0000000..73efdb1 --- /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 index 17cbabd..17cbabd 100644 --- a/Help/guide/tutorial/MultiPackage/Config.cmake.in +++ b/Help/guide/tutorial/Step12/Config.cmake.in diff --git a/Help/guide/tutorial/MultiPackage/License.txt b/Help/guide/tutorial/Step12/License.txt index c62d00b..c62d00b 100644 --- a/Help/guide/tutorial/MultiPackage/License.txt +++ b/Help/guide/tutorial/Step12/License.txt diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt index a2df2a7..720ee64 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 index ee58556..ee58556 100644 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx +++ b/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 index 0145300..0145300 100644 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx +++ b/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 index 3fb547b..3fb547b 100644 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h +++ b/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 index 5e622be..8153f18 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<int>(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 index e1c42ef..e1c42ef 100644 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h +++ b/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 index 8cd2fc9..7e4d7fa 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 index f97805b..a4f44d5 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 d74d160..a844cbf 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 <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` 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 <cmake-gui(1)>` and +:manual:`ccmake <ccmake(1)>` +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 <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` 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 <ccmake(1)>` executable or the :manual:`cmake-gui <cmake-gui(1)>` +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 <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` 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 <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` 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 <cmake(1)>` 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 <ctest(1)>` 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 <iostream> + +Run the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` 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 <cmath>`. -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 <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` 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 <CPack>` 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 <cpack(1)>` 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 <ctest(1)>` executable will read in this file when it runs. +To create a simple dashboard you can run the :manual:`cmake <cmake(1)>` +executable or the :manual:`cmake-gui <cmake-gui(1)>` 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 <ctest(1)>` 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 <cmake-generator-expressions(7)>` 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 <cmake-generator-expressions(7)>` 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 <cmake-generator-expressions(7)>` 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 <cmake-generator-expressions(7)>` 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 <cmake-generator-expressions(7)>` 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 <cmake(1)>` 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 <cpack(1)>` 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 Binary files differnew file mode 100644 index 0000000..1e9be7e --- /dev/null +++ b/Help/guide/user-interaction/GUI-Add-Entry.png diff --git a/Help/guide/user-interaction/GUI-Choose-Generator.png b/Help/guide/user-interaction/GUI-Choose-Generator.png Binary files differnew file mode 100644 index 0000000..19ad2c0 --- /dev/null +++ b/Help/guide/user-interaction/GUI-Choose-Generator.png diff --git a/Help/guide/user-interaction/GUI-Configure-Dialog.png b/Help/guide/user-interaction/GUI-Configure-Dialog.png Binary files differnew file mode 100644 index 0000000..9839cac --- /dev/null +++ b/Help/guide/user-interaction/GUI-Configure-Dialog.png diff --git a/Help/guide/user-interaction/GUI-Source-Binary.png b/Help/guide/user-interaction/GUI-Source-Binary.png Binary files differnew file mode 100644 index 0000000..e338354 --- /dev/null +++ b/Help/guide/user-interaction/GUI-Source-Binary.png diff --git a/Help/guide/user-interaction/index.rst b/Help/guide/user-interaction/index.rst new file mode 100644 index 0000000..3a1038f --- /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 <Using Dependencies Guide>`, +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 <CMAKE_MAKE_PROGRAM>`, +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 <cmake-generators(7)>` 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 <Using Dependencies Guide>` + :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 <cmake-toolchains(7)>`. + :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 <cmake-generators(7)>`, 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 0000000..6fdcc55 --- /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/<PackageName>``, though +they may be in other locations instead. The +``<PackageName>`` corresponds to use in CMake code with the +:command:`find_package` command such as +``find_package(PackageName REQUIRED)``. + +The ``lib/cmake/<PackageName>`` directory will contain a +file which is either named ``<PackageName>Config.cmake`` +or ``<PackageName>-config.cmake``. This is the entry point +to the package for CMake. A separate optional file named +``<PackageName>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 <User Interaction Guide>` 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 <Setting Build Variables>`. +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 ``<PackageName>_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<PackageName>.cmake`` file does + not indicate the availability of the binaries themselves. +#. CMake does not search the :variable:`CMAKE_PREFIX_PATH` for + ``Find<PackageName>.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<PackageName>.cmake`` files for some + :manual:`third party packages <cmake-modules(7)>` + 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:`<PackageName>_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 cc6cee6..4d9a9c8 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 0000000..be2b163 --- /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 <cmake-commands(7)>`. diff --git a/Help/manual/VS-Choose-Arch.png b/Help/manual/VS-Choose-Arch.png Binary files differnew file mode 100644 index 0000000..816b0f4 --- /dev/null +++ b/Help/manual/VS-Choose-Arch.png diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index a14e322..05dc038 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 <CUDA_STANDARD>` -from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the +CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` and +their associated meta-features (e.g. ``cuda_std_11``) available from the +following :variable:`compiler ids <CMAKE_<LANG>_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 96ceb94..adfc39e 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 04b6ed2..12eecd9 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 75f4bd4..691481b 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -596,7 +596,8 @@ Target-Dependent Queries requirement. ``$<INSTALL_PREFIX>`` Content of the install prefix when the target is exported via - :command:`install(EXPORT)` and empty otherwise. + :command:`install(EXPORT)`, or when evaluated in + :prop_tgt:`INSTALL_NAME_DIR`, and empty otherwise. Output-Related Expressions -------------------------- diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 41f7652..6f88c0a 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 4ca8e3a..b7f0861 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 c60dc40..be64112 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 44ea1a8..c256250 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. </policy/CMP0102> + CMP0101: target_compile_options honors BEFORE keyword in all scopes. </policy/CMP0101> + CMP0100: Let AUTOMOC and AUTOUIC process .hh header files. </policy/CMP0100> + CMP0099: Link properties are transitive over private dependency on static libraries. </policy/CMP0099> + CMP0098: FindFLEX runs flex in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0098> + Policies Introduced by CMake 3.16 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index e704371..fb84378 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 @@ -297,6 +303,8 @@ Properties on Targets /prop_tgt/OBJCXX_STANDARD_REQUIRED /prop_tgt/OSX_ARCHITECTURES_CONFIG /prop_tgt/OSX_ARCHITECTURES + /prop_tgt/OSX_CURRENT_VERSION + /prop_tgt/OSX_COMPATIBILITY_VERSION /prop_tgt/OUTPUT_NAME_CONFIG /prop_tgt/OUTPUT_NAME /prop_tgt/PDB_NAME_CONFIG @@ -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 @@ -380,6 +389,7 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /prop_tgt/XCODE_SCHEME_ARGUMENTS + /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER @@ -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 f233d08..e8badd4 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 53b7f8d..1023a66 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 <CMake Language 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 @@ -235,10 +247,12 @@ Variables that Change Behavior /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /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 @@ -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,8 +372,10 @@ Variables that Control the Build /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_CONFIG_POSTFIX + /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_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_ENABLE_EXPORTS @@ -411,6 +428,9 @@ Variables that Control the Build /variable/CMAKE_MODULE_LINKER_FLAGS_INIT /variable/CMAKE_MSVCIDE_RUN_PATH /variable/CMAKE_MSVC_RUNTIME_LIBRARY + /variable/CMAKE_NMC_CROSS_CONFIGS + /variable/CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG + /variable/CMAKE_NMC_DEFAULT_CONFIGS /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED @@ -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 4ab55a0..44b1f2f 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=<format>`` + Put cmake in trace mode and sets the trace output format. + + ``<format>`` can be one of the following values. + + ``human`` + Prints each trace line in a human-readable format. This is the + default format. + + ``json`` + 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=<file>`` 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] <file>...`` - 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 <dir>...`` - Remove ``<dir>`` directories and their contents. If a directory does + .. deprecated:: 3.17 + + Remove ``<dir>`` directories and their contents. If a directory does not exist it will be silently ignored. If ``<dir>`` is a symlink to a directory, just the symlink will be removed. + Use ``rm`` instead. ``rename <oldname> <newname>`` Rename a file or directory (on one volume). If file with the ``<newname>`` name already exists, then it will be silently replaced. +``rm [-rRf] <file> <dir>...`` + Remove the files ``<file>`` 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 e29ebca..6503f0e 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 <n>`` - Require each test to run ``<n>`` times without failing in order to pass. +``--repeat <mode>:<n>`` + Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times. + The modes are: + + ``until-fail`` + Require each test to run ``<n>`` 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 ``<n>`` 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 ``<n>`` times in order to pass. + Repeats tests only if they timeout. + This is useful in tolerating sporadic timeouts in test cases + on busy machines. - This is useful in finding sporadic failures in test cases. +``--repeat-until-fail <n>`` + Equivalent to ``--repeat until-fail:<n>``. ``--max-width <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 0000000..5f01d68 --- /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 0000000..6d1443b --- /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 0000000..c897e7b --- /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 0000000..b24d013 --- /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 0000000..9941acf --- /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 0000000..9859006 --- /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 0000000..44e37fe --- /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_tgt/AIX_EXPORT_ALL_SYMBOLS.rst b/Help/prop_tgt/AIX_EXPORT_ALL_SYMBOLS.rst new file mode 100644 index 0000000..15ddc0b --- /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 07fbc5a..968b619 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 `<origin>_autogen` target starts a number of threads of which +The custom ``<origin>_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/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index f6dfabd..c18859b 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 69957bf..6eda26c 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 ebd5c49..330849b 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() <FindQt4>` 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 e2ebb3f..3e3059d 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 <target_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 cca3e58..9a98f44 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 d6ade5a..5261aff 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() <FindQt4>` 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 5cf8755..cd24f5e 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 ``<base_name>.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 +``<base_name>.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 3f613b9..425ea1c 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() <FindQt4>` 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 195215e..46aec4f 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 0000000..a6d7050 --- /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 0000000..0782765 --- /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 <cmake-generator-expressions(7)>`. + +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 0000000..fef2e2e --- /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 0000000..8698eb6 --- /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 c100326..b33f4fb 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 2216072..747615a 100644 --- a/Help/prop_tgt/INSTALL_NAME_DIR.rst +++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst @@ -10,3 +10,7 @@ installed targets. This property is initialized by the value of the variable :variable:`CMAKE_INSTALL_NAME_DIR` if it is set when a target is created. + +This property supports :manual:`generator expressions <cmake-generator-expressions(7)>`. +In particular, the ``$<INSTALL_PREFIX>`` generator expression can be used to set the +directory relative to the install-time prefix. diff --git a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst index d8be954..d16a7a1 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 0000000..ece28a4 --- /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/LINK_LIBRARIES_INDIRECTION.txt b/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt index 1fdb6ad..476e4a6 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(<target> ...)` may update this property on ``<target>``. If ``<target>`` was not created in the same - directory as the call then :command:`target_link_libraries` will add a - suffix of the form ``::@<directory-id>`` to each entry, where the - ``::@`` is a separator and the ``<directory-id>`` 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 ``<target>`` was created. Valid directory ids are stripped on export diff --git a/Help/prop_tgt/OSX_COMPATIBILITY_VERSION.rst b/Help/prop_tgt/OSX_COMPATIBILITY_VERSION.rst new file mode 100644 index 0000000..5432b9a7 --- /dev/null +++ b/Help/prop_tgt/OSX_COMPATIBILITY_VERSION.rst @@ -0,0 +1,14 @@ +OSX_COMPATIBILITY_VERSION +------------------------- + +What compatibility version number is this target for OSX. + +For shared libraries on Mach-O systems (e.g. macOS, iOS) +the ``OSX_COMPATIBILITY_VERSION`` property correspond to +``compatibility version`` and :prop_tgt:`OSX_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 <binary>`` +command. If ``OSX_COMPATIBILITY_VERSION`` is not set, the value of +the :prop_tgt:``SOVERSION`` property will be used. diff --git a/Help/prop_tgt/OSX_CURRENT_VERSION.rst b/Help/prop_tgt/OSX_CURRENT_VERSION.rst new file mode 100644 index 0000000..609924d --- /dev/null +++ b/Help/prop_tgt/OSX_CURRENT_VERSION.rst @@ -0,0 +1,13 @@ +OSX_CURRENT_VERSION +------------------- + +What current version number is this target for OSX. + +For shared libraries on Mach-O systems (e.g. macOS, iOS) +the :prop_tgt:`OSX_COMPATIBILITY_VERSION` property correspond to +``compatibility version`` and ``OSX_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 <binary>`` +command. If ``OSX_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 b07c17c..1a66c8f 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 <binary>`` command. +the ``SOVERSION`` property is a fallback to +:prop_tgt:`OSX_COMPATIBILITY_VERSION` property which corresponds to +*compatiblity version* and :prop_tgt:`VERSION` is a fallback to +:prop_tgt:`OSX_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 <binary>`` command. diff --git a/Help/prop_tgt/VERSION.rst b/Help/prop_tgt/VERSION.rst index ff3b303..a24b613 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:`OSX_CURRENT_VERSION` +property which corresponds to *current version* and :prop_tgt:`SOVERSION` +is a fallback to :prop_tgt:`OSX_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 <binary>`` 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 0000000..1bc361c --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst @@ -0,0 +1,6 @@ +VS_DOTNET_DOCUMENTATION_FILE +---------------------------- + +Visual Studio managed project .NET documentation output + +Sets the target XML documentation file output. diff --git a/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst index 9f5a313..6cb8f86 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 0000000..7ffa74b --- /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.17.rst b/Help/release/3.17.rst new file mode 100644 index 0000000..30e6cc3 --- /dev/null +++ b/Help/release/3.17.rst @@ -0,0 +1,316 @@ +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 <cmake-compile-features(7)>` 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` learned a new option ``ZIP_LISTS`` 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 <Script Processing Mode>`. + +* The :command:`message` command learned to output context provided in + the :variable:`CMAKE_MESSAGE_CONTEXT` variable for log levels + ``NOTICE`` and below. Enable this output with the new ``--log-context`` + command-line option or :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable. + +* The :command:`message` command gained new keywords ``CHECK_START``, + ``CHECK_PASS`` and ``CHECK_FAIL``. + +* :command:`target_compile_options` command now honors the ``BEFORE`` + keyword more consistently. See policy :policy:`CMP0101`. + +Variables +--------- + +* A :variable:`CMAKE_CTEST_ARGUMENTS` variable was added to specify a list + of command-line arguments passed to CTest when running through the + ``test`` (or ``RUN_TESTS``) target of the generated build system. + +* The following variables are now defined inside a :command:`function`: + + - :variable:`CMAKE_CURRENT_FUNCTION` + - :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR` + - :variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE` + - :variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` + +* The :variable:`CMAKE_CUDA_RUNTIME_LIBRARY` variable and + :prop_tgt:`CUDA_RUNTIME_LIBRARY` target property were introduced to + select the CUDA runtime library used when linking targets that + use CUDA. + +* The :variable:`CMAKE_FIND_DEBUG_MODE` variable was introduced to + print extra find call information during the cmake run to standard + error. Output is designed for human consumption and not for parsing. + +* The :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable now takes its + initial value from the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment + variable if no explicit configuration is given. + +* The :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable, if not set + explicitly, now takes its initial value from the + :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` environment variable. + +* The :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can now be used + to persist a log level between CMake runs, unlike the ``--log-level`` + command line option which only applies to that particular run. + +* The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable and + :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property were added to + tell the :generator:`Xcode` generator to set the value of the + ``Custom Working Directory`` schema option. + +Properties +---------- + +* The :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property and associated + :variable:`CMAKE_AIX_EXPORT_ALL_SYMBOLS` variable were created to + optionally explicitly disbale automatic export of symbols from shared + libraries on AIX. + +* The :prop_tgt:`DEPRECATION` target property was added to mark + a target as deprecated. If a linked target is marked as + deprecated, a warning with the deprecation message is issued + at generate time. + +* The :prop_tgt:`INSTALL_NAME_DIR` target property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + In particular, the ``$<INSTALL_PREFIX>`` generator expression can + be used to set the directory relative to the install-time prefix. + +* Target properties :prop_tgt:`OSX_COMPATIBILITY_VERSION` and + :prop_tgt:`OSX_CURRENT_VERSION` were added to set the + ``compatibility_version`` and ``curent_version`` respectively + on macOS. For backwards compatibility, if these properties + are not set, :prop_tgt:`SOVERSION` and :prop_tgt:`VERSION` + are used respectively as fallbacks. + +* The :prop_tgt:`VS_DOTNET_DOCUMENTATION_FILE` target property was added + to tell :ref:`Visual Studio Generators` to generate a ``DocumentationFile`` + reference in ``.csproj`` files. + +Modules +------- + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + command gained a ``GIT_SUBMODULES_RECURSE`` option to specify whether + Git submodules should be updated recursively. The default is on to + preserve existing behavior. + +* The :module:`FindCUDAToolkit` module was added to find the + CUDA Toolkit without enabling CUDA as a language. + +* The :module:`FindCURL` module learned to find CURL using + the ``CURLConfig.cmake`` package configuration file generated by + CURL's cmake buildsystem. It also gained a new ``CURL_NO_CURL_CMAKE`` + option to disable this behavior. + +* The :module:`FindFLEX` module's ``FLEX_TARGET`` command now runs ``flex`` + with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory. + See policy :policy:`CMP0098`. + +* The :module:`FindLibArchive` module now provides an imported target + for libarchive. + +* The :module:`FindPython` module has learned to find Python components + in active virtual environments managed by ``conda``. + +* The :module:`FindPython3` and :module:`FindPython` modules gained, + respectively, variable ``Python3_SOABI`` and ``Python_SOABI`` giving + the standard extension suffix for modules. + +* The :module:`FindLibXml2` module now provides an imported target for the + ``xmllint`` executable + +Autogen +------- + +* :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` learned to process headers + with a ``.hh`` extension. See policy :policy:`CMP0100`. + +CTest +----- + +* The :variable:`CTEST_CONFIGURATION_TYPE` variable is now set from the + command line when :manual:`ctest(1)` is invoked with ``-C <cfg>``. + +* The :manual:`ctest(1)` gained support for Dr. Memory to run + memcheck runs. + +* The :manual:`ctest(1)` tool gained a ``--no-tests=<[error|ignore]>`` option + to explicitly set and unify the behavior between direct invocation and + script mode if no tests were found. + +* The :manual:`ctest(1)` tool gained a ``--repeat <mode>:<n>`` option + to specify conditions in which to repeat tests. This generalizes + the existing ``--repeat-until-fail <n>`` option to add modes for + ``until-pass`` and ``after-timeout``. + +* The :command:`ctest_test` command gained a ``REPEAT <mode>:<n>`` option + to specify conditions in which to repeat tests. + +CPack +----- + +* The :cpack_gen:`CPack DragNDrop Generator` learned to use + the :variable:`CPACK_DMG_<component>_FILE_NAME` variable + to set a custom filename when packaging components into + their own DMGs. + +* The :cpack_gen:`CPack DragNDrop Generator` learned to handle + RTF formatted license files. When :variable:`CPACK_DMG_SLA_DIR` + variable is set, ``<language>.license.rtf`` is considered, but + only as a fallback when the plaintext (``.txt``) file is not found + in order to maintain backwards compatibility. + +* The :cpack_gen:`CPack NSIS Generator` gained a new variable + :variable:`CPACK_NSIS_MUI_HEADERIMAGE` to set the header image. + To not break existing setups, it still defaults to + :variable:`CPACK_PACKAGE_ICON` if the new variable is not set. + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_UNINSTALL_NAME`. + This can be used to specify the name of the Uninstall program. + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_WELCOME_TITLE` and + :variable:`CPACK_NSIS_WELCOME_TITLE_3LINES`. + These can be used to specify the welcome page title and display it in 3 lines. + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_FINISH_TITLE` and + :variable:`CPACK_NSIS_FINISH_TITLE_3LINES`. + These can be used to specify the finish page title and display it in 3 lines. + +* The :cpack_gen:`CPack productbuild Generator` gained option + :variable:`CPACK_PRODUCTBUILD_BACKGROUND` to specify a background image + for the macOS installer. + +Other +----- + +* :manual:`ccmake(1)` now displays cache values using colors + based on the entry type if the terminal supports color. + +* :manual:`ccmake(1)` now displays messages and a progress bar during + configure and generate. It will keep the output displayed if any + errors or warnings occurred. + +Deprecated and Removed Features +=============================== + +* An explicit deprecation diagnostic was added for policy ``CMP0068`` + and policy ``CMP0069`` (``CMP0067`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. + +* The :cpack_gen:`CPack PackageMaker Generator` generator has been + deprecated because Xcode no longer distributes the PackageMaker tools. + The undocumented ``OSXX11`` generator has also been deprecated. + +* The :manual:`cmake(1)` command-line ``-E remove`` and ``-E remove_directory`` + tools are deprecated in favor of the new ``-E rm`` tool. The older tools + always returned 0 if a named path did not exist even without the force + option and cannot be fixed without breaking compatibility, and so have + been superseded. + +Other Changes +============= + +* The :manual:`file API <cmake-file-api(7)>` index file now emits a + ``multiConfig`` flag specifying whether or not the generator supports + multiple output configurations. + +* 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 on static libraries. + See policy :policy:`CMP0099`. + +* When using MinGW tools, the :command:`find_library` command no longer + finds ``.dll`` files by default. Instead it expects ``.dll.a`` import + libraries to be available. + +* The :generator:`MinGW Makefiles` generator no longer issues an error if + ``sh.exe`` is present in the environment's ``PATH``. + +* The :generator:`Ninja` generator now prefers the first ninja build + tool to appear in the ``PATH`` no matter whether it is called + ``ninja-build``, ``ninja``, or ``samu``. Previously the first + of those names to appear anywhere in the ``PATH`` would be preferred. + +* With SDCC the ``sdar`` tool is now preferred over ``sdcclib`` as librarian. + The latter was deprecated by SDCC 3.2.0 and removed in SDCC 3.8.6. + +* With SDCC the default flags no longer include any target-specific flags. + Previously the default flags were hard-coded for 8051. + +* The :variable:`CMAKE_VS_GLOBALS` variable value now applies during + compiler identification and in targets created by the + :command:`add_custom_target` command. + +* The :generator:`Xcode` generator no longer hard-codes ``-Wmost``, + ``-Wno-four-char-constants``, and ``-Wno-unknown-pragmas`` warning flags. diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/cmake-gui-env-platform-defaults.rst b/Help/release/dev/cmake-gui-env-platform-defaults.rst new file mode 100644 index 0000000..0960ef1 --- /dev/null +++ b/Help/release/dev/cmake-gui-env-platform-defaults.rst @@ -0,0 +1,8 @@ +cmake-gui-env-platform-defaults +------------------------------- + +* :manual:`cmake-gui(1)` now populates its generator selection + widget default value from the :envvar:`CMAKE_GENERATOR` environment + variable. Additionally, environment variables + :envvar:`CMAKE_GENERATOR_PLATFORM` and :envvar:`CMAKE_GENERATOR_TOOLSET` + are used to populate their respective widget defaults. diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000..cffd206 --- /dev/null +++ b/Help/release/dev/deprecate-policy-old.rst @@ -0,0 +1,8 @@ +deprecate-policy-old +-------------------- + +* An explicit deprecation diagnostic was added for policy ``CMP0070`` + and policy ``CMP0071`` (``CMP0069`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. diff --git a/Help/release/dev/string-hex.rst b/Help/release/dev/string-hex.rst new file mode 100644 index 0000000..f220aca --- /dev/null +++ b/Help/release/dev/string-hex.rst @@ -0,0 +1,5 @@ +string-hex +---------- + +* The :command:`string` command learned a new ``HEX`` sub-command, which + converts strings into their hexadecimal representation. diff --git a/Help/release/index.rst b/Help/release/index.rst index 0cc3f97..22b1a09 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,12 +7,15 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== .. toctree:: :maxdepth: 1 + 3.17 <3.17> 3.16 <3.16> 3.15 <3.15> 3.14 <3.14> diff --git a/Help/variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS.rst b/Help/variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS.rst new file mode 100644 index 0000000..c64dd48 --- /dev/null +++ b/Help/variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS.rst @@ -0,0 +1,6 @@ +CMAKE_AIX_EXPORT_ALL_SYMBOLS +---------------------------- + +Default value for :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_CTEST_ARGUMENTS.rst b/Help/variable/CMAKE_CTEST_ARGUMENTS.rst new file mode 100644 index 0000000..0940b46 --- /dev/null +++ b/Help/variable/CMAKE_CTEST_ARGUMENTS.rst @@ -0,0 +1,6 @@ +CMAKE_CTEST_ARGUMENTS +--------------------- + +Set this to a :ref:`semicolon-separated list <CMake Language Lists>` of +command-line arguments to pass to :manual:`ctest(1)` when running tests +through the ``test`` (or ``RUN_TESTS``) target of the generated build system. diff --git a/Help/variable/CMAKE_CUDA_COMPILE_FEATURES.rst b/Help/variable/CMAKE_CUDA_COMPILE_FEATURES.rst new file mode 100644 index 0000000..2cd2650 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_COMPILE_FEATURES.rst @@ -0,0 +1,11 @@ +CMAKE_CUDA_COMPILE_FEATURES +--------------------------- + +List of features known to the CUDA compiler + +These features are known to be available for use with the CUDA compiler. This +list is a subset of the features listed in the +:prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES` global property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_RUNTIME_LIBRARY.rst b/Help/variable/CMAKE_CUDA_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..ea1c1b8 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_RUNTIME_LIBRARY.rst @@ -0,0 +1,24 @@ +CMAKE_CUDA_RUNTIME_LIBRARY +-------------------------- + +Select the CUDA runtime library for use by compilers targeting the MSVC ABI. +This variable is used to initialize the :prop_tgt:`CUDA_RUNTIME_LIBRARY` +property on all targets as they are created. + +The allowed case insensitive values are: + +.. include:: ../prop_tgt/CUDA_RUNTIME_LIBRARY-VALUES.txt + +Contents of ``CMAKE_CUDA_RUNTIME_LIBRARY`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +If this variable is not set then the :prop_tgt:`CUDA_RUNTIME_LIBRARY` target +property will not be set automatically. If that 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/variable/CMAKE_CURRENT_FUNCTION.rst b/Help/variable/CMAKE_CURRENT_FUNCTION.rst new file mode 100644 index 0000000..aa2936c --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION.rst @@ -0,0 +1,6 @@ +CMAKE_CURRENT_FUNCTION +---------------------- + +When executing code inside a :command:`function`, this variable +contains the name of the current function. It can be used for +diagnostic or debug messages. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst new file mode 100644 index 0000000..0119381 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst @@ -0,0 +1,33 @@ +CMAKE_CURRENT_FUNCTION_LIST_DIR +------------------------------- + +When executing code inside a :command:`function`, this variable +contains the full directory of the listfile defining the current function. + +It is quite common practice in CMake that modules use some additional files +(e.g., templates to render). And the code typically did the following: + +.. code-block:: cmake + :caption: Bad + + set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}") + + function(foo) + configure_file( + "${_THIS_MODULE_BASE_DIR}/some.template.in" + some.output + ) + endfunction() + +Using this variable inside a function eliminates the neccessity of the +additional one with "global" scope: + +.. code-block:: cmake + :caption: Good + + function(foo) + configure_file( + "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in" + some.output + ) + endfunction() diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst new file mode 100644 index 0000000..d2c846a --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst @@ -0,0 +1,5 @@ +CMAKE_CURRENT_FUNCTION_LIST_FILE +-------------------------------- + +When executing code inside a :command:`function`, this variable +contains the full path to the listfile declaring a current function. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst new file mode 100644 index 0000000..5a7cd13 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst @@ -0,0 +1,5 @@ +CMAKE_CURRENT_FUNCTION_LIST_LINE +-------------------------------- + +When executing code inside a :command:`function`, this variable +contains the line number in the listfile where a current function has defined. diff --git a/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK.rst b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK.rst new file mode 100644 index 0000000..8edcd1e --- /dev/null +++ b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK.rst @@ -0,0 +1,16 @@ +CMAKE_DOTNET_TARGET_FRAMEWORK +----------------------------- + +Default value for :prop_tgt:`DOTNET_TARGET_FRAMEWORK` property of +targets. + +This variable is used to initialize the +:prop_tgt:`DOTNET_TARGET_FRAMEWORK` property on all targets. See that +target property for additional information. + +Setting ``CMAKE_DOTNET_TARGET_FRAMEWORK`` may be necessary +when working with ``C#`` and newer .NET framework versions to +avoid referencing errors with the ``ALL_BUILD`` CMake target. + +This variable is only evaluated for :ref:`Visual Studio Generators` +VS 2010 and above. diff --git a/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst index 124fefe..c2eef9e 100644 --- a/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst +++ b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -6,7 +6,11 @@ property of targets. This variable is used to initialize the :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` property on all -targets. See that target property for additional information. +targets. See that target property for additional information. When set, +:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK` takes precednece over this +variable. See that variable or the associated target property +:prop_tgt:`DOTNET_TARGET_FRAMEWORK` for additional information. + Setting ``CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION`` may be necessary when working with ``C#`` and newer .NET framework versions to diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst index 4548abc..6d2450b 100644 --- a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst +++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -25,6 +25,9 @@ form. The format of the JSON file looks like: } ] +This is initialized by the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment +variable. + .. note:: This option is implemented only by :ref:`Makefile Generators` and the :generator:`Ninja`. It is ignored on other generators. diff --git a/Help/variable/CMAKE_FIND_DEBUG_MODE.rst b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst new file mode 100644 index 0000000..33ffdd6 --- /dev/null +++ b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst @@ -0,0 +1,22 @@ +CMAKE_FIND_DEBUG_MODE +--------------------- + +Print extra find call information for the following commands to standard +error: +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +Output is designed for human consumption and not for parsing. +Enabling this variable is equivalent to using :manual:`cmake <cmake(1)>` ``--debug-find`` +with the added ability to enable debugging for a subset of find calls. + +.. code-block:: cmake + + set(CMAKE_FIND_DEBUG_MODE TRUE) + find_program(...) + set(CMAKE_FIND_DEBUG_MODE FALSE) + +Default is unset. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 222824f..53ad2f3 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -58,3 +58,8 @@ Supported pairs are: Specify the toolset version to use. Supported by VS 2017 and above with the specified toolset installed. See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_VERSION` variable. + +``VCTargetsPath=<path>`` + Specify an alternative ``VCTargetsPath`` value for Visual Studio + project files. This allows use of VS platform extension configuration + files (``.props`` and ``.targets``) that are not installed with VS. diff --git a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst index e82867d..8587742 100644 --- a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst +++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst @@ -3,7 +3,7 @@ CMAKE_GLOBAL_AUTOGEN_TARGET Switch to enable generation of a global ``autogen`` target. -When :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` is enabled, a custom target +When :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is enabled, a custom target ``autogen`` is generated. This target depends on all :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project. By building the global ``autogen`` target, all :prop_tgt:`AUTOMOC` and diff --git a/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst b/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst index ba8a850..5f08728 100644 --- a/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst +++ b/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst @@ -3,6 +3,13 @@ CMAKE_HOST_SYSTEM_PROCESSOR The name of the CPU CMake is running on. -On systems that support ``uname``, this variable is set to the output of -``uname -p``. On Windows it is set to the value of the environment variable -``PROCESSOR_ARCHITECTURE``. +On Windows, this variable is set to the value of the environment variable +``PROCESSOR_ARCHITECTURE``. On systems that support ``uname``, this variable is +set to the output of: + +- ``uname -m`` on GNU, Linux, Cygwin, Darwin, Android, or +- ``arch`` on OpenBSD, or +- on other systems, + + * ``uname -p`` if its exit code is nonzero, or + * ``uname -m`` otherwise. diff --git a/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst b/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst index 78148d5..a99c108 100644 --- a/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst +++ b/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst @@ -3,7 +3,11 @@ CMAKE_INSTALL_RPATH_USE_LINK_PATH Add paths to linker search and installed rpath. -``CMAKE_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 is used to initialize the -target property :prop_tgt:`INSTALL_RPATH_USE_LINK_PATH` for all targets. +``CMAKE_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 varibale is used to initialize the target property +:prop_tgt:`INSTALL_RPATH_USE_LINK_PATH` for all targets. diff --git a/Help/variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER.rst b/Help/variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER.rst new file mode 100644 index 0000000..f9467b3 --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER.rst @@ -0,0 +1,6 @@ +CMAKE_JOB_POOL_PRECOMPILE_HEADER +-------------------------------- + +This variable is used to initialize the :prop_tgt:`JOB_POOL_PRECOMPILE_HEADER` +property on all the targets. See :prop_tgt:`JOB_POOL_PRECOMPILE_HEADER` +for additional information. diff --git a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst index 6b7e35a..c76e2d0 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -5,3 +5,6 @@ Default value for :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property. This variable is used to initialize the property on each target as it is created. This is done only when ``<LANG>`` is ``C``, ``CXX``, ``Fortran``, ``OBJC``, ``OBJCXX``, or ``CUDA``. + +This variable is initialized to the :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` +environment variable if it is set. diff --git a/Help/variable/CMAKE_MESSAGE_CONTEXT.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst new file mode 100644 index 0000000..6b4ca40 --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst @@ -0,0 +1,62 @@ +CMAKE_MESSAGE_CONTEXT +--------------------- + +When enabled by the :manual:`cmake <cmake(1)>` ``--log-context`` command line +option or the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable, the +:command:`message` command converts the ``CMAKE_MESSAGE_CONTEXT`` list into a +dot-separated string surrounded by square brackets and prepends it to each line +for messages of log levels ``NOTICE`` and below. + +For logging contexts to work effectively, projects should generally +``APPEND`` and ``POP_BACK`` an item to the current value of +``CMAKE_MESSAGE_CONTEXT`` rather than replace it. +Projects should not assume the message context at the top of the source tree +is empty, as there are scenarios where the context might have already been set +(e.g. hierarchical projects). + +.. warning:: + + Valid context names are restricted to anything that could be used + as a CMake variable name. All names that begin with an underscore + or the string ``cmake_`` are also reserved for use by CMake and + should not be used by projects. + +Example: + +.. code-block:: cmake + + function(bar) + list(APPEND CMAKE_MESSAGE_CONTEXT "bar") + message(VERBOSE "bar VERBOSE message") + endfunction() + + function(baz) + list(APPEND CMAKE_MESSAGE_CONTEXT "baz") + message(DEBUG "baz DEBUG message") + endfunction() + + function(foo) + list(APPEND CMAKE_MESSAGE_CONTEXT "foo") + bar() + message(TRACE "foo TRACE message") + baz() + endfunction() + + list(APPEND CMAKE_MESSAGE_CONTEXT "top") + + message(VERBOSE "Before `foo`") + foo() + message(VERBOSE "After `foo`") + + list(POP_BACK CMAKE_MESSAGE_CONTEXT) + + +Which results in the following output: + +.. code-block:: none + + -- [top] Before `foo` + -- [top.foo.bar] bar VERBOSE message + -- [top.foo] foo TRACE message + -- [top.foo.baz] baz DEBUG message + -- [top] After `foo` diff --git a/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst new file mode 100644 index 0000000..7ec218e --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst @@ -0,0 +1,15 @@ +CMAKE_MESSAGE_CONTEXT_SHOW +-------------------------- + +Setting this variable to true enables showing a context with each line +logged by the :command:`message` command (see :variable:`CMAKE_MESSAGE_CONTEXT` +for how the context itself is specified). + +This variable is an alternative to providing the ``--log-context`` option +on the :manual:`cmake <cmake(1)>` command line. Whereas the command line +option will apply only to that one CMake run, setting +``CMAKE_MESSAGE_CONTEXT_SHOW`` to true as a cache variable will ensure that +subsequent CMake runs will continue to show the message context. + +Projects should not set ``CMAKE_MESSAGE_CONTEXT_SHOW``. It is intended for +users so that they may control whether or not to include context with messages. diff --git a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst new file mode 100644 index 0000000..1d4cfe6 --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst @@ -0,0 +1,15 @@ +CMAKE_MESSAGE_LOG_LEVEL +----------------------- + +When set, this variable specifies the logging level used by the +:command:`message` command. Valid values are the same as those for the +``--log-level`` command line option of the :manual:`cmake(1)` program. +If this variable is set and the ``--log-level`` command line option is +given, the command line option takes precedence. + +The main advantage to using this variable is to make a log level persist +between CMake runs. Setting it as a cache variable will ensure that +subsequent CMake runs will continue to use the chosen log level. + +Projects should not set this variable, it is intended for users so that +they may control the log level according to their own needs. diff --git a/Help/variable/CMAKE_NMC_CROSS_CONFIGS.rst b/Help/variable/CMAKE_NMC_CROSS_CONFIGS.rst new file mode 100644 index 0000000..6eb6494 --- /dev/null +++ b/Help/variable/CMAKE_NMC_CROSS_CONFIGS.rst @@ -0,0 +1,7 @@ +CMAKE_NMC_CROSS_CONFIGS +------------------------------- + +Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of +configurations available from all ``build-<Config>.ninja`` files in the +:generator:`Ninja Multi-Config` generator. See the generator's +documentation for more details. diff --git a/Help/variable/CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG.rst b/Help/variable/CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG.rst new file mode 100644 index 0000000..c0eab56 --- /dev/null +++ b/Help/variable/CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG.rst @@ -0,0 +1,6 @@ +CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG +------------------------------------------- + +Specifies the configuration to use by default in a ``build.ninja`` file in the +:generator:`Ninja Multi-Config` generator. See the generator's documentation +for more details. diff --git a/Help/variable/CMAKE_NMC_DEFAULT_CONFIGS.rst b/Help/variable/CMAKE_NMC_DEFAULT_CONFIGS.rst new file mode 100644 index 0000000..e2bb017 --- /dev/null +++ b/Help/variable/CMAKE_NMC_DEFAULT_CONFIGS.rst @@ -0,0 +1,7 @@ +CMAKE_NMC_DEFAULT_CONFIGS +--------------------------------- + +Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of configurations +to build for a target in ``build.ninja`` if no ``:<Config>`` suffix is specified in +the :generator:`Ninja Multi-Config` generator. +See the generator's documentation for more details. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index fc52e7b..de71d0e 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -23,6 +23,8 @@ warn by default: policy :policy:`CMP0082`. * ``CMAKE_POLICY_WARNING_CMP0089`` controls the warning for policy :policy:`CMP0089`. +* ``CMAKE_POLICY_WARNING_CMP0102`` controls the warning for + policy :policy:`CMP0102`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE.rst index 965c94e..5835264 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE.rst @@ -5,5 +5,6 @@ A CMake language file or module to be included as the last step of all :command:`project` command calls. This is intended for injecting custom code into project builds without modifying their source. -See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` and +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst index 70b15e6..280c14a 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst @@ -5,5 +5,6 @@ A CMake language file or module to be included as the first step of all :command:`project` command calls. This is intended for injecting custom code into project builds without modifying their source. -See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` and +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and :variable:`CMAKE_PROJECT_INCLUDE` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst index 3485c38..74247f1 100644 --- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -6,5 +6,6 @@ A CMake language file or module to be included as the last step of any name. This is intended for injecting custom code into project builds without modifying their source. -See also the :variable:`CMAKE_PROJECT_INCLUDE` and +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_INCLUDE` and :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst new file mode 100644 index 0000000..db1432d --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE +------------------------------------------- + +A CMake language file or module to be included as the first step of any +:command:`project` command calls that specify ``<PROJECT-NAME>`` as the project +name. This is intended for injecting custom code into project builds without +modifying their source. + +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_INCLUDE` and +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst b/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst index 2ba8fe2..2eea424 100644 --- a/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst +++ b/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst @@ -1,8 +1,18 @@ CMAKE_VS_WINRT_BY_DEFAULT ------------------------- -Tell :ref:`Visual Studio Generators` for VS 2010 and above that the -target platform compiles as WinRT by default (compiles with ``/ZW``). +Inform :ref:`Visual Studio Generators` for VS 2010 and above that the +target platform enables WinRT compilation by default and it needs to +be explicitly disabled if ``/ZW`` or :prop_tgt:`VS_WINRT_COMPONENT` is +omitted (as opposed to enabling it when either of those options is +present) + +This makes cmake configuration consistent in terms of WinRT among +platforms - if you did not enable the WinRT compilation explicitly, it +will be disabled (by either not enabling it or explicitly disabling it) + +Note: WinRT compilation is always explicitly disabled for C language +source files, even if it is expliclty enabled for a project This variable is meant to be set by a :variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` for such platforms. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst new file mode 100644 index 0000000..4832659 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_ENVIRONMENT +------------------------------ + +Specify environment variables that should be added to the Arguments +section of the generated Xcode scheme. + +If set to a list of environment variables and values of the form +``MYVAR=value`` those environment variables will be added to the +scheme. + +This variable initializes the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst b/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst new file mode 100644 index 0000000..cc690f7 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_WORKING_DIRECTORY +------------------------------------ + +Specify the ``Working Directory`` a of the `Run` and `Profile` +action in the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CTEST_CONFIGURATION_TYPE.rst b/Help/variable/CTEST_CONFIGURATION_TYPE.rst index c905480..9e277fa 100644 --- a/Help/variable/CTEST_CONFIGURATION_TYPE.rst +++ b/Help/variable/CTEST_CONFIGURATION_TYPE.rst @@ -3,3 +3,6 @@ CTEST_CONFIGURATION_TYPE Specify the CTest ``DefaultCTestConfigurationType`` setting in a :manual:`ctest(1)` dashboard client script. + +If the configuration type is set via ``-C <cfg>`` from the command line +then this variable is populated accordingly. diff --git a/Help/variable/CTEST_MEMORYCHECK_TYPE.rst b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst index b8b4c30..4e7d5c0 100644 --- a/Help/variable/CTEST_MEMORYCHECK_TYPE.rst +++ b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst @@ -3,6 +3,6 @@ CTEST_MEMORYCHECK_TYPE Specify the CTest ``MemoryCheckType`` setting in a :manual:`ctest(1)` dashboard client script. -Valid values are ``Valgrind``, ``Purify``, ``BoundsChecker``, and +Valid values are ``Valgrind``, ``Purify``, ``BoundsChecker``, ``DrMemory`` and ``ThreadSanitizer``, ``AddressSanitizer``, ``LeakSanitizer``, ``MemorySanitizer``, and ``UndefinedBehaviorSanitizer``. |
