diff options
Diffstat (limited to 'Help/command')
36 files changed, 667 insertions, 161 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index cd3c78b..59a4e71 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -15,6 +15,7 @@ The general signature is: [PATHS [path | ENV var]... ] [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] [PATH_SUFFIXES suffix1 [suffix2 ...]] + [VALIDATOR function] [DOC "cache documentation string"] [NO_CACHE] [REQUIRED] @@ -66,6 +67,26 @@ Options include: Specify additional subdirectories to check below each directory location otherwise considered. +``VALIDATOR`` + .. versionadded:: 3.25 + + Specify a :command:`function` (a :command:`macro` is not an acceptable + choice) which will be called for each found item. The search ends when + the validation function returns a successful status. + + The validation function expects two arguments: output variable name and item + value. By default, the output variable name already holds a ``TRUE`` value. + + .. parsed-literal:: + + function (MY_CHECK output_status item) + if (NOT item MATCHES ...) + set(${output_status} FALSE PARENT_SCOPE) + endif() + endfunction() + + |FIND_XXX| (result NAMES ... VALIDATOR my_check) + ``DOC`` Specify the documentation string for the ``<VAR>`` cache entry. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 9e60d2d..99adc85 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -67,6 +67,8 @@ The options are: Each byproduct file will be marked with the :prop_sf:`GENERATED` source file property automatically. + *See policy* :policy:`CMP0058` *for the motivation behind this feature.* + Explicit specification of byproducts is supported by the :generator:`Ninja` generator to tell the ``ninja`` build tool how to regenerate byproducts when they are missing. It is @@ -434,7 +436,7 @@ one of the keywords to make clear the behavior they expect. Because generator expressions can be used in custom commands, it is possible to define ``COMMAND`` lines or whole custom commands which evaluate to empty strings for certain configurations. - For **Visual Studio 2010 (and newer)** generators these command + For **Visual Studio 11 2012 (and newer)** generators these command lines or custom commands will be omitted for the specific configuration and no "empty-string-command" will be added. diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index def23fa..d8882ca 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -42,6 +42,8 @@ The options are: Each byproduct file will be marked with the :prop_sf:`GENERATED` source file property automatically. + *See policy* :policy:`CMP0058` *for the motivation behind this feature.* + Explicit specification of byproducts is supported by the :generator:`Ninja` generator to tell the ``ninja`` build tool how to regenerate byproducts when they are missing. It is diff --git a/Help/command/add_subdirectory.rst b/Help/command/add_subdirectory.rst index 8dba986..13cae10 100644 --- a/Help/command/add_subdirectory.rst +++ b/Help/command/add_subdirectory.rst @@ -5,7 +5,7 @@ Add a subdirectory to the build. .. code-block:: cmake - add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL]) + add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM]) Adds a subdirectory to the build. The source_dir specifies the directory in which the source CMakeLists.txt and code files are @@ -33,3 +33,10 @@ dependencies supersede this exclusion. If a target built by the parent project depends on a target in the subdirectory, the dependee target will be included in the parent project build system to satisfy the dependency. + +If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory +property of the subdirectory will be set to true. This property is +used to initialize the :prop_tgt:`SYSTEM` property of each target +created in that subdirectory. The include directories of targets with +:prop_tgt:`SYSTEM` set to true will be treated as ``SYSTEM`` when +compiling consumers. diff --git a/Help/command/block.rst b/Help/command/block.rst new file mode 100644 index 0000000..9d37deb --- /dev/null +++ b/Help/command/block.rst @@ -0,0 +1,75 @@ +block +----- + +.. versionadded:: 3.25 + +Evaluate a group of commands with a dedicated variable and/or policy scope. + +.. code-block:: cmake + + block([SCOPE_FOR (POLICIES|VARIABLES)] [PROPAGATE <var-name>...]) + <commands> + endblock() + +All commands between ``block()`` and the matching :command:`endblock` are +recorded without being invoked. Once the :command:`endblock` is evaluated, the +recorded list of commands is invoked inside the requested scopes, and, finally, +the scopes created by ``block()`` command are removed. + +``SCOPE_FOR`` + Specify which scopes must be created. + + ``POLICIES`` + Create a new policy scope. This is equivalent to + :command:`cmake_policy(PUSH)`. + + ``VARIABLES`` + Create a new variable scope. + + If ``SCOPE_FOR`` is not specified, this is equivalent to: + + .. code-block:: cmake + + block(SCOPE_FOR VARIABLES POLICIES) + +``PROPAGATE`` + When a variable scope is created by :command:`block` command, this option + set or unset the specified variables in the parent scope. This is equivalent + to :command:`set(PARENT_SCOPE)` or :command:`unset(PARENT_SCOPE)` commands. + + .. code-block:: cmake + + set(VAR1 "INIT1") + set(VAR2 "INIT2") + + block(PROPAGATE VAR1 VAR2) + set(VAR1 "VALUE1") + unset(VAR2) + endblock() + + # here, VAR1 holds value VALUE1 and VAR2 is unset + + This option is only allowed when a variable scope is created. An error will + be raised in the other cases. + +When the ``block`` is local to a :command:`foreach` or :command:`while` +command, the commands :command:`break` and :command:`continue` can be used +inside this block. + +.. code-block:: cmake + + while(TRUE) + block() + ... + # the break() command will terminate the while() command + break() + endblock() + endwhile() + + +See Also +^^^^^^^^ + + * :command:`endblock` + * :command:`return` + * :command:`cmake_policy` diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index a03979d..3d86a2e 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -24,12 +24,12 @@ options, if any. The trailing ``-- -i`` option is added for :ref:`Makefile Generators` if policy :policy:`CMP0061` is not set to ``NEW``. -When invoked, this ``cmake --build`` command line will launch the +When invoked, this :option:`cmake --build` command line will launch the underlying build system tool. .. versionadded:: 3.21 - The ``PARALLEL_LEVEL`` argument can be used to set the ``--parallel`` - flag. + The ``PARALLEL_LEVEL`` argument can be used to set the + :option:`--parallel <cmake--build --parallel>` flag. .. code-block:: cmake @@ -39,7 +39,7 @@ This second signature is deprecated, but still available for backwards compatibility. Use the first signature instead. It sets the given ``<cachevariable>`` to a command-line string as -above but without the ``--target`` option. +above but without the :option:`--target <cmake--build --target>` option. The ``<makecommand>`` is ignored but should be the full path to devenv, nmake, make or one of the end user build tools for legacy invocations. diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index cb8d60b..8801a9f 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -14,6 +14,7 @@ Synopsis cmake_language(`EVAL`_ CODE <code>...) cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...]) cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...) + cmake_language(`GET_MESSAGE_LOG_LEVEL`_ <out-var>) Introduction ^^^^^^^^^^^^ @@ -50,6 +51,7 @@ is equivalent to To ensure consistency of the code, the following commands are not allowed: * ``if`` / ``elseif`` / ``else`` / ``endif`` + * ``block`` / ``endblock`` * ``while`` / ``endwhile`` * ``foreach`` / ``endforeach`` * ``function`` / ``endfunction`` @@ -491,3 +493,29 @@ calling the provider command recursively for the same dependency. SET_DEPENDENCY_PROVIDER mycomp_provide_dependency SUPPORTED_METHODS FIND_PACKAGE ) + +Getting current message log level +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.25 + +.. _GET_MESSAGE_LOG_LEVEL: +.. _query_message_log_level: + +.. code-block:: cmake + + cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>) + +Writes the current :command:`message` logging level +into the given ``<output_variable>``. + +See :command:`message` for the possible logging levels. + +The current message logging level can be set either using the +:option:`--log-level <cmake --log-level>` +command line option of the :manual:`cmake(1)` program or using +the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable. + +If both the command line option and the variable are set, the command line +option takes precedence. If neither are set, the default logging level +is returned. diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index 94060d9..54fc548 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -103,6 +103,47 @@ Calls to the :command:`cmake_minimum_required(VERSION)`, ``cmake_policy(VERSION)``, or ``cmake_policy(SET)`` commands influence only the current top of the policy stack. +.. versionadded:: 3.25 + The :command:`block` and :command:`endblock` commands offer a more flexible + and more secure way to manage the policy stack. The pop action is done + automatically when the :command:`endblock` command is executed, so it avoid + to call the :command:`cmake_policy(POP)` command before each + :command:`return` command. + + .. code-block:: cmake + + # stack management with cmake_policy() + function(my_func) + cmake_policy(PUSH) + cmake_policy(SET ...) + if (<cond1>) + ... + cmake_policy(POP) + return() + elseif(<cond2>) + ... + cmake_policy(POP) + return() + endif() + ... + cmake_policy(POP) + endfunction() + + # stack management with block()/endblock() + function(my_func) + block(SCOPE_FOR POLICIES) + cmake_policy(SET ...) + if (<cond1>) + ... + return() + elseif(<cond2>) + ... + return() + endif() + ... + endblock() + endfunction() + Commands created by the :command:`function` and :command:`macro` commands record policy settings when they are created and use the pre-record policies when they are invoked. If the function or diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index e05df1a..8c81f2d 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -40,8 +40,8 @@ The options are: ``CONFIGURATION <config>`` Specify the build configuration (e.g. ``Debug``). If not specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked. - Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)` - command will be used, if any. + Otherwise the :option:`-C \<cfg\> <ctest -C>` option given to the + :manual:`ctest(1)` command will be used, if any. ``PARALLEL_LEVEL <parallel>`` .. versionadded:: 3.21 @@ -54,7 +54,7 @@ The options are: Pass additional arguments to the underlying build command. If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked. This can, e.g., be used to trigger a parallel build using the - ``-j`` option of make. See the :module:`ProcessorCount` module + ``-j`` option of ``make``. See the :module:`ProcessorCount` module for an example. ``PROJECT_NAME <project-name>`` diff --git a/Help/command/ctest_run_script.rst b/Help/command/ctest_run_script.rst index 5ec543e..a2b348f 100644 --- a/Help/command/ctest_run_script.rst +++ b/Help/command/ctest_run_script.rst @@ -1,15 +1,15 @@ ctest_run_script ---------------- -runs a ctest -S script +runs a :option:`ctest -S` script :: ctest_run_script([NEW_PROCESS] script_file_name script_file_name1 script_file_name2 ... [RETURN_VALUE var]) -Runs a script or scripts much like if it was run from ctest -S. If no -argument is provided then the current script is run using the current +Runs a script or scripts much like if it was run from :option:`ctest -S`. +If no argument is provided then the current script is run using the current settings of the variables. If ``NEW_PROCESS`` is specified then each script will be run in a separate process.If ``RETURN_VALUE`` is specified the return value of the last script run will be put into ``var``. diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index c0f3c6d..921279a 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -45,7 +45,7 @@ The parameters are as follows: ctest_start(Experimental GROUP GroupExperimental) - Later, in another ``ctest -S`` script: + Later, in another :option:`ctest -S` script: .. code-block:: cmake diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 65f82d7..4f9f891 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -109,8 +109,9 @@ The options are: While running tests in parallel, try not to start tests when they may cause the CPU load to pass above a given threshold. If not specified the :variable:`CTEST_TEST_LOAD` variable will be checked, - and then the ``--test-load`` command-line argument to :manual:`ctest(1)`. - See also the ``TestLoad`` setting in the :ref:`CTest Test Step`. + and then the :option:`--test-load <ctest --test-load>` command-line + argument to :manual:`ctest(1)`. See also the ``TestLoad`` setting + in the :ref:`CTest Test Step`. ``REPEAT <mode>:<n>`` .. versionadded:: 3.17 @@ -176,8 +177,9 @@ See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`, :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` and :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables, along with their corresponding :manual:`ctest(1)` command line options -``--test-output-size-passed``, ``--test-output-size-failed``, and -``--test-output-truncation``. +:option:`--test-output-size-passed <ctest --test-output-size-passed>`, +:option:`--test-output-size-failed <ctest --test-output-size-failed>`, and +:option:`--test-output-truncation <ctest --test-output-truncation>`. .. _`Additional Test Measurements`: diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index d2acbc8..d9103b8 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -1,13 +1,14 @@ enable_language --------------- -Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc) + +Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc) .. code-block:: cmake - enable_language(<lang> [OPTIONAL] ) + enable_language(<lang>... [OPTIONAL]) -Enables support for the named language in CMake. This is -the same as the :command:`project` command but does not create any of the extra +Enables support for the named languages in CMake. This is the same as +the :command:`project` command but does not create any of the extra variables that are created by the project command. Example languages are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``. diff --git a/Help/command/endblock.rst b/Help/command/endblock.rst new file mode 100644 index 0000000..3b21c12 --- /dev/null +++ b/Help/command/endblock.rst @@ -0,0 +1,11 @@ +endblock +-------- + +.. versionadded:: 3.25 + +Ends a list of commands in a :command:`block` and removes the scopes +created by the :command:`block` command. + +.. code-block:: cmake + + endblock() diff --git a/Help/command/export.rst b/Help/command/export.rst index dc69645..0f79f63 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -25,7 +25,8 @@ Exporting Targets .. code-block:: cmake export(TARGETS <target>... [NAMESPACE <namespace>] - [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]) + [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES] + [CXX_MODULES_DIRECTORY <directory>]) Creates a file ``<filename>`` that may be included by outside projects to import targets named by ``<target>...`` from the current project's build tree. @@ -52,6 +53,16 @@ The options are: in the export, even when policy :policy:`CMP0022` is NEW. This is useful to support consumers using CMake versions older than 2.8.12. +``CXX_MODULES_DIRECTORY <directory>`` + + .. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + + Export C++ module properties to files under the given directory. Each file + will be named according to the target's export name (without any namespace). + These files will automatically be included from the export file. + This signature requires all targets to be listed explicitly. If a library target is included in the export, but a target to which it links is not included, the behavior is unspecified. See the `export(EXPORT)`_ signature @@ -95,7 +106,8 @@ Exporting Targets matching install(EXPORT) .. code-block:: cmake - export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]) + export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>] + [CXX_MODULES_DIRECTORY <directory>]) Creates a file ``<filename>`` that may be included by outside projects to import targets from the current project's build tree. This is the same diff --git a/Help/command/file.rst b/Help/command/file.rst index 3374d2d..fbe2a81 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -1121,8 +1121,11 @@ Additional options to ``DOWNLOAD`` are: Verify that the downloaded content hash matches the expected value, where ``ALGO`` is one of the algorithms supported by ``file(<HASH>)``. - If it does not match, the operation fails with an error. It is an error to - specify this if ``DOWNLOAD`` is not given a ``<file>``. + If the file already exists and matches the hash, the download is skipped. + If the file already exists and does not match the hash, the file is + downloaded again. If after download the file does not match the hash, the + operation fails with an error. It is an error to specify this option if + ``DOWNLOAD`` is not given a ``<file>``. ``EXPECTED_MD5 <value>`` Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error to diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index c96d84e..c99c73d 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -285,29 +285,40 @@ CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a configuration file. The tables below show the directories searched. Each entry is meant for installation trees following Windows (``W``), UNIX -(``U``), or Apple (``A``) conventions:: - - <prefix>/ (W) - <prefix>/(cmake|CMake)/ (W) - <prefix>/<name>*/ (W) - <prefix>/<name>*/(cmake|CMake)/ (W) - <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/ (U) - <prefix>/(lib/<arch>|lib*|share)/<name>*/ (U) - <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (U) - <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ (W/U) - <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U) - <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U) +(``U``), or Apple (``A``) conventions: + +==================================================================== ========== + Entry Convention +==================================================================== ========== + ``<prefix>/`` W + ``<prefix>/(cmake|CMake)/`` W + ``<prefix>/<name>*/`` W + ``<prefix>/<name>*/(cmake|CMake)/`` W + ``<prefix>/<name>*/(cmake|CMake)/<name>*/`` [#]_ W + ``<prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/`` U + ``<prefix>/(lib/<arch>|lib*|share)/<name>*/`` U + ``<prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/`` U + ``<prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/`` W/U + ``<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/`` W/U + ``<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/`` W/U +==================================================================== ========== + +.. [#] .. versionadded:: 3.25 On systems supporting macOS :prop_tgt:`FRAMEWORK` and :prop_tgt:`BUNDLE`, the following directories are searched for Frameworks or Application Bundles -containing a configuration file:: - - <prefix>/<name>.framework/Resources/ (A) - <prefix>/<name>.framework/Resources/CMake/ (A) - <prefix>/<name>.framework/Versions/*/Resources/ (A) - <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A) - <prefix>/<name>.app/Contents/Resources/ (A) - <prefix>/<name>.app/Contents/Resources/CMake/ (A) +containing a configuration file: + +=========================================================== ========== + Entry Convention +=========================================================== ========== + ``<prefix>/<name>.framework/Resources/`` A + ``<prefix>/<name>.framework/Resources/CMake/`` A + ``<prefix>/<name>.framework/Versions/*/Resources/`` A + ``<prefix>/<name>.framework/Versions/*/Resources/CMake/`` A + ``<prefix>/<name>.app/Contents/Resources/`` A + ``<prefix>/<name>.app/Contents/Resources/CMake/`` A +=========================================================== ========== In all cases the ``<name>`` is treated as case-insensitive and corresponds to any of the names specified (``<PackageName>`` or names given by ``NAMES``). @@ -368,7 +379,7 @@ enabled. See policy :policy:`CMP0074`. 2. Search paths specified in cmake-specific cache variables. These - are intended to be used on the command line with a ``-DVAR=value``. + are intended to be used on the command line with a :option:`-DVAR=VALUE <cmake -D>`. The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`. This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``: diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index d9f54ca..ddf8dfa 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -130,3 +130,11 @@ yields -- en=two, ba=dua -- en=three, ba=tiga -- en=four, ba= + +See Also +^^^^^^^^ + +* :command:`break` +* :command:`continue` +* :command:`endforeach` +* :command:`while` diff --git a/Help/command/function.rst b/Help/command/function.rst index 3d25aa4..fc55c03 100644 --- a/Help/command/function.rst +++ b/Help/command/function.rst @@ -73,3 +73,9 @@ argument. Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined behavior. Checking that ``ARGC`` is greater than ``#`` is the only way to ensure that ``ARGV#`` was passed to the function as an extra argument. + +See Also +^^^^^^^^ + +* :command:`endfunction` +* :command:`return` diff --git a/Help/command/get_test_property.rst b/Help/command/get_test_property.rst index e02b9bc..6bcc1ef 100644 --- a/Help/command/get_test_property.rst +++ b/Help/command/get_test_property.rst @@ -16,6 +16,7 @@ relevant parent scope as described for the :command:`define_property` command and if still unable to find the property, ``VAR`` will be set to an empty string. -For a list of standard properties you can type ``cmake --help-property-list``. +For a list of standard properties you can type +:option:`cmake --help-property-list`. See also the more general :command:`get_property` command. diff --git a/Help/command/if.rst b/Help/command/if.rst index 301cdce..b72769f 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -424,3 +424,10 @@ There is no automatic evaluation for environment or cache :ref:`Variable References`. Their values must be referenced as ``$ENV{<name>}`` or ``$CACHE{<name>}`` wherever the above-documented condition syntax accepts ``<variable|string>``. + +See also +^^^^^^^^ + + * :command:`else` + * :command:`elseif` + * :command:`endif` diff --git a/Help/command/install.rst b/Help/command/install.rst index 973aa31..feff436 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -132,7 +132,7 @@ Installing Targets install(TARGETS targets... [EXPORT <export-name>] [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>] [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| - PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>] + PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>|CXX_MODULES_BMI] [DESTINATION <dir>] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] @@ -215,11 +215,21 @@ that may be installed: ``/blah/include/myproj/here.h`` with a base directory ``/blah/include`` would be installed to ``myproj/here.h`` below the destination. +``CXX_MODULES_BMI`` + + .. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + + Any module files from C++ modules from ``PUBLIC`` sources in a file set of + type ``CXX_MODULES`` will be installed to the given ``DESTINATION``. All + modules are placed directly in the destination as no directory structure is + derived from the names of the modules. An empty ``DESTINATION`` may be used + to suppress installing these files (for use in generic code). + For each of these arguments given, the arguments following them only apply to the target or file type specified in the argument. If none is given, the -installation properties apply to all target types. If only one is given then -only targets of that type will be installed (which can be used to install -just a DLL or just an import library.) +installation properties apply to all target types. For regular executables, static libraries and shared libraries, the ``DESTINATION`` argument is not required. For these target types, when @@ -233,6 +243,14 @@ Apple bundles and frameworks. A destination can be omitted for interface and object libraries, but they are handled differently (see the discussion of this topic toward the end of this section). +For shared libraries on DLL platforms, if neither ``RUNTIME`` nor ``ARCHIVE`` +destinations are specified, both the ``RUNTIME`` and ``ARCHIVE`` components are +installed to their default destinations. If either a ``RUNTIME`` or ``ARCHIVE`` +destination is specified, the component is installed to that destination, and +the other component is not installed. If both ``RUNTIME`` and ``ARCHIVE`` +destinations are specified, then both components are installed to their +respective destinations. + The following table shows the target types with their associated variables and built-in defaults that apply when no destination is given: @@ -778,9 +796,10 @@ Installing Exports .. code-block:: cmake install(EXPORT <export-name> DESTINATION <dir> - [NAMESPACE <namespace>] [[FILE <name>.cmake]| + [NAMESPACE <namespace>] [FILE <name>.cmake] [PERMISSIONS permissions...] - [CONFIGURATIONS [Debug|Release|...]] + [CONFIGURATIONS [Debug|Release|...] + [CXX_MODULES_DIRECTORY <directory>] [EXPORT_LINK_INTERFACE_LIBRARIES] [COMPONENT <component>] [EXCLUDE_FROM_ALL]) @@ -836,6 +855,18 @@ library is always installed if the headers and CMake export file are present. to an ndk build system complete with transitive dependencies, include flags and defines required to use the libraries. +``CXX_MODULES_DIRECTORY`` + + .. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + + Specify a subdirectory to store C++ module information for targets in the + export set. This directory will be populated with files which add the + necessary target property information to the relevant targets. Note that + without this information, none of the C++ modules which are part of the + targets in the export set will support being imported in consuming targets. + The ``EXPORT`` form is useful to help outside projects use targets built and installed by the current project. For example, the code @@ -932,12 +963,12 @@ Generated Installation Script .. note:: Use of this feature is not recommended. Please consider using the - ``--install`` argument of :manual:`cmake(1)` instead. + :option:`cmake --install` instead. The ``install()`` command generates a file, ``cmake_install.cmake``, inside the build directory, which is used internally by the generated install target -and by CPack. You can also invoke this script manually with ``cmake -P``. This -script accepts several variables: +and by CPack. You can also invoke this script manually with +:option:`cmake -P`. This script accepts several variables: ``COMPONENT`` Set this variable to install only a single CPack component as opposed to all diff --git a/Help/command/message.rst b/Help/command/message.rst index ca4f5c1..77d21c8 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -83,8 +83,9 @@ are sent to stderr and are not prefixed with hyphens. The :manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area. 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. +interactive pop-up box. The :option:`--log-level <cmake --log-level>` +command-line option to each of these tools can be used to control which +messages will be shown. .. versionadded:: 3.17 To make a log level persist between CMake runs, the @@ -104,7 +105,7 @@ these tools can be used to control which messages will be shown. 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`` + enabled by giving the :option:`cmake --log-context` command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable to true. See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for usage examples. diff --git a/Help/command/return.rst b/Help/command/return.rst index ec009d8..029fd05 100644 --- a/Help/command/return.rst +++ b/Help/command/return.rst @@ -5,7 +5,7 @@ Return from a file, directory or function. .. code-block:: cmake - return() + return([PROPAGATE <var-name>...]) Returns from a file, directory or function. When this command is encountered in an included file (via :command:`include` or @@ -16,5 +16,39 @@ deferred calls scheduled by :command:`cmake_language(DEFER)` are invoked and control is returned to the parent directory if there is one. If return is called in a function, control is returned to the caller of the function. +``PROPAGATE`` + .. versionadded:: 3.25 + + This option set or unset the specified variables in the parent directory or + function caller scope. This is equivalent to :command:`set(PARENT_SCOPE)` or + :command:`unset(PARENT_SCOPE)` commands. + + The option ``PROPAGATE`` can be very useful in conjunction with the + :command:`block` command because the :command:`return` will cross over + various scopes created by the :command:`block` commands. + + .. code-block:: cmake + + function(MULTI_SCOPES RESULT_VARIABLE) + block(SCOPE_FOR VARIABLES) + # here set(PARENT_SCOPE) is not usable because it will not set the + # variable in the caller scope but in the parent scope of the block() + set(${RESULT_VARIABLE} "new-value") + return(PROPAGATE ${RESULT_VARIABLE}) + endblock() + endfunction() + + set(MY_VAR "initial-value") + multi_scopes(MY_VAR) + # here MY_VAR will holds "new-value" + +Policy :policy:`CMP0140` controls the behavior regarding the arguments of the +command. + Note that a :command:`macro <macro>`, unlike a :command:`function <function>`, is expanded in place and therefore cannot handle ``return()``. + +See Also +^^^^^^^^ + + * :command:`block` diff --git a/Help/command/set.rst b/Help/command/set.rst index af862e4..90b57d2 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -22,12 +22,17 @@ Set Normal Variable Sets the given ``<variable>`` in the current function or directory scope. If the ``PARENT_SCOPE`` option is given the variable will be set in -the scope above the current scope. Each new directory or function -creates a new scope. This command will set the value of a variable -into the parent directory or calling function (whichever is applicable -to the case at hand). The previous state of the variable's value stays the -same in the current scope (e.g., if it was undefined before, it is still -undefined and if it had a value, it is still that value). +the scope above the current scope. Each new directory or :command:`function` +command creates a new scope. A scope can also be created with the +:command:`block` command. This command will set the value of a variable into +the parent directory, calling function or encompassing scope (whichever is +applicable to the case at hand). The previous state of the variable's value +stays the same in the current scope (e.g., if it was undefined before, it is +still undefined and if it had a value, it is still that value). + +The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands can +be used as an alternate method to the :command:`set(PARENT_SCOPE)` and +:command:`unset(PARENT_SCOPE)` commands to update the parent scope. Set Cache Entry ^^^^^^^^^^^^^^^ @@ -78,7 +83,7 @@ option is given then the cache entry will be set to the given value. It is possible for the cache entry to exist prior to the call but have no type set if it was created on the :manual:`cmake(1)` command -line by a user through the ``-D<var>=<value>`` option without +line by a user through the :option:`-D\<var\>=\<value\> <cmake -D>` option without specifying a type. In this case the ``set`` command will add the type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH`` and the ``<value>`` provided on the command line is a relative path, diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index 3fb113a..2d292af 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -15,9 +15,9 @@ named ``<target>`` must have been created by a command such as :ref:`ALIAS target <Alias Targets>`. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to -specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` -items will populate the :prop_tgt:`COMPILE_DEFINITIONS` property of -``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +specify the :ref:`scope <Target Usage Requirements>` of the following arguments. +``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_DEFINITIONS` +property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``. The following arguments specify compile definitions. Repeated calls for the same ``<target>`` append items in the order called. diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index e45b209..0d86c91 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -22,9 +22,9 @@ If ``BEFORE`` is specified, the content will be prepended to the property instead of being appended. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to -specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` -items will populate the :prop_tgt:`COMPILE_OPTIONS` property of -``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +specify the :ref:`scope <Target Usage Requirements>` of the following arguments. +``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_OPTIONS` +property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``. The following arguments specify compile options. Repeated calls for the same ``<target>`` append items in the order called. diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 9a99a7d..f13ff29 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -18,9 +18,9 @@ By using ``AFTER`` or ``BEFORE`` explicitly, you can select between appending and prepending, independent of the default. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify -the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will -populate the :prop_tgt:`INCLUDE_DIRECTORIES` property of ``<target>``. -``PUBLIC`` and ``INTERFACE`` items will populate the +the :ref:`scope <Target Usage Requirements>` of the following arguments. +``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`INCLUDE_DIRECTORIES` +property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``. The following arguments specify include directories. diff --git a/Help/command/target_link_directories.rst b/Help/command/target_link_directories.rst index bb75a3d..b72f746 100644 --- a/Help/command/target_link_directories.rst +++ b/Help/command/target_link_directories.rst @@ -21,11 +21,12 @@ The named ``<target>`` must have been created by a command such as :ref:`ALIAS target <Alias Targets>`. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to -specify the scope of the items that follow them. ``PRIVATE`` and -``PUBLIC`` items will populate the :prop_tgt:`LINK_DIRECTORIES` property -of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_LINK_DIRECTORIES` property of ``<target>`` -(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items). +specify the :ref:`scope <Target Usage Requirements>` of the items that follow +them. ``PRIVATE`` and ``PUBLIC`` items will populate the +:prop_tgt:`LINK_DIRECTORIES` property of ``<target>``. ``PUBLIC`` and +``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_LINK_DIRECTORIES` +property of ``<target>`` (:ref:`IMPORTED targets <Imported Targets>` only +support ``INTERFACE`` items). Each item specifies a link directory and will be converted to an absolute path if necessary before adding it to the relevant property. Repeated calls for the same ``<target>`` append items in the order called. diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index c85094a..bb7b5cc 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -146,8 +146,10 @@ Libraries for a Target and/or its Dependents <PRIVATE|PUBLIC|INTERFACE> <item>... [<PRIVATE|PUBLIC|INTERFACE> <item>...]...) -The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to +The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` +:ref:`scope <Target Usage Requirements>` keywords can be used to specify both the link dependencies and the link interface in one command. + Libraries and targets following ``PUBLIC`` are linked to, and are made part of the link interface. Libraries and targets following ``PRIVATE`` are linked to, but are not made part of the link interface. Libraries diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst index 87dff39..3cd0e64 100644 --- a/Help/command/target_link_options.rst +++ b/Help/command/target_link_options.rst @@ -32,9 +32,9 @@ If ``BEFORE`` is specified, the content will be prepended to the property instead of being appended. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to -specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` -items will populate the :prop_tgt:`LINK_OPTIONS` property of -``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +specify the :ref:`scope <Target Usage Requirements>` of the following arguments. +``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`LINK_OPTIONS` +property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_LINK_OPTIONS` property of ``<target>``. The following arguments specify link options. Repeated calls for the same ``<target>`` append items in the order called. diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst index 9f7dabb..84f5d12 100644 --- a/Help/command/target_precompile_headers.rst +++ b/Help/command/target_precompile_headers.rst @@ -25,9 +25,9 @@ The named ``<target>`` must have been created by a command such as :ref:`ALIAS target <Alias Targets>`. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to -specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` -items will populate the :prop_tgt:`PRECOMPILE_HEADERS` property of -``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +specify the :ref:`scope <Target Usage Requirements>` of the following arguments. +``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`PRECOMPILE_HEADERS` +property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>`` (:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items). Repeated calls for the same ``<target>`` will append items in the order called. diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 72119f6..461175a 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -22,10 +22,10 @@ The named ``<target>`` must have been created by a command such as ``<target>`` can be a custom target. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to -specify the scope of the source file paths (``<items>``) that follow -them. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`SOURCES` -property of ``<target>``, which are used when building the target itself. -``PUBLIC`` and ``INTERFACE`` items will populate the +specify the :ref:`scope <Target Usage Requirements>` of the source file paths +(``<items>``) that follow them. ``PRIVATE`` and ``PUBLIC`` items will +populate the :prop_tgt:`SOURCES` property of ``<target>``, which are used when +building the target itself. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used when building dependents. A target created by :command:`add_custom_target` can only have ``PRIVATE`` scope. @@ -75,9 +75,33 @@ File Sets Adds a file set to a target, or adds files to an existing file set. Targets have zero or more named file sets. Each file set has a name, a type, a scope of ``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and -files within those directories. The only acceptable type is ``HEADERS``. The -optional default file sets are named after their type. The target may not be a -custom target or :prop_tgt:`FRAMEWORK` target. +files within those directories. The acceptable types include: + +``HEADERS`` + + Sources intended to be used via a language's ``#include`` mechanism. + +``CXX_MODULES`` + + .. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + + Sources which contain C++ interface module or partition units (i.e., those + using the ``export`` keyword). This file set type may not have an + ``INTERFACE`` scope except on ``IMPORTED`` targets. + +``CXX_MODULE_HEADER_UNITS`` + + .. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + + C++ header sources which may be imported by other C++ source code. This file + set type may not have an ``INTERFACE`` scope except on ``IMPORTED`` targets. + +The optional default file sets are named after their type. The target may not +be a custom target or :prop_tgt:`FRAMEWORK` target. Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets @@ -93,16 +117,17 @@ Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, o The name of the file set to create or add to. It must contain only letters, numbers and underscores. Names starting with a capital letter are reserved - for built-in file sets predefined by CMake. The only predefined set name is - ``HEADERS``. All other set names must not start with a capital letter or + for built-in file sets predefined by CMake. The only predefined set names + are those matching the acceptable types. All other set names must not start + with a capital letter or underscore. ``TYPE <type>`` - Every file set is associated with a particular type of file. ``HEADERS`` - is currently the only defined type and it is an error to specify anything - else. As a special case, if the name of the file set is ``HEADERS``, the - type does not need to be specified and the ``TYPE <type>`` arguments can be + Every file set is associated with a particular type of file. Only types + specified above may be used and it is an error to specify anything else. As + a special case, if the name of the file set is one of the types, the type + does not need to be specified and the ``TYPE <type>`` arguments can be omitted. For all other file set names, ``TYPE`` is required. ``BASE_DIRS <dirs>...`` @@ -134,6 +159,8 @@ Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, o The following target properties are set by ``target_sources(FILE_SET)``, but they should not generally be manipulated directly: +For file sets of type ``HEADERS``: + * :prop_tgt:`HEADER_SETS` * :prop_tgt:`INTERFACE_HEADER_SETS` * :prop_tgt:`HEADER_SET` @@ -141,17 +168,37 @@ but they should not generally be manipulated directly: * :prop_tgt:`HEADER_DIRS` * :prop_tgt:`HEADER_DIRS_<NAME>` +For file sets of type ``CXX_MODULES``: + +* :prop_tgt:`CXX_MODULE_SETS` +* :prop_tgt:`INTERFACE_CXX_MODULE_SETS` +* :prop_tgt:`CXX_MODULE_SET` +* :prop_tgt:`CXX_MODULE_SET_<NAME>` +* :prop_tgt:`CXX_MODULE_DIRS` +* :prop_tgt:`CXX_MODULE_DIRS_<NAME>` + +For file sets of type ``CXX_MODULE_HEADER_UNITS``: + +* :prop_tgt:`CXX_MODULE_HEADER_UNIT_SETS` +* :prop_tgt:`INTERFACE_CXX_MODULE_HEADER_UNIT_SETS` +* :prop_tgt:`CXX_MODULE_HEADER_UNIT_SET` +* :prop_tgt:`CXX_MODULE_HEADER_UNIT_SET_<NAME>` +* :prop_tgt:`CXX_MODULE_HEADER_UNIT_DIRS` +* :prop_tgt:`CXX_MODULE_HEADER_UNIT_DIRS_<NAME>` + Target properties related to include directories are also modified by ``target_sources(FILE_SET)`` as follows: :prop_tgt:`INCLUDE_DIRECTORIES` - If the ``TYPE`` is ``HEADERS``, and the scope of the file set is ``PRIVATE`` - or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are wrapped in - :genex:`$<BUILD_INTERFACE>` and appended to this property. + If the ``TYPE`` is ``HEADERS`` or ``CXX_MODULE_HEADER_UNITS``, and the scope + of the file set is ``PRIVATE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of + the file set are wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this + property. :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` - If the ``TYPE`` is ``HEADERS``, and the scope of the file set is - ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are - wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this property. + If the ``TYPE`` is ``HEADERS`` or ``CXX_MODULE_HEADER_UNITS``, and the scope + of the file set is ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of + the file set are wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this + property. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 806a98d..9e9f39f 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -14,10 +14,16 @@ Try Compiling Whole Projects .. code-block:: cmake - try_compile(<resultVar> <bindir> <srcdir> - <projectName> [<targetName>] [CMAKE_FLAGS <flags>...] + try_compile(<resultVar> PROJECT <projectName> + SOURCE_DIR <srcdir> + [BINARY_DIR <bindir>] + [TARGET <targetName>] + [NO_CACHE] + [CMAKE_FLAGS <flags>...] [OUTPUT_VARIABLE <var>]) +.. versionadded:: 3.25 + Try building a project. The success or failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``. @@ -34,6 +40,17 @@ below for the meaning of other options. Previously this was only done by the :ref:`source file <Try Compiling Source Files>` signature. +This command also supports an alternate signature +which was present in older versions of CMake: + +.. code-block:: cmake + + try_compile(<resultVar> <bindir> <srcdir> + <projectName> [<targetName>] + [NO_CACHE] + [CMAKE_FLAGS <flags>...] + [OUTPUT_VARIABLE <var>]) + .. _`Try Compiling Source Files`: Try Compiling Source Files @@ -41,7 +58,12 @@ Try Compiling Source Files .. code-block:: cmake - try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...> + try_compile(<resultVar> + <SOURCES <srcfile...> | + SOURCE_FROM_CONTENT <name> <content> | + SOURCE_FROM_VAR <name> <var> | + SOURCE_FROM_FILE <name> <path> >... + [NO_CACHE] [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] @@ -53,15 +75,19 @@ Try Compiling Source Files [<LANG>_EXTENSIONS <bool>] ) +.. versionadded:: 3.25 + Try building an executable or static library from one or more source files (which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable). The success or failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``. -In this form, one or more source files must be provided. If -:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``, -the sources must include a definition for ``main`` and CMake will create a -``CMakeLists.txt`` file to build the source(s) as an executable. +In this form, one or more source files must be provided. Additionally, one of +``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords. + +If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to +``EXECUTABLE``, the sources must include a definition for ``main`` and CMake +will create a ``CMakeLists.txt`` file to build the source(s) as an executable. If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``STATIC_LIBRARY``, a static library will be built instead and no definition for ``main`` is required. For an executable, the generated ``CMakeLists.txt`` file would @@ -76,11 +102,45 @@ contain something like the following: target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>) target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES}) +CMake automatically generates, for each ``try_compile`` operation, a +unique directory under ``${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch`` +with an unspecified name. These directories are cleaned automatically unless +:option:`--debug-trycompile <cmake --debug-trycompile>` is passed to ``cmake``. +Such directories from previous runs are also unconditionally cleaned at the +beginning of any ``cmake`` execution. + +This command also supports an alternate signature +which was present in older versions of CMake: + +.. code-block:: cmake + + try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...> + [NO_CACHE] + [CMAKE_FLAGS <flags>...] + [COMPILE_DEFINITIONS <defs>...] + [LINK_OPTIONS <options>...] + [LINK_LIBRARIES <libs>...] + [OUTPUT_VARIABLE <var>] + [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]] + [<LANG>_STANDARD <std>] + [<LANG>_STANDARD_REQUIRED <bool>] + [<LANG>_EXTENSIONS <bool>] + ) + +In this version, ``try_compile`` will use ``<bindir>/CMakeFiles/CMakeTmp`` for +its operation, and all such files will be cleaned automatically. +For debugging, :option:`--debug-trycompile <cmake --debug-trycompile>` can be +passed to ``cmake`` to avoid this clean. However, multiple sequential +``try_compile`` operations, if given the same ``<bindir>``, will reuse this +single output directory, such that you can only debug one such ``try_compile`` +call at a time. Use of the newer signature is recommended to simplify +debugging of multiple ``try_compile`` operations. + The options are: ``CMAKE_FLAGS <flags>...`` - Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to - the ``cmake`` command-line used to drive the test build. + Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed + to the :manual:`cmake(1)` command-line used to drive the test build. The above example shows how values for variables ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES`` are used. @@ -111,9 +171,61 @@ The options are: set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable. +``NO_CACHE`` + .. versionadded:: 3.25 + + The result will be stored in a normal variable rather than a cache entry. + + The result variable is normally cached so that a simple pattern can be used + to avoid repeating the test on subsequent executions of CMake: + + .. code-block:: cmake + + if(NOT DEFINED RESULTVAR) + # ...(check-specific setup code)... + try_compile(RESULTVAR ...) + # ...(check-specific logging and cleanup code)... + endif() + + If the guard variable and result variable are not the same (for example, if + the test is part of a larger inspection), ``NO_CACHE`` may be useful to avoid + leaking the intermediate result variable into the cache. + ``OUTPUT_VARIABLE <var>`` Store the output from the build process in the given variable. +``SOURCE_FROM_CONTENT <name> <content>`` + .. versionadded:: 3.25 + + Write ``<content>`` to a file named ``<name>`` in the operation directory. + This can be used to bypass the need to separately write a source file when + the contents of the file are dynamically specified. The specified ``<name>`` + is not allowed to contain path components. + + ``SOURCE_FROM_CONTENT`` may be specified multiple times. + +``SOURCE_FROM_FILE <name> <path>`` + .. versionadded:: 3.25 + + Copy ``<path>`` to a file named ``<name>`` in the operation directory. This + can be used to consolidate files into the operation directory, which may be + useful if a source which already exists (i.e. as a stand-alone file in a + project's source repository) needs to refer to other file(s) created by + ``SOURCE_FROM_*``. (Otherwise, ``SOURCES`` is usually more convenient.) The + specified ``<name>`` is not allowed to contain path components. + +``SOURCE_FROM_VAR <name> <var>`` + .. versionadded:: 3.25 + + Write the contents of ``<var>`` to a file named ``<name>`` in the operation + directory. This is the same as ``SOURCE_FROM_CONTENT``, but takes the + contents from the specified CMake variable, rather than directly, which may + be useful when passing arguments through a function which wraps + ``try_compile``. The specified ``<name>`` is not allowed to contain path + components. + + ``SOURCE_FROM_VAR`` may be specified multiple times. + ``<LANG>_STANDARD <std>`` .. versionadded:: 3.8 @@ -136,17 +248,6 @@ The options are: :prop_tgt:`OBJC_EXTENSIONS`, :prop_tgt:`OBJCXX_EXTENSIONS`, or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project. -In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be -cleaned automatically. For debugging, ``--debug-trycompile`` can be -passed to ``cmake`` to avoid this clean. However, multiple sequential -``try_compile`` operations reuse this single output directory. If you use -``--debug-trycompile``, you can only debug one ``try_compile`` call at a time. -The recommended procedure is to protect all ``try_compile`` calls in your -project by ``if(NOT DEFINED <resultVar>)`` logic, configure with cmake -all the way through once, then delete the cache entry associated with -the try_compile call of interest, and then re-run cmake again with -``--debug-trycompile``. - Other Behavior Settings ^^^^^^^^^^^^^^^^^^^^^^^ @@ -214,9 +315,15 @@ a build configuration. the generated project (unless overridden by an explicit option). .. versionchanged:: 3.14 - For the :generator:`Green Hills MULTI` generator the GHS toolset and target - system customization cache variables are also propagated into the test project. + For the :generator:`Green Hills MULTI` generator, the GHS toolset and target + system customization cache variables are also propagated into the test + project. .. versionadded:: 3.24 The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be set to disable passing platform variables into the test project. + +.. versionadded:: 3.25 + If :policy:`CMP0141` is set to ``NEW``, one can use + :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` to specify the MSVC debug + information format. diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index fc41cdd..cd41a4b 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -13,68 +13,99 @@ Try Compiling and Running Source Files .. code-block:: cmake try_run(<runResultVar> <compileResultVar> - <bindir> <srcfile> [CMAKE_FLAGS <flags>...] + <SOURCES <srcfile...> | + SOURCE_FROM_CONTENT <name> <content> | + SOURCE_FROM_VAR <name> <var> | + SOURCE_FROM_FILE <name> <path> >... + [NO_CACHE] + [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] [LINK_LIBRARIES <libs>...] [COMPILE_OUTPUT_VARIABLE <var>] + [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]] + [<LANG>_STANDARD <std>] + [<LANG>_STANDARD_REQUIRED <bool>] + [<LANG>_EXTENSIONS <bool>] [RUN_OUTPUT_VARIABLE <var>] + [RUN_OUTPUT_STDOUT_VARIABLE <var>] + [RUN_OUTPUT_STDERR_VARIABLE <var>] [OUTPUT_VARIABLE <var>] [WORKING_DIRECTORY <var>] - [ARGS <args>...]) + [ARGS <args>...] + ) + +.. versionadded:: 3.25 Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success or failure in ``<compileResultVar>``. If the compile succeeded, runs the executable and returns its exit code in ``<runResultVar>``. If the executable was built, but failed to run, then ``<runResultVar>`` will be set to ``FAILED_TO_RUN``. See the :command:`try_compile` command for -information on how the test project is constructed to build the source file. - -The options are: - -``CMAKE_FLAGS <flags>...`` - Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to - the ``cmake`` command-line used to drive the test build. - The example in :command:`try_compile` shows how values for variables - ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES`` - are used. +documentation of options common to both commands, and for information on how +the test project is constructed to build the source file. -``COMPILE_DEFINITIONS <defs>...`` - Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions` - in the generated test project. - -``COMPILE_OUTPUT_VARIABLE <var>`` - Report the compile step build output in a given variable. +One or more source files must be provided. Additionally, one of ``SOURCES`` +and/or ``SOURCE_FROM_*`` must precede other keywords. -``LINK_LIBRARIES <libs>...`` - .. versionadded:: 3.2 +This command also supports an alternate signature +which was present in older versions of CMake: - Specify libraries to be linked in the generated project. - The list of libraries may refer to system libraries and to - :ref:`Imported Targets <Imported Targets>` from the calling project. +.. code-block:: cmake - If this option is specified, any ``-DLINK_LIBRARIES=...`` value - given to the ``CMAKE_FLAGS`` option will be ignored. + try_run(<runResultVar> <compileResultVar> + <bindir> <srcfile|SOURCES srcfile...> + [NO_CACHE] + [CMAKE_FLAGS <flags>...] + [COMPILE_DEFINITIONS <defs>...] + [LINK_OPTIONS <options>...] + [LINK_LIBRARIES <libs>...] + [COMPILE_OUTPUT_VARIABLE <var>] + [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]] + [<LANG>_STANDARD <std>] + [<LANG>_STANDARD_REQUIRED <bool>] + [<LANG>_EXTENSIONS <bool>] + [RUN_OUTPUT_VARIABLE <var>] + [RUN_OUTPUT_STDOUT_VARIABLE <var>] + [RUN_OUTPUT_STDERR_VARIABLE <var>] + [OUTPUT_VARIABLE <var>] + [WORKING_DIRECTORY <var>] + [ARGS <args>...] + ) -``LINK_OPTIONS <options>...`` - .. versionadded:: 3.14 +The options specific to ``try_run`` are: - Specify link step options to pass to :command:`target_link_options` in the - generated project. +``COMPILE_OUTPUT_VARIABLE <var>`` + Report the compile step build output in a given variable. ``OUTPUT_VARIABLE <var>`` Report the compile build output and the output from running the executable - in the given variable. This option exists for legacy reasons. Prefer - ``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead. + in the given variable. This option exists for legacy reasons and is only + supported by the old ``try_run`` signature. + Prefer ``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead. ``RUN_OUTPUT_VARIABLE <var>`` Report the output from running the executable in a given variable. +``RUN_OUTPUT_STDOUT_VARIABLE <var>`` + .. versionadded:: 3.25 + + Report the output of stdout from running the executable in a given variable. + +``RUN_OUTPUT_STDERR_VARIABLE <var>`` + .. versionadded:: 3.25 + + Report the output of stderr from running the executable in a given variable. + ``WORKING_DIRECTORY <var>`` .. versionadded:: 3.20 Run the executable in the given directory. If no ``WORKING_DIRECTORY`` is - specified, the executable will run in ``<bindir>``. + specified, the executable will run in ``<bindir>`` or the current build + directory. + +``ARGS <args>...`` + Additional arguments to pass to the executable when running it. Other Behavior Settings ^^^^^^^^^^^^^^^^^^^^^^^ @@ -110,6 +141,7 @@ These cache entries are: In order to make cross compiling your project easier, use ``try_run`` only if really required. If you use ``try_run``, use the +``RUN_OUTPUT_STDOUT_VARIABLE``, ``RUN_OUTPUT_STDERR_VARIABLE``, ``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` options only if really required. Using them will require that when cross-compiling, the cache variables will have to be set manually to the output of the executable. diff --git a/Help/command/while.rst b/Help/command/while.rst index a4957c1..0bafae5 100644 --- a/Help/command/while.rst +++ b/Help/command/while.rst @@ -23,3 +23,11 @@ Per legacy, the :command:`endwhile` command admits an optional ``<condition>`` argument. If used, it must be a verbatim repeat of the argument of the opening ``while`` command. + +See Also +^^^^^^^^ + + * :command:`break` + * :command:`continue` + * :command:`foreach` + * :command:`endwhile` |