diff options
Diffstat (limited to 'Help')
29 files changed, 419 insertions, 112 deletions
diff --git a/Help/command/cmake_command.rst b/Help/command/cmake_command.rst new file mode 100644 index 0000000..9281647 --- /dev/null +++ b/Help/command/cmake_command.rst @@ -0,0 +1,40 @@ +cmake_command +------------- + +Call meta-operations on CMake commands. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + cmake_command(`INVOKE`_ <command> [<args>...]) + +Introduction +^^^^^^^^^^^^ + +This command will call meta-operations on built-in CMake commands or +those created via the :command:`macro` or :command:`function` commands. + +Invoking +^^^^^^^^ + +.. _INVOKE: + +.. code-block:: cmake + + cmake_command(INVOKE <command> [<args>...]) + +Invokes the named ``<command>`` with the given arguments (if any). +For example, the code: + +.. code-block:: cmake + + set(message_command "message") + cmake_command(INVOKE ${message_command} STATUS "Hello World!") + +is equivalent to + +.. code-block:: cmake + + message(STATUS "Hello World!") diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index 14f879d..b32025f 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -21,7 +21,9 @@ Execute one or more child processes. [COMMAND_ECHO <where>] [OUTPUT_STRIP_TRAILING_WHITESPACE] [ERROR_STRIP_TRAILING_WHITESPACE] - [ENCODING <name>]) + [ENCODING <name>] + [ECHO_OUTPUT_VARIABLE] + [ECHO_ERROR_VARIABLE]) Runs the given sequence of one or more commands. @@ -105,6 +107,15 @@ Options: for this encoding. In CMake 3.11.0, ``UTF-8`` was added for consistency with the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention. +``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE`` + The standard output or standard error will not be exclusively redirected to + the configured variables. + + The output will be duplicated, it will be sent into the configured variables + and also on standard output or standard error. + + This is analogous to the ``tee`` Unix command. + If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the same pipe the precedence is not specified. If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will diff --git a/Help/command/file.rst b/Help/command/file.rst index df7d8ba..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: diff --git a/Help/command/function.rst b/Help/command/function.rst index 53ba754..30938b3 100644 --- a/Help/command/function.rst +++ b/Help/command/function.rst @@ -44,11 +44,15 @@ can be invoked through any of foo() Foo() FOO() + cmake_command(INVOKE foo) and so on. However, it is strongly recommended to stay with the case chosen in the function definition. Typically functions use all-lowercase names. +The :command:`cmake_command(INVOKE ...)` command can also be used to invoke the +function. + Arguments ^^^^^^^^^ diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 3f6f2f9..ee955cb 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -42,11 +42,15 @@ can be invoked through any of foo() Foo() FOO() + cmake_command(INVOKE foo) and so on. However, it is strongly recommended to stay with the case chosen in the macro definition. Typically macros use all-lowercase names. +The :command:`cmake_command(INVOKE ...)` command can also be used to invoke the +macro. + Arguments ^^^^^^^^^ diff --git a/Help/command/string.rst b/Help/command/string.rst index ba7c656..cfcf914 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -36,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>) @@ -355,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/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst index d7c71b4..776bb46 100644 --- a/Help/cpack_gen/ifw.rst +++ b/Help/cpack_gen/ifw.rst @@ -24,33 +24,6 @@ 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 -^^^^^^^^^^^^^^^^^^^^ - -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 -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. - -Localization of the description of your components and groups is useful for -users of your installers. - -A localized variable or argument can contain a single default value, and a -set of pairs the name of the locale and the localized value. - -For example: - -.. code-block:: cmake - - set(LOCALIZABLE_VARIABLE "Default value" - en "English value" - en_US "American value" - en_GB "Great Britain value" - ) - Variables ^^^^^^^^^ @@ -300,24 +273,58 @@ the path may be specified in either a CMake or an environment variable: The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides the value of the :variable:`QTIFWDIR` variable. +Other Settings +^^^^^^^^^^^^^^ Online installer -^^^^^^^^^^^^^^^^ +"""""""""""""""" -By default CPack IFW generator makes offline installer. This means that all -components will be packaged into a binary file. +By default, this generator generates an *offline installer*. This means that +that all packaged files are fully contained in the installer executable. -To make a component downloaded, you must set the ``DOWNLOADED`` option in -:command:`cpack_add_component`. +In contrast, an *online installer* will download some or all components from +a remote server. -Then you would use the command :command:`cpack_configure_downloads`. -If you set ``ALL`` option all components will be downloaded. +The ``DOWNLOADED`` option in the :command:`cpack_add_component` command +specifies that a component is to be downloaded. Alternatively, the ``ALL`` +option in the :command:`cpack_configure_downloads` command specifies that +`all` components are to be be downloaded. -You also can use command :command:`cpack_ifw_add_repository` and -variable :variable:`CPACK_IFW_DOWNLOAD_ALL` for more specific configuration. +The :command:`cpack_ifw_add_repository` command and the +:variable:`CPACK_IFW_DOWNLOAD_ALL` variable allow for more specific +configuration. -CPack IFW generator creates "repository" dir in current binary dir. You -would copy content of this dir to specified ``site`` (``url``). +When there are online components, CPack will write them to archive files. +The help page of the :module:`CPackComponent` module, especially the section +on the :command:`cpack_configure_downloads` function, explains how to make +these files accessible from a download URL. + +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 +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. + +Localization of the description of your components and groups is useful for +users of your installers. + +A localized variable or argument can contain a single default value, and a +set of pairs the name of the locale and the localized value. + +For example: + +.. code-block:: cmake + + set(LOCALIZABLE_VARIABLE "Default value" + en "English value" + en_US "American value" + en_GB "Great Britain value" + ) See Also ^^^^^^^^ diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index 2693c7b..66d5464 100644 --- a/Help/cpack_gen/rpm.rst +++ b/Help/cpack_gen/rpm.rst @@ -473,38 +473,42 @@ List of CPack RPM generator specific variables: .. variable:: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE + CPACK_RPM_PRE_TRANS_SCRIPT_FILE - Path to file containing pre (un)install script. + Path to file containing pre install/uninstall/transaction script. * Mandatory : NO * Default : - - May be used to embed a pre (un)installation script in the spec file. + May be used to embed a pre installation/uninstallation/transaction script in the spec file. The referred script file (or both) will be read and directly put after the ``%pre`` or ``%preun`` section - If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install + If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction script for each component can be overridden with - ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE`` and - ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``. + ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE``, + ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``, and + ``CPACK_RPM_<COMPONENT>_PRE_TRANS_SCRIPT_FILE`` One may verify which scriptlet has been included with:: rpm -qp --scripts package.rpm .. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE + CPACK_RPM_POST_TRANS_SCRIPT_FILE - Path to file containing post (un)install script. + Path to file containing post install/uninstall/transaction script. * Mandatory : NO * Default : - - May be used to embed a post (un)installation script in the spec file. + May be used to embed a post installation/uninstallation/transaction script in the spec file. The referred script file (or both) will be read and directly put after the ``%post`` or ``%postun`` section. - If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install + If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction script for each component can be overridden with - ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE`` and - ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``. + ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE``, + ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``, and + ``CPACK_RPM_<COMPONENT>_POST_TRANS_SCRIPT_FILE`` One may verify which scriptlet has been included with:: rpm -qp --scripts package.rpm diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst index 11c59f2..1f68535 100644 --- a/Help/generator/Ninja Multi-Config.rst +++ b/Help/generator/Ninja Multi-Config.rst @@ -12,9 +12,10 @@ 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.) +are intended to be run with ``ninja -f build-<Config>.ninja``. A +``build.ninja`` file is also generated, using the configuration from either +:variable:`CMAKE_DEFAULT_BUILD_TYPE` or the first item from +:variable:`CMAKE_CONFIGURATION_TYPES`. ``cmake --build . --config <Config>`` will always use ``build-<Config>.ninja`` to build. If no ``--config`` argument is specified, ``cmake --build .`` will @@ -35,7 +36,7 @@ The ``Ninja Multi-Config`` generator recognizes the following variables: Specifies the total set of configurations to build. See the variable's documentation for more information. -:variable:`CMAKE_NMC_CROSS_CONFIGS` +:variable:`CMAKE_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. @@ -49,36 +50,36 @@ The ``Ninja Multi-Config`` generator recognizes the following variables: The value of this variable must be a subset of :variable:`CMAKE_CONFIGURATION_TYPES`. -:variable:`CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG` +:variable:`CMAKE_DEFAULT_BUILD_TYPE` 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. + this variable is specified, ``build.ninja`` uses build rules from + ``build-<Config>.ninja`` by default. All custom commands are executed with + this configuration. If the variable is not specified, the first item from + :variable:`CMAKE_CONFIGURATION_TYPES` is used instead. The value of this variable must be one of the items from :variable:`CMAKE_CONFIGURATION_TYPES`. -:variable:`CMAKE_NMC_DEFAULT_CONFIGS` +:variable:`CMAKE_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 + configurations from :variable:`CMAKE_CROSS_CONFIGS` are used. If it is not specified, it defaults to - :variable:`CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG`. + :variable:`CMAKE_DEFAULT_BUILD_TYPE`. 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``, + :variable:`CMAKE_DEFAULT_BUILD_TYPE` to ``Release``, but + set :variable:`CMAKE_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. + :variable:`CMAKE_CROSS_CONFIGS` or be the same as + :variable:`CMAKE_DEFAULT_BUILD_TYPE`. It must not be + specified if :variable:`CMAKE_DEFAULT_BUILD_TYPE` or + :variable:`CMAKE_CROSS_CONFIGS` is not used. Consider the following example: @@ -104,8 +105,8 @@ 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: +But if :variable:`CMAKE_CROSS_CONFIGS` is set to ``all``, and you run the +following instead: .. code-block:: shell diff --git a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt index 4bf6024..f64c6ac 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt @@ -8,10 +8,20 @@ target_include_directories(MathFunctions # does this system provide the log and exp functions? include(CheckSymbolExists) -set(CMAKE_REQUIRED_LIBRARIES "m") check_symbol_exists(log "math.h" HAVE_LOG) check_symbol_exists(exp "math.h" HAVE_EXP) +if(NOT (HAVE_LOG AND HAVE_EXP)) + unset(HAVE_LOG CACHE) + unset(HAVE_EXP CACHE) + set(CMAKE_REQUIRED_LIBRARIES "m") + check_symbol_exists(log "math.h" HAVE_LOG) + check_symbol_exists(exp "math.h" HAVE_EXP) + if(HAVE_LOG AND HAVE_EXP) + target_link_libraries(MathFunctions PRIVATE m) + endif() +endif() +# add compile definitions if(HAVE_LOG AND HAVE_EXP) target_compile_definitions(MathFunctions PRIVATE "HAVE_LOG" "HAVE_EXP") diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index a844cbf..4fbcd4c 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -386,7 +386,7 @@ these functions using the :module:`CheckSymbolExists` module in the top-level .. literalinclude:: Step6/MathFunctions/CMakeLists.txt :language: cmake :start-after: # does this system provide the log and exp functions? - :end-before: if(HAVE_LOG AND HAVE_EXP) + :end-before: # add compile definitions Now let's add these defines to ``TutorialConfig.h.in`` so that we can use them from ``mysqrt.cxx``: 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-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 691481b..72de4ac 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -259,6 +259,109 @@ 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. + String-Valued Generator Expressions =================================== @@ -450,22 +553,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 +602,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 +641,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 +659,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 +710,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-properties.7.rst b/Help/manual/cmake-properties.7.rst index fb84378..37f8678 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -375,6 +375,7 @@ Properties on Targets /prop_tgt/VS_SCC_PROJECTNAME /prop_tgt/VS_SCC_PROVIDER /prop_tgt/VS_SDK_REFERENCES + /prop_tgt/VS_SOLUTION_DEPLOY /prop_tgt/VS_USER_PROPS /prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION /prop_tgt/VS_WINRT_COMPONENT diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 1023a66..a639b5d 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -372,11 +372,14 @@ Variables that Control the Build /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_CONFIG_POSTFIX + /variable/CMAKE_CROSS_CONFIGS /variable/CMAKE_CTEST_ARGUMENTS /variable/CMAKE_CUDA_SEPARABLE_COMPILATION /variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS /variable/CMAKE_CUDA_RUNTIME_LIBRARY /variable/CMAKE_DEBUG_POSTFIX + /variable/CMAKE_DEFAULT_BUILD_TYPE + /variable/CMAKE_DEFAULT_CONFIGS /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS @@ -428,9 +431,6 @@ 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 diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 2bfaafe..6503f0e 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -1331,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/prop_tgt/VS_SOLUTION_DEPLOY.rst b/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst new file mode 100644 index 0000000..7906d75 --- /dev/null +++ b/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst @@ -0,0 +1,29 @@ +VS_SOLUTION_DEPLOY +------------------ + +Specify that the target should be marked for deployment when not targeting +Windows CE, Windows Phone or a Windows Store application. + +If the target platform doesn't support deployment, this property won't have any effect. + +Generator expressions are supported. + +Example 1 +^^^^^^^^^ + +This shows setting the variable for the target foo. + +.. code-block:: cmake + + add_executable(foo SHARED foo.cpp) + set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY ON) + +Example 2 +^^^^^^^^^ + +This shows setting the variable for the Release configuration only. + +.. code-block:: cmake + + add_executable(foo SHARED foo.cpp) + set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY "$<NOT:$<CONFIG:Release>>") diff --git a/Help/release/dev/CPackRPM-trans-scripts.rst b/Help/release/dev/CPackRPM-trans-scripts.rst new file mode 100644 index 0000000..57fc099 --- /dev/null +++ b/Help/release/dev/CPackRPM-trans-scripts.rst @@ -0,0 +1,7 @@ +CPackRPM-trans-scripts +---------------------- + +* The :cpack_gen:`CPack RPM Generator` gained + :variable:`CPACK_RPM_PRE_TRANS_SCRIPT_FILE` + :variable:`CPACK_RPM_POST_TRANS_SCRIPT_FILE` + variables to specify pre- and post-trans scripts. diff --git a/Help/release/dev/cmake_command-command.rst b/Help/release/dev/cmake_command-command.rst new file mode 100644 index 0000000..ebe75b1 --- /dev/null +++ b/Help/release/dev/cmake_command-command.rst @@ -0,0 +1,6 @@ +cmake_command +------------- + +* The :command:`cmake_command()` command was added for meta-operations on + scripted or built-in commands, starting with a mode to ``INVOKE`` other + commands. diff --git a/Help/release/dev/execute_process.rst b/Help/release/dev/execute_process.rst new file mode 100644 index 0000000..02e813b --- /dev/null +++ b/Help/release/dev/execute_process.rst @@ -0,0 +1,5 @@ +execute_process +--------------- + +* The :command:`execute_process` command gained the ``ECHO_OUTPUT_VARIABLE`` + and ``ECHO_ERROR_VARIABLE`` options. diff --git a/Help/release/dev/findswig-components.rst b/Help/release/dev/findswig-components.rst new file mode 100644 index 0000000..ce569be --- /dev/null +++ b/Help/release/dev/findswig-components.rst @@ -0,0 +1,5 @@ +findswig-components +------------------- + +* The :module:`FindSWIG` module now accepts target languages as ``COMPONENTS`` + and ``OPTIONAL_COMPONENTS`` arguments to ``find_package``. diff --git a/Help/release/dev/genex-LINK_LANGUAGE.rst b/Help/release/dev/genex-LINK_LANGUAGE.rst new file mode 100644 index 0000000..05894d6 --- /dev/null +++ b/Help/release/dev/genex-LINK_LANGUAGE.rst @@ -0,0 +1,5 @@ +genex-LINK_LANGUAGE +=================== + +* The ``$<LINK_LANGUAGE:...>`` and ``$<LINK_LANG_AND_ID:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` were added. 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/dev/useswig-fortran.rst b/Help/release/dev/useswig-fortran.rst new file mode 100644 index 0000000..17baf96 --- /dev/null +++ b/Help/release/dev/useswig-fortran.rst @@ -0,0 +1,7 @@ +useswig-fortran +--------------- + +* The :module:`UseSWIG` module now supports Fortran as a target language if + the ``SWIG_EXECUTABLE`` is SWIG-Fortran_. + +.. _`SWIG-Fortran`: https://github.com/swig-fortran/swig diff --git a/Help/release/dev/vs-sln-deploy.rst b/Help/release/dev/vs-sln-deploy.rst new file mode 100644 index 0000000..2e83e52 --- /dev/null +++ b/Help/release/dev/vs-sln-deploy.rst @@ -0,0 +1,6 @@ +vs-sln-deploy +------------- + +* The :prop_tgt:`VS_SOLUTION_DEPLOY` target property was added to tell + :ref:`Visual Studio Generators` for VS 2010 and above to mark a + target for deployment even when not building for Windows Phone/Store/CE. diff --git a/Help/variable/CMAKE_CFG_INTDIR.rst b/Help/variable/CMAKE_CFG_INTDIR.rst index af82f75..842654e 100644 --- a/Help/variable/CMAKE_CFG_INTDIR.rst +++ b/Help/variable/CMAKE_CFG_INTDIR.rst @@ -16,6 +16,13 @@ Example values: $(Configuration) = Visual Studio 10 $(CONFIGURATION) = Xcode . = Make-based tools + . = Ninja + ${CONFIGURATION} = Ninja Multi-Config + +Note that this variable only has limited support on +:generator:`Ninja Multi-Config`. It is recommended that you use the +``$<CONFIG>`` :manual:`generator expression <cmake-generator-expressions(7)>` +instead. Since these values are evaluated by the native build system, this variable is suitable only for use in command lines that will be diff --git a/Help/variable/CMAKE_NMC_CROSS_CONFIGS.rst b/Help/variable/CMAKE_CROSS_CONFIGS.rst index 6eb6494..c850af2 100644 --- a/Help/variable/CMAKE_NMC_CROSS_CONFIGS.rst +++ b/Help/variable/CMAKE_CROSS_CONFIGS.rst @@ -1,5 +1,5 @@ -CMAKE_NMC_CROSS_CONFIGS -------------------------------- +CMAKE_CROSS_CONFIGS +------------------- Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of configurations available from all ``build-<Config>.ninja`` files in the diff --git a/Help/variable/CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG.rst b/Help/variable/CMAKE_DEFAULT_BUILD_TYPE.rst index c0eab56..62ee0d2 100644 --- a/Help/variable/CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG.rst +++ b/Help/variable/CMAKE_DEFAULT_BUILD_TYPE.rst @@ -1,5 +1,5 @@ -CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG -------------------------------------------- +CMAKE_DEFAULT_BUILD_TYPE +------------------------ Specifies the configuration to use by default in a ``build.ninja`` file in the :generator:`Ninja Multi-Config` generator. See the generator's documentation diff --git a/Help/variable/CMAKE_NMC_DEFAULT_CONFIGS.rst b/Help/variable/CMAKE_DEFAULT_CONFIGS.rst index e2bb017..86d8a5a 100644 --- a/Help/variable/CMAKE_NMC_DEFAULT_CONFIGS.rst +++ b/Help/variable/CMAKE_DEFAULT_CONFIGS.rst @@ -1,5 +1,5 @@ -CMAKE_NMC_DEFAULT_CONFIGS ---------------------------------- +CMAKE_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 |