diff options
Diffstat (limited to 'Help/manual')
| -rw-r--r-- | Help/manual/cmake-commands.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-env-variables.7.rst | 15 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 194 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 11 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 9 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 4 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 23 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 11 |
8 files changed, 234 insertions, 34 deletions
diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 59ba897..87743b4 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -16,6 +16,7 @@ These commands are always available. :maxdepth: 1 /command/break + /command/cmake_command /command/cmake_host_system_information /command/cmake_minimum_required /command/cmake_parse_arguments diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index f72e414..ce1e360 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -14,6 +14,13 @@ For general information on environment variables, see the :ref:`Environment Variables <CMake Language Environment Variables>` section in the cmake-language manual. +Environment Variables that Change Behavior +========================================== + +.. toctree:: + :maxdepth: 1 + + /envvar/CMAKE_PREFIX_PATH Environment Variables that Control the Build ============================================ @@ -75,3 +82,11 @@ Environment Variables for CTest /envvar/CTEST_PROGRESS_OUTPUT /envvar/CTEST_USE_LAUNCHERS_DEFAULT /envvar/DASHBOARD_TEST_FROM_CTEST + +Environment Variables for the CMake curses interface +==================================================== + +.. toctree:: + :maxdepth: 1 + + /envvar/CCMAKE_COLORS diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 691481b..9e411a4 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -259,6 +259,121 @@ Variable Queries add_executable(myapp main.cpp) target_link_libraries(myapp myapp_c myapp_cxx) +.. _`Boolean LINK_LANGUAGE Generator Expression`: + +``$<LINK_LANG_AND_ID:language,compiler_ids>`` + ``1`` when the language used for link step matches ``language`` and the + CMake's compiler id of the language linker matches any one of the entries + in ``compiler_ids``, otherwise ``0``. This expression is a short form for the + combination of ``$<LINK_LANGUAGE:language>`` and + ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify + link libraries, link options, link directories and link dependencies of a + particular language and linker combination in a target. For example: + + .. code-block:: cmake + + add_library(libC_Clang ...) + add_library(libCXX_Clang ...) + add_library(libC_Intel ...) + add_library(libCXX_Intel ...) + + add_executable(myapp main.c) + if (CXX_CONFIG) + target_sources(myapp PRIVATE file.cxx) + endif() + target_link_libraries(myapp + PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang> + $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang> + $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel> + $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>) + + This specifies the use of different link libraries based on both the + compiler id and link language. This example will have target ``libCXX_Clang`` + as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX`` + linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker. + Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target + ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when + ``Intel`` is the ``C`` linker. + + See :ref:`the note related to + <Constraints LINK_LANGUAGE Generator Expression>` + ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this + generator expression. + +``$<LINK_LANGUAGE:languages>`` + ``1`` when the language used for link step matches any of the entries + in ``languages``, otherwise ``0``. This expression may be used to specify + link libraries, link options, link directories and link dependencies of a + particular language in a target. For example: + + .. code-block:: cmake + + add_library(api_C ...) + add_library(api_CXX ...) + add_library(api INTERFACE) + target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c> + $<$<LINK_LANGUAGE:CXX>:-opt_cxx>) + target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C> + $<$<LINK_LANGUAGE:CXX>:api_CXX>) + + add_executable(myapp1 main.c) + target_link_options(myapp1 PRIVATE api) + + add_executable(myapp2 main.cpp) + target_link_options(myapp2 PRIVATE api) + + This specifies to use the ``api`` target for linking targets ``myapp1`` and + ``myapp2``. In practice, ``myapp1`` will link with target ``api_C`` and + option ``-opt_c`` because it will use ``C`` as link language. And ``myapp2`` + will link with ``api_CXX`` and option ``-opt_cxx`` because ``CXX`` will be + the link language. + + .. _`Constraints LINK_LANGUAGE Generator Expression`: + + .. note:: + + To determine the link language of a target, it is required to collect, + transitively, all the targets which will be linked to it. So, for link + libraries properties, a double evaluation will be done. During the first + evaluation, ``$<LINK_LANGUAGE:..>`` expressions will always return ``0``. + The link language computed after this first pass will be used to do the + second pass. To avoid inconsistency, it is required that the second pass + do not change the link language. Moreover, to avoid unexpected + side-effects, it is required to specify complete entities as part of the + ``$<LINK_LANGUAGE:..>`` expression. For example: + + .. code-block:: cmake + + add_library(lib STATIC file.cxx) + add_library(libother STATIC file.c) + + # bad usage + add_executable(myapp1 main.c) + target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>) + + # correct usage + add_executable(myapp2 main.c) + target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>) + + In this example, for ``myapp1``, the first pass will, unexpectedly, + determine that the link language is ``CXX`` because the evaluation of the + generator expression will be an empty string so ``myapp1`` will depends on + target ``lib`` which is ``C++``. On the contrary, for ``myapp2``, the first + evaluation will give ``C`` as link language, so the second pass will + correctly add target ``libother`` as link dependency. + +``$<DEVICE_LINK:list>`` + Returns the list if it is the device link step, an empty list otherwise. + The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION` + and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties. This expression can + only be used to specify link options. + +``$<HOST_LINK:list>`` + Returns the list if it is the normal link step, an empty list otherwise. + This expression is mainly useful when a device link step is also involved + (see ``$<DEVICE_LINK:list>`` generator expression). This expression can only + be used to specify link options. + String-Valued Generator Expressions =================================== @@ -450,22 +565,41 @@ Variable Queries <Boolean COMPILE_LANGUAGE Generator Expression>` ``$<COMPILE_LANGUAGE:language>`` for notes about the portability of this generator expression. +``$<LINK_LANGUAGE>`` + The link language of target when evaluating link options. + See :ref:`the related boolean expression + <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>`` + for notes about the portability of this generator expression. + + .. note:: + + This generator expression is not supported by the link libraries + properties to avoid side-effects due to the double evaluation of + these properties. Target-Dependent Queries ------------------------ +These queries refer to a target ``tgt``. This can be any runtime artifact, +namely: + +* an executable target created by :command:`add_executable` +* a shared library target (``.so``, ``.dll`` but not their ``.lib`` import library) + created by :command:`add_library` +* a static library target created by :command:`add_library` + +In the following, "the ``tgt`` filename" means the name of the ``tgt`` +binary file. This has to be distinguished from "the target name", +which is just the string ``tgt``. + ``$<TARGET_NAME_IF_EXISTS:tgt>`` - Expands to the ``tgt`` if the given target exists, an empty string - otherwise. + The target name ``tgt`` if the target exists, an empty string otherwise. ``$<TARGET_FILE:tgt>`` - Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a - target. + Full path to the ``tgt`` binary file. ``$<TARGET_FILE_BASE_NAME:tgt>`` - Base name of main file where ``tgt`` is the name of a target. - - The base name corresponds to the target file name (see - ``$<TARGET_FILE_NAME:tgt>``) without prefix and suffix. For example, if - target file name is ``libbase.so``, the base name is ``base``. + Base name of ``tgt``, i.e. ``$<TARGET_FILE_NAME:tgt>`` without prefix and + suffix. + For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME` @@ -480,32 +614,31 @@ Target-Dependent Queries Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. ``$<TARGET_FILE_PREFIX:tgt>`` - Prefix of main file where ``tgt`` is the name of a target. + Prefix of the ``tgt`` filename (such as ``lib``). See also the :prop_tgt:`PREFIX` target property. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. ``$<TARGET_FILE_SUFFIX:tgt>`` - Suffix of main file where ``tgt`` is the name of a target. - - The suffix corresponds to the file extension (such as ".so" or ".exe"). + Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``). See also the :prop_tgt:`SUFFIX` target property. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. ``$<TARGET_FILE_NAME:tgt>`` - Name of main file (.exe, .so.1.2, .a). + The ``tgt`` filename. ``$<TARGET_FILE_DIR:tgt>`` - Directory of main file (.exe, .so.1.2, .a). + Directory of the ``tgt`` binary file. ``$<TARGET_LINKER_FILE:tgt>`` - File used to link (.a, .lib, .so) where ``tgt`` is the name of a target. + File used when linking to the ``tgt`` target. This will usually + be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``), + but for a shared library on DLL platforms, it would be the ``.lib`` + import library associated with the DLL. ``$<TARGET_LINKER_FILE_BASE_NAME:tgt>`` - Base name of file used to link where ``tgt`` is the name of a target. - - The base name corresponds to the target linker file name (see - ``$<TARGET_LINKER_FILE_NAME:tgt>``) without prefix and suffix. For example, + Base name of file used to link the target ``tgt``, i.e. + ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example, if target file name is ``libbase.a``, the base name is ``base``. See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, @@ -520,7 +653,7 @@ Target-Dependent Queries Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. ``$<TARGET_LINKER_FILE_PREFIX:tgt>`` - Prefix of file used to link where ``tgt`` is the name of a target. + Prefix of file used to link target ``tgt``. See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target properties. @@ -538,15 +671,15 @@ Target-Dependent Queries Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. ``$<TARGET_LINKER_FILE_NAME:tgt>`` - Name of file used to link (.a, .lib, .so). + Name of file used to link target ``tgt``. ``$<TARGET_LINKER_FILE_DIR:tgt>`` - Directory of file used to link (.a, .lib, .so). + Directory of file used to link target ``tgt``. ``$<TARGET_SONAME_FILE:tgt>`` - File with soname (.so.3) where ``tgt`` is the name of a target. + File with soname (``.so.3``) where ``tgt`` is the name of a target. ``$<TARGET_SONAME_FILE_NAME:tgt>`` - Name of file with soname (.so.3). + Name of file with soname (``.so.3``). ``$<TARGET_SONAME_FILE_DIR:tgt>`` - Directory of with soname (.so.3). + Directory of with soname (``.so.3``). ``$<TARGET_PDB_FILE:tgt>`` Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -589,11 +722,10 @@ Target-Dependent Queries Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. ``$<TARGET_PROPERTY:prop>`` - Value of the property ``prop`` on the target on which the generator - expression is evaluated. Note that for generator expressions in - :ref:`Target Usage Requirements` this is the value of the property - on the consuming target rather than the target specifying the - requirement. + Value of the property ``prop`` on the target for which the expression + is being evaluated. Note that for generator expressions in + :ref:`Target Usage Requirements` this is the consuming target rather + than the target specifying the requirement. ``$<INSTALL_PREFIX>`` Content of the install prefix when the target is exported via :command:`install(EXPORT)`, or when evaluated in diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index c256250..3f3b70d 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,17 @@ 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.18 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0106: The Documentation module is removed. </policy/CMP0106> + CMP0105: Device link step uses the link options. </policy/CMP0105> + CMP0104: CMAKE_CUDA_ARCHITECTURES now detected for NVCC, empty CUDA_ARCHITECTURES not allowed. </policy/CMP0104> + CMP0103: Multiple export() with same FILE without APPEND is not allowed. </policy/CMP0103> + Policies Introduced by CMake 3.17 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 060a072..4103806 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -127,6 +127,7 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_DIRECTORY /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG /prop_tgt/ARCHIVE_OUTPUT_NAME + /prop_tgt/PCH_WARN_INVALID /prop_tgt/AUTOGEN_BUILD_DIR /prop_tgt/AUTOGEN_ORIGIN_DEPENDS /prop_tgt/AUTOGEN_PARALLEL @@ -171,6 +172,7 @@ Properties on Targets /prop_tgt/CONFIG_OUTPUT_NAME /prop_tgt/CONFIG_POSTFIX /prop_tgt/CROSSCOMPILING_EMULATOR + /prop_tgt/CUDA_ARCHITECTURES /prop_tgt/CUDA_PTX_COMPILATION /prop_tgt/CUDA_SEPARABLE_COMPILATION /prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS @@ -200,6 +202,7 @@ Properties on Targets /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY /prop_tgt/FRAMEWORK + /prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG /prop_tgt/FRAMEWORK_VERSION /prop_tgt/GENERATOR_FILE_NAME /prop_tgt/GHS_INTEGRITY_APP @@ -343,6 +346,7 @@ Properties on Targets /prop_tgt/UNITY_BUILD_BATCH_SIZE /prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE + /prop_tgt/UNITY_BUILD_MODE /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE @@ -369,12 +373,15 @@ Properties on Targets /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION /prop_tgt/VS_NO_SOLUTION_DEPLOY /prop_tgt/VS_PACKAGE_REFERENCES + /prop_tgt/VS_PLATFORM_TOOLSET /prop_tgt/VS_PROJECT_IMPORT /prop_tgt/VS_SCC_AUXPATH /prop_tgt/VS_SCC_LOCALPATH /prop_tgt/VS_SCC_PROJECTNAME /prop_tgt/VS_SCC_PROVIDER /prop_tgt/VS_SDK_REFERENCES + /prop_tgt/VS_SOLUTION_DEPLOY + /prop_tgt/VS_SOURCE_SETTINGS_tool /prop_tgt/VS_USER_PROPS /prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION /prop_tgt/VS_WINRT_COMPONENT @@ -478,12 +485,14 @@ Properties on Source Files /prop_sf/Swift_DEPENDENCIES_FILE /prop_sf/Swift_DIAGNOSTICS_FILE /prop_sf/SYMBOLIC + /prop_sf/UNITY_GROUP /prop_sf/VS_COPY_TO_OUT_DIR /prop_sf/VS_CSHARP_tagname /prop_sf/VS_DEPLOYMENT_CONTENT /prop_sf/VS_DEPLOYMENT_LOCATION /prop_sf/VS_INCLUDE_IN_VSIX /prop_sf/VS_RESOURCE_GENERATOR + /prop_sf/VS_SETTINGS /prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS /prop_sf/VS_SHADER_ENABLE_DEBUG /prop_sf/VS_SHADER_ENTRYPOINT diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index fc27739..7d802e1 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -388,6 +388,7 @@ Variables that Control the Build /variable/CMAKE_EXE_LINKER_FLAGS_INIT /variable/CMAKE_FOLDER /variable/CMAKE_FRAMEWORK + /variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY /variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE @@ -437,6 +438,7 @@ Variables that Control the Build /variable/CMAKE_OSX_ARCHITECTURES /variable/CMAKE_OSX_DEPLOYMENT_TARGET /variable/CMAKE_OSX_SYSROOT + /variable/CMAKE_PCH_WARN_INVALID /variable/CMAKE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_POSITION_INDEPENDENT_CODE @@ -486,6 +488,7 @@ Variables for Languages /variable/CMAKE_COMPILER_IS_GNUCC /variable/CMAKE_COMPILER_IS_GNUCXX /variable/CMAKE_COMPILER_IS_GNUG77 + /variable/CMAKE_CUDA_ARCHITECTURES /variable/CMAKE_CUDA_COMPILE_FEATURES /variable/CMAKE_CUDA_HOST_COMPILER /variable/CMAKE_CUDA_EXTENSIONS @@ -621,6 +624,7 @@ Variables for CTest /variable/CTEST_P4_COMMAND /variable/CTEST_P4_OPTIONS /variable/CTEST_P4_UPDATE_OPTIONS + /variable/CTEST_RESOURCE_SPEC_FILE /variable/CTEST_RUN_CURRENT_SCRIPT /variable/CTEST_SCP_COMMAND /variable/CTEST_SITE diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index d343874..9becfc6 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -358,6 +358,20 @@ Options in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`. This flag tells CMake to warn about other files as well. +``--profiling-output=<path>`` + Used in conjuction with ``--profiling-format`` to output to a given path. + +``--profiling-format=<file>`` + Enable the output of profiling data of CMake script in the given format. + + This can aid performance analysis of CMake scripts executed. Third party + applications should be used to process the output into human readable format. + + Currently supported values are: + ``google-trace`` Outputs in Google Trace Format, which can be parsed by the + about:tracing tab of Google Chrome or using a plugin for a tool like Trace + Compass. + .. _`Build Tool Mode`: Build a Project @@ -467,13 +481,17 @@ Run a Script .. code-block:: shell - cmake [{-D <var>=<value>}...] -P <cmake-script-file> + cmake [{-D <var>=<value>}...] -P <cmake-script-file> [-- <unparsed-options>...] Process the given cmake file as a script written in the CMake language. No configure or generate step is performed and the cache is not modified. If variables are defined using ``-D``, this must be done before the ``-P`` argument. +Any options after ``--`` are not parsed by CMake, but they are still included +in the set of :variable:`CMAKE_ARGV<n> <CMAKE_ARGV0>` variables passed to the +script (including the ``--`` itself). + Run a Command-Line Tool ======================= @@ -540,6 +558,9 @@ Available commands are: ``serverMode`` ``true`` if cmake supports server-mode and ``false`` otherwise. +``cat <files>...`` + Concatenate files and print on the standard output. + ``chdir <dir> <cmd> [<arg>...]`` Change the current working directory and run a command. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 6503f0e..5f953b3 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -72,6 +72,9 @@ Options This option can also be enabled by setting the :envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable +``--stop-on-failure`` + Stop running the tests when the first failure happens. + ``-F`` Enable failover. @@ -994,8 +997,12 @@ Configuration settings include: ``ResourceSpecFile`` Specify a - :ref:`resource specification file <ctest-resource-specification-file>`. See - :ref:`ctest-resource-allocation` for more information. + :ref:`resource specification file <ctest-resource-specification-file>`. + + * `CTest Script`_ variable: :variable:`CTEST_RESOURCE_SPEC_FILE` + * :module:`CTest` module variable: ``CTEST_RESOURCE_SPEC_FILE`` + + See :ref:`ctest-resource-allocation` for more information. ``LabelsForSubprojects`` Specify a semicolon-separated list of labels that will be treated as |