diff options
Diffstat (limited to 'Help/command')
26 files changed, 666 insertions, 187 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index dde4dbbbc..42bf52b08 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -79,17 +79,19 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_SYSTEM_PREFIX_PATH` -1. If called from within a find module loaded by +1. If called from within a find module or any other script loaded by a call to :command:`find_package(<PackageName>)`, search prefixes unique to the - current package being found. Specifically look in the + current package being found. Specifically, look in the :variable:`<PackageName>_ROOT` CMake variable and the :envvar:`<PackageName>_ROOT` environment variable. - The package root variables are maintained as a stack so if called from - nested find modules, root paths from the parent's find module will be - searched after paths from the current module, - i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, + The package root variables are maintained as a stack, so if called from + nested find modules or config packages, root paths from the parent's find + module or config package will be searched after paths from the current + module or package. In other words, the search order would be + ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc. - This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. See policy :policy:`CMP0074`. * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| @@ -97,7 +99,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: 2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`. - This can be skipped if ``NO_CMAKE_PATH`` is passed. + This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``. * |CMAKE_PREFIX_PATH_XXX| * |CMAKE_XXX_PATH| @@ -107,7 +110,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: These are intended to be set in the user's shell configuration, and therefore use the host's native path separator (``;`` on Windows and ``:`` on UNIX). - This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed. + This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or + by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``. * |CMAKE_PREFIX_PATH_XXX| * |CMAKE_XXX_PATH| @@ -119,13 +123,16 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: Hard-coded guesses should be specified with the ``PATHS`` option. 5. Search the standard system environment variables. - This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument. + This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by + setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. * |SYSTEM_ENVIRONMENT_PATH_XXX| + * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| 6. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` - is passed. + is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` + to ``FALSE``. * |CMAKE_SYSTEM_PREFIX_PATH_XXX| * |CMAKE_SYSTEM_XXX_PATH| diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt index a72337515..3f66181be 100644 --- a/Help/command/LINK_OPTIONS_LINKER.txt +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -1,8 +1,8 @@ -To pass options to the linker tool, each compiler driver has is own syntax. -The ``LINKER:`` prefix can be used to specify, in a portable way, options -to pass to the linker tool. The ``LINKER:`` prefix is replaced by the required -driver option and the rest of the option string defines linker arguments using -``,`` as separator. These arguments will be formatted according to the +To pass options to the linker tool, each compiler driver has its own syntax. +The ``LINKER:`` prefix and ``,`` separator can be used to specify, in a portable +way, options to pass to the linker tool. ``LINKER:`` is replaced by the +appropriate driver option and ``,`` by the appropriate driver separator. +The driver prefix and driver separator are given by the values of the :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` and :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variables. @@ -12,11 +12,11 @@ For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for The ``LINKER:`` prefix can be specified as part of a ``SHELL:`` prefix expression. -The ``LINKER:`` prefix supports, as alternate syntax, specification of -arguments using ``SHELL:`` prefix and space as separator. Previous example -becomes ``"LINKER:SHELL:-z defs"``. +The ``LINKER:`` prefix supports, as an alternative syntax, specification of +arguments using the ``SHELL:`` prefix and space as separator. The previous +example then becomes ``"LINKER:SHELL:-z defs"``. .. note:: - Specifying ``SHELL:`` prefix elsewhere than at the beginning of the + Specifying the ``SHELL:`` prefix anywhere other than at the beginning of the ``LINKER:`` prefix is not supported. diff --git a/Help/command/OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index 530c0126f..0f8ec323c 100644 --- a/Help/command/OPTIONS_SHELL.txt +++ b/Help/command/OPTIONS_SHELL.txt @@ -1,9 +1,9 @@ The final set of compile or link options used for a target is constructed by accumulating options from the current target and the usage requirements of -it dependencies. The set of options is de-duplicated to avoid repetition. +its dependencies. The set of options is de-duplicated to avoid repetition. While beneficial for individual options, the de-duplication step can break up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may specify a group of options using shell-like quoting along with a ``SHELL:`` -prefix. The ``SHELL:`` prefix is dropped and the rest of the option string +prefix. The ``SHELL:`` prefix is dropped, and the rest of the option string is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index ed321fcef..aba374261 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -68,9 +68,6 @@ The options are: order-only dependencies to ensure the byproducts will be available before their dependents build. - The ``BYPRODUCTS`` option is ignored on non-Ninja generators - except to mark byproducts ``GENERATED``. - ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, @@ -82,25 +79,33 @@ The options are: will be ignored. If ``COMMAND`` specifies an executable target name (created by the - :command:`add_executable` command) it will automatically be replaced - by the location of the executable created at build time. If set, the - :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will - also be prepended to the command to allow the executable to run on - the host. - (Use the ``TARGET_FILE`` - :manual:`generator expression <cmake-generator-expressions(7)>` to - reference an executable later in the command line.) - Additionally a target-level dependency will be added so that the - executable target will be built before any target using this custom - command. However this does NOT add a file-level dependency that - would cause the custom command to re-run whenever the executable is - recompiled. + :command:`add_executable` command), it will automatically be replaced + by the location of the executable created at build time if either of + the following is true: + + * The target is not being cross-compiled (i.e. the + :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). + * The target is being cross-compiled and an emulator is provided (i.e. + its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). + In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be + prepended to the command before the location of the target executable. + + If neither of the above conditions are met, it is assumed that the + command name is a program to be found on the ``PATH`` at build time. Arguments to ``COMMAND`` may use :manual:`generator expressions <cmake-generator-expressions(7)>`. - References to target names in generator expressions imply target-level - dependencies, but NOT file-level dependencies. List target names with - the ``DEPENDS`` option to add file-level dependencies. + Use the ``TARGET_FILE`` generator expression to refer to the location of + a target later in the command line (i.e. as a command argument rather + than as the command to execute). + + Whenever a target is used as a command to execute or is mentioned in a + generator expression as a command argument, a target-level dependency + will be added automatically so that the mentioned target will be built + before any target using this custom command. However this does NOT add + a file-level dependency that would cause the custom command to re-run + whenever the executable is recompiled. List target names with + the ``DEPENDS`` option to add such file-level dependencies. ``COMMENT`` Display the given message before the commands are executed at @@ -111,6 +116,9 @@ The options are: an ``OUTPUT`` of another custom command in the same directory (``CMakeLists.txt`` file) CMake automatically brings the other custom command into the target in which this command is built. + A target-level dependency is added if any dependency is listed as + ``BYPRODUCTS`` of a target or any of its build events in the same + directory to ensure the byproducts will be available. If ``DEPENDS`` is not specified the command will run whenever the ``OUTPUT`` is missing; if the command does not actually create the ``OUTPUT`` then the rule will always run. @@ -219,7 +227,8 @@ target is already built, the command will not execute. [BYPRODUCTS [files...]] [WORKING_DIRECTORY dir] [COMMENT comment] - [VERBATIM] [USES_TERMINAL]) + [VERBATIM] [USES_TERMINAL] + [COMMAND_EXPAND_LISTS]) This defines a new command that will be associated with building the specified ``<target>``. The ``<target>`` must be defined in the current diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 08b95168b..2d5f5f081 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -49,9 +49,6 @@ The options are: order-only dependencies to ensure the byproducts will be available before their dependents build. - The ``BYPRODUCTS`` option is ignored on non-Ninja generators - except to mark byproducts ``GENERATED``. - ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, @@ -61,18 +58,30 @@ The options are: a ``COMMAND`` to launch it.) If ``COMMAND`` specifies an executable target name (created by the - :command:`add_executable` command) it will automatically be replaced - by the location of the executable created at build time. If set, the - :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will - also be prepended to the command to allow the executable to run on - the host. - Additionally a target-level dependency will be added so that the - executable target will be built before this custom target. + :command:`add_executable` command), it will automatically be replaced + by the location of the executable created at build time if either of + the following is true: + + * The target is not being cross-compiled (i.e. the + :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). + * The target is being cross-compiled and an emulator is provided (i.e. + its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). + In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be + prepended to the command before the location of the target executable. + + If neither of the above conditions are met, it is assumed that the + command name is a program to be found on the ``PATH`` at build time. Arguments to ``COMMAND`` may use :manual:`generator expressions <cmake-generator-expressions(7)>`. - References to target names in generator expressions imply target-level - dependencies. + Use the ``TARGET_FILE`` generator expression to refer to the location of + a target later in the command line (i.e. as a command argument rather + than as the command to execute). + + Whenever a target is used as a command to execute or is mentioned in a + generator expression as a command argument, a target-level dependency + will be added automatically so that the mentioned target will be built + before this custom target. The command and arguments are optional and if not specified an empty target will be created. @@ -86,6 +95,9 @@ The options are: :command:`add_custom_command` command calls in the same directory (``CMakeLists.txt`` file). They will be brought up to date when the target is built. + A target-level dependency is added if any dependency is a byproduct + of a target or any of its build events in the same directory to ensure + the byproducts will be available before this target is built. Use the :command:`add_dependencies` command to add dependencies on other targets. diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index 46b9b63c5..a77ba37cc 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -7,7 +7,8 @@ Add a test to the project to be run by :manual:`ctest(1)`. add_test(NAME <name> COMMAND <command> [<arg>...] [CONFIGURATIONS <config>...] - [WORKING_DIRECTORY <dir>]) + [WORKING_DIRECTORY <dir>] + [COMMAND_EXPAND_LISTS]) Adds a test called ``<name>``. The test name may not contain spaces, quotes, or other characters special in CMake syntax. The options are: @@ -28,12 +29,18 @@ quotes, or other characters special in CMake syntax. The options are: directory set to the build directory corresponding to the current source directory. +``COMMAND_EXPAND_LISTS`` + Lists in ``COMMAND`` arguments will be expanded, including those + created with + :manual:`generator expressions <cmake-generator-expressions(7)>`. + The given test command is expected to exit with code ``0`` to pass and non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test property is set. Any output written to stdout or stderr will be captured by :manual:`ctest(1)` but does not affect the pass/fail status -unless the :prop_test:`PASS_REGULAR_EXPRESSION` or -:prop_test:`FAIL_REGULAR_EXPRESSION` test property is used. +unless the :prop_test:`PASS_REGULAR_EXPRESSION`, +:prop_test:`FAIL_REGULAR_EXPRESSION` or +:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used. The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator expressions" with the syntax ``$<...>``. See the diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst index 8d27b9c1b..d50f63498 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst @@ -8,7 +8,7 @@ Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`. ctest_coverage([BUILD <build-dir>] [APPEND] [LABELS <label>...] [RETURN_VALUE <result-var>] - [CAPTURE_CMAKE_ERROR <result-var] + [CAPTURE_CMAKE_ERROR <result-var>] [QUIET] ) diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index 6db9a485a..f0704aca5 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -5,9 +5,9 @@ Starts the testing for a given model :: - ctest_start(<model> [<source> [<binary>]] [TRACK <track>] [QUIET]) + ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET]) - ctest_start([<model> [<source> [<binary>]]] [TRACK <track>] APPEND [QUIET]) + ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET]) Starts the testing for a given model. The command should be called after the binary directory is initialized. @@ -26,20 +26,21 @@ The parameters are as follows: Set the binary directory. If not specified, the value of :variable:`CTEST_BINARY_DIRECTORY` is used instead. -``TRACK <track>`` - If ``TRACK`` is used, the submissions will go to the specified track on the - CDash server. If no ``TRACK`` is specified, the name of the model is used by - default. +``GROUP <group>`` + If ``GROUP`` is used, the submissions will go to the specified group on the + CDash server. If no ``GROUP`` is specified, the name of the model is used by + default. This replaces the deprecated option ``TRACK``. Despite the name + change its behavior is unchanged. ``APPEND`` If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new one based on the current time stamp. If you use ``APPEND``, you can omit the - ``<model>`` and ``TRACK <track>`` parameters, because they will be read from + ``<model>`` and ``GROUP <group>`` parameters, because they will be read from the generated ``TAG`` file. For example: .. code-block:: cmake - ctest_start(Experimental TRACK TrackExperimental) + ctest_start(Experimental GROUP GroupExperimental) Later, in another ``ctest -S`` script: @@ -48,11 +49,11 @@ The parameters are as follows: ctest_start(APPEND) When the second script runs ``ctest_start(APPEND)``, it will read the - ``Experimental`` model and ``TrackExperimental`` track from the ``TAG`` file + ``Experimental`` model and ``GroupExperimental`` group from the ``TAG`` file generated by the first ``ctest_start()`` command. Please note that if you - call ``ctest_start(APPEND)`` and specify a different model or track than + call ``ctest_start(APPEND)`` and specify a different model or group than in the first ``ctest_start()`` command, a warning will be issued, and the - new model and track will be used. + new model and group will be used. ``QUIET`` If ``QUIET`` is used, CTest will suppress any non-error messages that it @@ -65,11 +66,11 @@ equivalent: .. code-block:: cmake - ctest_start(Experimental path/to/source path/to/binary TRACK SomeTrack QUIET APPEND) + ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND) - ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary) + ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary) - ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack path/to/binary) + ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary) However, for the sake of readability, it is recommended that you order your parameters in the order listed at the top of this page. diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 4a69491d5..7a3393b4d 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -17,6 +17,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. [EXCLUDE_FIXTURE_SETUP <regex>] [EXCLUDE_FIXTURE_CLEANUP <regex>] [PARALLEL_LEVEL <level>] + [RESOURCE_SPEC_FILE <file>] [TEST_LOAD <threshold>] [SCHEDULE_RANDOM <ON|OFF>] [STOP_TIME <time-of-day>] @@ -82,6 +83,11 @@ The options are: Specify a positive number representing the number of tests to be run in parallel. +``RESOURCE_SPEC_FILE <file>`` + Specify a + :ref:`resource specification file <ctest-resource-specification-file>`. See + :ref:`ctest-resource-allocation` for more information. + ``TEST_LOAD <threshold>`` 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 diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index fb49b4432..fdc44f2bc 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -1,7 +1,6 @@ enable_language --------------- - -Enable a language (CXX/C/Fortran/etc) +Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc) .. code-block:: cmake @@ -10,7 +9,7 @@ Enable a language (CXX/C/Fortran/etc) 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 variables that are created by the project command. Example languages -are ``CXX``, ``C``, ``CUDA``, ``Fortran``, and ``ASM``. +are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, and ``ASM``. If enabling ``ASM``, enable it last so that CMake can check whether compilers for other languages like ``C`` work for assembly too. diff --git a/Help/command/file.rst b/Help/command/file.rst index f99021ef6..b186177eb 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -13,6 +13,7 @@ Synopsis file(`STRINGS`_ <filename> <out-var> [...]) file(`\<HASH\> <HASH_>`_ <filename> <out-var>) file(`TIMESTAMP`_ <filename> <out-var> [...]) + file(`GET_RUNTIME_DEPENDENCIES`_ [...]) `Writing`_ file({`WRITE`_ | `APPEND`_} <filename> <content>...) @@ -130,6 +131,273 @@ timestamp variable will be set to the empty string (""). See the :command:`string(TIMESTAMP)` command for documentation of the ``<format>`` and ``UTC`` options. +.. _GET_RUNTIME_DEPENDENCIES: + +.. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + [RESOLVED_DEPENDENCIES_VAR <deps_var>] + [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>] + [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>] + [EXECUTABLES [<executable_files>...]] + [LIBRARIES [<library_files>...]] + [MODULES [<module_files>...]] + [DIRECTORIES [<directories>...]] + [BUNDLE_EXECUTABLE <bundle_executable_file>] + [PRE_INCLUDE_REGEXES [<regexes>...]] + [PRE_EXCLUDE_REGEXES [<regexes>...]] + [POST_INCLUDE_REGEXES [<regexes>...]] + [POST_EXCLUDE_REGEXES [<regexes>...]] + ) + +Recursively get the list of libraries depended on by the given files. + +Please note that this sub-command is not intended to be used in project mode. +Instead, use it in an :command:`install(CODE)` or :command:`install(SCRIPT)` +block. For example: + +.. code-block:: cmake + + install(CODE [[ + file(GET_RUNTIME_DEPENDENCIES + # ... + ) + ]]) + +The arguments are as follows: + +``RESOLVED_DEPENDENCIES_VAR <deps_var>`` + Name of the variable in which to store the list of resolved dependencies. + +``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>`` + Name of the variable in which to store the list of unresolved dependencies. + If this variable is not specified, and there are any unresolved dependencies, + an error is issued. + +``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>`` + Variable prefix in which to store conflicting dependency information. + Dependencies are conflicting if two files with the same name are found in + two different directories. The list of filenames that conflict are stored in + ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list of paths + that were found for that filename are stored in + ``<conflicting_deps_prefix>_<filename>``. + +``EXECUTABLES <executable_files>`` + List of executable files to read for dependencies. These are executables that + are typically created with :command:`add_executable`, but they do not have to + be created by CMake. On Apple platforms, the paths to these files determine + the value of ``@executable_path`` when recursively resolving the libraries. + Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here + will result in undefined behavior. + +``LIBRARIES <library_files>`` + List of library files to read for dependencies. These are libraries that are + typically created with :command:`add_library(SHARED)`, but they do not have + to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` + libraries, or executables here will result in undefined behavior. + +``MODULES <module_files>`` + List of loadable module files to read for dependencies. These are modules + that are typically created with :command:`add_library(MODULE)`, but they do + not have to be created by CMake. They are typically used by calling + ``dlopen()`` at runtime rather than linked at link time with ``ld -l``. + Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables here + will result in undefined behavior. + +``DIRECTORIES <directories>`` + List of additional directories to search for dependencies. On Linux + platforms, these directories are searched if the dependency is not found in + any of the other usual paths. If it is found in such a directory, a warning + is issued, because it means that the file is incomplete (it does not list all + of the directories that contain its dependencies). On Windows platforms, + these directories are searched if the dependency is not found in any of the + other search paths, but no warning is issued, because searching other paths + is a normal part of Windows dependency resolution. On Apple platforms, this + argument has no effect. + +``BUNDLE_EXECUTABLE <bundle_executable_file>`` + Executable to treat as the "bundle executable" when resolving libraries. On + Apple platforms, this argument determines the value of ``@executable_path`` + when recursively resolving libraries for ``LIBRARIES`` and ``MODULES`` files. + It has no effect on ``EXECUTABLES`` files. On other platforms, it has no + effect. This is typically (but not always) one of the executables in the + ``EXECUTABLES`` argument which designates the "main" executable of the + package. + +The following arguments specify filters for including or excluding libraries to +be resolved. See below for a full description of how they work. + +``PRE_INCLUDE_REGEXES <regexes>`` + List of pre-include regexes through which to filter the names of + not-yet-resolved dependencies. + +``PRE_EXCLUDE_REGEXES <regexes>`` + List of pre-exclude regexes through which to filter the names of + not-yet-resolved dependencies. + +``POST_INCLUDE_REGEXES <regexes>`` + List of post-include regexes through which to filter the names of resolved + dependencies. + +``POST_EXCLUDE_REGEXES <regexes>`` + List of post-exclude regexes through which to filter the names of resolved + dependencies. + +These arguments can be used to blacklist unwanted system libraries when +resolving the dependencies, or to whitelist libraries from a specific +directory. The filtering works as follows: + +1. If the not-yet-resolved dependency matches any of the + ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency + resolution proceeds to step 4. +2. If the not-yet-resolved dependency matches any of the + ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency. +3. Otherwise, dependency resolution proceeds. +4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to + the linking rules of the platform (see below). +5. If the dependency is found, and its full path matches one of the + ``POST_INCLUDE_REGEXES``, the full path is added to the resolved + dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves + that library's own dependencies. Otherwise, resolution proceeds to step 6. +6. If the dependency is found, but its full path matches one of the + ``POST_EXCLUDE_REGEXES``, it is not added to the resolved dependencies, and + dependency resolution stops for that dependency. +7. If the dependency is found, and its full path does not match either + ``POST_INCLUDE_REGEXES`` or ``POST_EXCLUDE_REGEXES``, the full path is added + to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` + recursively resolves that library's own dependencies. + +Different platforms have different rules for how dependencies are resolved. +These specifics are described here. + +On Linux platforms, library resolution works as follows: + +1. If the depending file does not have any ``RUNPATH`` entries, and the library + exists in one of the depending file's ``RPATH`` entries, or its parents', in + that order, the dependency is resolved to that file. +2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the + library exists in one of those entries, the dependency is resolved to that + file. +3. Otherwise, if the library exists in one of the directories listed by + ``ldconfig``, the dependency is resolved to that file. +4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, the + dependency is resolved to that file. In this case, a warning is issued, + because finding a file in one of the ``DIRECTORIES`` means that the + depending file is not complete (it does not list all the directories from + which it pulls dependencies). +5. Otherwise, the dependency is unresolved. + +On Windows platforms, library resolution works as follows: + +1. The dependent DLL name is converted to lowercase. Windows DLL names are + case-insensitive, and some linkers mangle the case of the DLL dependency + names. However, this makes it more difficult for ``PRE_INCLUDE_REGEXES``, + ``PRE_EXCLUDE_REGEXES``, ``POST_INCLUDE_REGEXES``, and + ``POST_EXCLUDE_REGEXES`` to properly filter DLL names - every regex would + have to check for both uppercase and lowercase letters. For example: + + .. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$" + ) + + Converting the DLL name to lowercase allows the regexes to only match + lowercase names, thus simplifying the regex. For example: + + .. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^mylibrary\\.dll$" + ) + + This regex will match ``mylibrary.dll`` regardless of how it is cased, + either on disk or in the depending file. (For example, it will match + ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.) + + Please note that the directory portion of any resolved DLLs retains its + casing and is not converted to lowercase. Only the filename portion is + converted. + +2. (**Not yet implemented**) If the depending file is a Windows Store app, and + the dependency is listed as a dependency in the application's package + manifest, the dependency is resolved to that file. +3. Otherwise, if the library exists in the same directory as the depending + file, the dependency is resolved to that file. +4. Otherwise, if the library exists in either the operating system's + ``system32`` directory or the ``Windows`` directory, in that order, the + dependency is resolved to that file. +5. Otherwise, if the library exists in one of the directories specified by + ``DIRECTORIES``, in the order they are listed, the dependency is resolved to + that file. In this case, a warning is not issued, because searching other + directories is a normal part of Windows library resolution. +6. Otherwise, the dependency is unresolved. + +On Apple platforms, library resolution works as follows: + +1. If the dependency starts with ``@executable_path/``, and an ``EXECUTABLES`` + argument is in the process of being resolved, and replacing + ``@executable_path/`` with the directory of the executable yields an + existing file, the dependency is resolved to that file. +2. Otherwise, if the dependency starts with ``@executable_path/``, and there is + a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` with + the directory of the bundle executable yields an existing file, the + dependency is resolved to that file. +3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing + ``@loader_path/`` with the directory of the depending file yields an + existing file, the dependency is resolved to that file. +4. Otherwise, if the dependency starts with ``@rpath/``, and replacing + ``@rpath/`` with one of the ``RPATH`` entries of the depending file yields + an existing file, the dependency is resolved to that file. Note that + ``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/`` + also have these items replaced with the appropriate path. +5. Otherwise, if the dependency is an absolute file that exists, the dependency + is resolved to that file. +6. Otherwise, the dependency is unresolved. + +This function accepts several variables that determine which tool is used for +dependency resolution: + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM + + Determines which operating system and executable format the files are built + for. This could be one of several values: + + * ``linux+elf`` + * ``windows+pe`` + * ``macos+macho`` + + If this variable is not specified, it is determined automatically by system + introspection. + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL + + Determines the tool to use for dependency resolution. It could be one of + several values, depending on the value of + :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`: + + ================================================= ============================================= + ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL`` + ================================================= ============================================= + ``linux+elf`` ``objdump`` + ``windows+pe`` ``dumpbin`` + ``windows+pe`` ``objdump`` + ``macos+macho`` ``otool`` + ================================================= ============================================= + + If this variable is not specified, it is determined automatically by system + introspection. + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND + + Determines the path to the tool to use for dependency resolution. This is the + actual path to ``objdump``, ``dumpbin``, or ``otool``. + + If this variable is not specified, it is determined automatically by system + introspection. + Writing ^^^^^^^ @@ -235,6 +503,11 @@ regular expressions, but much simpler. If ``RELATIVE`` flag is specified, the results will be returned as relative paths to the given path. The results will be ordered lexicographically. +On Windows and macOS, globbing is case-insensitive even if the underlying +filesystem is case-sensitive (both filenames and globbing expressions are +converted to lowercase before matching). On other platforms, globbing is +case-sensitive. + If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic to the main build system check target to rerun the flagged ``GLOB`` commands at build time. If any of the outputs change, CMake will regenerate the build diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index 2a14ad72f..3f03f37e3 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -17,11 +17,10 @@ find_file .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``. - On Windows hosts: - ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` - is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the - directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index 0861d6789..8a55aca3d 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -17,11 +17,10 @@ find_library .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``LIB``. - On Windows hosts: - ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, - and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, - and the directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: + ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index e5e5b2cf6..64a16f321 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -81,6 +81,7 @@ The complete Config mode command signature is find_package(<PackageName> [version] [EXACT] [QUIET] [REQUIRED] [[COMPONENTS] [components...]] + [OPTIONAL_COMPONENTS components...] [CONFIG|NO_MODULE] [NO_POLICY_SCOPE] [NAMES name1 [name2 ...]] @@ -293,13 +294,15 @@ enabled. The package root variables are maintained as a stack so if called from within a find module, root paths from the parent's find module will also be searched after paths for the current package. - This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. 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``. The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`. - This can be skipped if ``NO_CMAKE_PATH`` is passed:: + This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``:: CMAKE_PREFIX_PATH CMAKE_FRAMEWORK_PATH @@ -309,7 +312,8 @@ enabled. These are intended to be set in the user's shell configuration, and therefore use the host's native path separator (``;`` on Windows and ``:`` on UNIX). - This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed:: + This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``:: <PackageName>_DIR CMAKE_PREFIX_PATH @@ -322,7 +326,8 @@ enabled. be specified with the ``PATHS`` option. 5. Search the standard system environment variables. This can be - skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed. Path entries + skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. Path entries ending in ``/bin`` or ``/sbin`` are automatically converted to their parent directories:: @@ -330,14 +335,17 @@ enabled. 6. Search paths stored in the CMake :ref:`User Package Registry`. This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by - setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` - to ``TRUE``. + setting the variable :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` + to ``FALSE`` or the deprecated variable + :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` to ``TRUE``. + See the :manual:`cmake-packages(7)` manual for details on the user package registry. 7. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is - passed:: + passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` + to ``FALSE``:: CMAKE_SYSTEM_PREFIX_PATH CMAKE_SYSTEM_FRAMEWORK_PATH @@ -345,8 +353,10 @@ enabled. 8. Search paths stored in the CMake :ref:`System Package Registry`. This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed - or by setting the + or by setting the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` + variable to ``FALSE`` or the deprecated variable :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``. + See the :manual:`cmake-packages(7)` manual for details on the system package registry. diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index 988a3fae4..52ffe3c79 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -17,11 +17,10 @@ find_path .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``. - On Windows hosts: - ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` - is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the - directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index 4f00773b3..e2ff69342 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -15,7 +15,8 @@ find_program .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_APPBUNDLE_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: ``PATH`` +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts no extra search paths are included .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/if.rst b/Help/command/if.rst index d8e3a45da..be992df15 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -29,6 +29,8 @@ If used, it must be a verbatim repeat of the argument of the opening ``if`` command. +.. _`Condition Syntax`: + Condition Syntax ^^^^^^^^^^^^^^^^ diff --git a/Help/command/install.rst b/Help/command/install.rst index ab6fef664..5affc5b99 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -126,6 +126,8 @@ project. There are several kinds of target files that may be installed: marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK`` below.) For DLL platforms (all Windows-based systems including Cygwin), the DLL import library is treated as an ``ARCHIVE`` target. + On AIX, the linker import file created for executables with + :prop_tgt:`ENABLE_EXPORTS` is treated as an ``ARCHIVE`` target. ``LIBRARY`` Module libraries are always treated as ``LIBRARY`` targets. For non- diff --git a/Help/command/list.rst b/Help/command/list.rst index 39e7e2a69..50bf417bf 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -180,7 +180,7 @@ Insert elements to the 0th position in the list. list(REMOVE_ITEM <list> <value> [<value> ...]) -Removes the given items from the list. +Removes all instances of the given items from the list. .. _REMOVE_AT: diff --git a/Help/command/load_cache.rst b/Help/command/load_cache.rst index 33625c463..b89eb6177 100644 --- a/Help/command/load_cache.rst +++ b/Help/command/load_cache.rst @@ -5,7 +5,7 @@ Load in the values from another project's CMake cache. .. code-block:: cmake - load_cache(pathToCacheFile READ_WITH_PREFIX prefix entry1...) + load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...) Reads the cache and store the requested entries in variables with their name prefixed with the given prefix. This only reads the values, and @@ -13,7 +13,7 @@ does not create entries in the local project's cache. .. code-block:: cmake - load_cache(pathToCacheFile [EXCLUDE entry1...] + load_cache(pathToBuildDirectory [EXCLUDE entry1...] [INCLUDE_INTERNALS entry1...]) Loads in the values from another cache and store them in the local diff --git a/Help/command/math.rst b/Help/command/math.rst index 3cbe719e5..ddb1ec63c 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -8,7 +8,8 @@ Evaluate a mathematical expression. math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>]) Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the -resulting value. +resulting value. The result of the expression must be representable as a +64-bit signed integer. The mathematical expression must be given as a string (i.e. enclosed in double quotation marks). An example is ``"5 * (10 + 13)"``. diff --git a/Help/command/message.rst b/Help/command/message.rst index 5dca6b417..c614286c1 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -57,9 +57,14 @@ 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 ``--loglevel`` command-line option to each of +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. +Messages of log levels ``NOTICE`` and below will also have each line preceded +by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to +a single string by concatenating its list items). For ``STATUS`` to ``TRACE`` +messages, this indenting content will be inserted after the hyphens. + CMake Warning and Error message text displays using a simple markup language. Non-indented text is formatted in line-wrapped paragraphs delimited by newlines. Indented text is considered pre-formatted. diff --git a/Help/command/project.rst b/Help/command/project.rst index baf18be64..395145619 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -87,7 +87,8 @@ The options are: Can also be specified without ``LANGUAGES`` keyword per the first, short signature. Selects which programming languages are needed to build the project. - Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, ``Fortran``, and ``ASM``. + Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, + ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, and ``ASM``. By default ``C`` and ``CXX`` are enabled if no language options are given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, to skip enabling any languages. diff --git a/Help/command/string.rst b/Help/command/string.rst index 2e89d7b9e..81a206112 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -22,8 +22,8 @@ Synopsis string(`PREPEND`_ <string-var> [<input>...]) string(`CONCAT`_ <out-var> [<input>...]) string(`JOIN`_ <glue> <out-var> [<input>...]) - string(`TOLOWER`_ <string1> <out-var>) - string(`TOUPPER`_ <string1> <out-var>) + string(`TOLOWER`_ <string> <out-var>) + string(`TOUPPER`_ <string> <out-var>) string(`LENGTH`_ <string> <out-var>) string(`SUBSTRING`_ <string> <begin> <length> <out-var>) string(`STRIP`_ <string> <out-var>) @@ -38,7 +38,7 @@ Synopsis `Generation`_ string(`ASCII`_ <number>... <out-var>) - string(`CONFIGURE`_ <string1> <out-var> [...]) + string(`CONFIGURE`_ <string> <out-var> [...]) string(`MAKE_C_IDENTIFIER`_ <string> <out-var>) string(`RANDOM`_ [<option>...] <out-var>) string(`TIMESTAMP`_ <out-var> [<format string>] [UTC]) @@ -51,23 +51,28 @@ Search and Replace .. code-block:: cmake - string(FIND <string> <substring> <output variable> [REVERSE]) + string(FIND <string> <substring> <output_variable> [REVERSE]) -Return the position where the given substring was found in -the supplied string. If the ``REVERSE`` flag was used, the command will +Return the position where the given ``<substring>`` was found in +the supplied ``<string>``. If the ``REVERSE`` flag was used, the command will search for the position of the last occurrence of the specified -substring. If the substring is not found, a position of -1 is returned. +``<substring>``. If the ``<substring>`` is not found, a position of -1 is +returned. + +The ``string(FIND)`` subcommand treats all strings as ASCII-only characters. +The index stored in ``<output_variable>`` will also be counted in bytes, +so strings containing multi-byte characters may lead to unexpected results. .. _REPLACE: .. code-block:: cmake string(REPLACE <match_string> - <replace_string> <output variable> + <replace_string> <output_variable> <input> [<input>...]) -Replace all occurrences of ``match_string`` in the input -with ``replace_string`` and store the result in the output. +Replace all occurrences of ``<match_string>`` in the ``<input>`` +with ``<replace_string>`` and store the result in the ``<output_variable>``. Regular Expressions ^^^^^^^^^^^^^^^^^^^ @@ -77,9 +82,10 @@ Regular Expressions .. code-block:: cmake string(REGEX MATCH <regular_expression> - <output variable> <input> [<input>...]) + <output_variable> <input> [<input>...]) -Match the regular expression once and store the match in the output variable. +Match the ``<regular_expression>`` once and store the match in the +``<output_variable>``. All ``<input>`` arguments are concatenated before matching. .. _`REGEX MATCHALL`: @@ -87,10 +93,10 @@ All ``<input>`` arguments are concatenated before matching. .. code-block:: cmake string(REGEX MATCHALL <regular_expression> - <output variable> <input> [<input>...]) + <output_variable> <input> [<input>...]) -Match the regular expression as many times as possible and store the matches -in the output variable as a list. +Match the ``<regular_expression>`` as many times as possible and store the +matches in the ``<output_variable>`` as a list. All ``<input>`` arguments are concatenated before matching. .. _`REGEX REPLACE`: @@ -98,16 +104,17 @@ All ``<input>`` arguments are concatenated before matching. .. code-block:: cmake string(REGEX REPLACE <regular_expression> - <replace_expression> <output variable> + <replacement_expression> <output_variable> <input> [<input>...]) -Match the regular expression as many times as possible and substitute the -replacement expression for the match in the output. +Match the ``<regular_expression>`` as many times as possible and substitute +the ``<replacement_expression>`` for the match in the output. All ``<input>`` arguments are concatenated before matching. -The replace expression may refer to paren-delimited subexpressions of the -match using ``\1``, ``\2``, ..., ``\9``. Note that two backslashes (``\\1``) -are required in CMake code to get a backslash through argument parsing. +The ``<replacement_expression>`` may refer to parenthesis-delimited +subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that +two backslashes (``\\1``) are required in CMake code to get a backslash +through argument parsing. .. _`Regex Specification`: @@ -180,103 +187,109 @@ Manipulation .. code-block:: cmake - string(APPEND <string variable> [<input>...]) + string(APPEND <string_variable> [<input>...]) -Append all the input arguments to the string. +Append all the ``<input>`` arguments to the string. .. _PREPEND: .. code-block:: cmake - string(PREPEND <string variable> [<input>...]) + string(PREPEND <string_variable> [<input>...]) -Prepend all the input arguments to the string. +Prepend all the ``<input>`` arguments to the string. .. _CONCAT: .. code-block:: cmake - string(CONCAT <output variable> [<input>...]) + string(CONCAT <output_variable> [<input>...]) -Concatenate all the input arguments together and store -the result in the named output variable. +Concatenate all the ``<input>`` arguments together and store +the result in the named ``<output_variable>``. .. _JOIN: .. code-block:: cmake - string(JOIN <glue> <output variable> [<input>...]) + string(JOIN <glue> <output_variable> [<input>...]) -Join all the input arguments together using the glue -string and store the result in the named output variable. +Join all the ``<input>`` arguments together using the ``<glue>`` +string and store the result in the named ``<output_variable>``. -To join list's elements, use preferably the ``JOIN`` operator -from :command:`list` command. This allows for the elements to have +To join a list's elements, prefer to use the ``JOIN`` operator +from the :command:`list` command. This allows for the elements to have special characters like ``;`` in them. .. _TOLOWER: .. code-block:: cmake - string(TOLOWER <string1> <output variable>) + string(TOLOWER <string> <output_variable>) -Convert string to lower characters. +Convert ``<string>`` to lower characters. .. _TOUPPER: .. code-block:: cmake - string(TOUPPER <string1> <output variable>) + string(TOUPPER <string> <output_variable>) -Convert string to upper characters. +Convert ``<string>`` to upper characters. .. _LENGTH: .. code-block:: cmake - string(LENGTH <string> <output variable>) + string(LENGTH <string> <output_variable>) -Store in an output variable a given string's length. +Store in an ``<output_variable>`` a given string's length in bytes. +Note that this means if ``<string>`` contains multi-byte characters, the +result stored in ``<output_variable>`` will *not* be the number of characters. .. _SUBSTRING: .. code-block:: cmake - string(SUBSTRING <string> <begin> <length> <output variable>) + string(SUBSTRING <string> <begin> <length> <output_variable>) + +Store in an ``<output_variable>`` a substring of a given ``<string>``. If +``<length>`` is ``-1`` the remainder of the string starting at ``<begin>`` +will be returned. If ``<string>`` is shorter than ``<length>`` then the +end of the string is used instead. -Store in an output variable a substring of a given string. If length is -``-1`` the remainder of the string starting at begin will be returned. -If string is shorter than length then end of string is used instead. +Both ``<begin>`` and ``<length>`` are counted in bytes, so care must +be exercised if ``<string>`` could contain multi-byte characters. .. note:: - CMake 3.1 and below reported an error if length pointed past - the end of string. + CMake 3.1 and below reported an error if ``<length>`` pointed past + the end of ``<string>``. .. _STRIP: .. code-block:: cmake - string(STRIP <string> <output variable>) + string(STRIP <string> <output_variable>) -Store in an output variable a substring of a given string with leading and -trailing spaces removed. +Store in an ``<output_variable>`` a substring of a given ``<string>`` with +leading and trailing spaces removed. .. _GENEX_STRIP: .. code-block:: cmake - string(GENEX_STRIP <input string> <output variable>) + string(GENEX_STRIP <string> <output_variable>) Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` -from the ``input string`` and store the result in the ``output variable``. +from the input ``<string>`` and store the result in the ``<output_variable>``. .. _REPEAT: .. code-block:: cmake - string(REPEAT <input string> <count> <output variable>) + string(REPEAT <string> <count> <output_variable>) -Produce the output string as repetion of ``input string`` ``count`` times. +Produce the output string as the input ``<string>`` repeated ``<count>`` times. Comparison ^^^^^^^^^^ @@ -285,14 +298,14 @@ Comparison .. code-block:: cmake - string(COMPARE LESS <string1> <string2> <output variable>) - string(COMPARE GREATER <string1> <string2> <output variable>) - string(COMPARE EQUAL <string1> <string2> <output variable>) - string(COMPARE NOTEQUAL <string1> <string2> <output variable>) - string(COMPARE LESS_EQUAL <string1> <string2> <output variable>) - string(COMPARE GREATER_EQUAL <string1> <string2> <output variable>) + string(COMPARE LESS <string1> <string2> <output_variable>) + string(COMPARE GREATER <string1> <string2> <output_variable>) + string(COMPARE EQUAL <string1> <string2> <output_variable>) + string(COMPARE NOTEQUAL <string1> <string2> <output_variable>) + string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>) + string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>) -Compare the strings and store true or false in the output variable. +Compare the strings and store true or false in the ``<output_variable>``. .. _`Supported Hash Algorithms`: @@ -303,9 +316,9 @@ Hashing .. code-block:: cmake - string(<HASH> <output variable> <input>) + string(<HASH> <output_variable> <input>) -Compute a cryptographic hash of the input string. +Compute a cryptographic hash of the ``<input>`` string. The supported ``<HASH>`` algorithm names are: ``MD5`` @@ -336,7 +349,7 @@ Generation .. code-block:: cmake - string(ASCII <number> [<number> ...] <output variable>) + string(ASCII <number> [<number> ...] <output_variable>) Convert all numbers into corresponding ASCII characters. @@ -344,31 +357,31 @@ Convert all numbers into corresponding ASCII characters. .. code-block:: cmake - string(CONFIGURE <string1> <output variable> + string(CONFIGURE <string> <output_variable> [@ONLY] [ESCAPE_QUOTES]) -Transform a string like :command:`configure_file` transforms a file. +Transform a ``<string>`` like :command:`configure_file` transforms a file. .. _MAKE_C_IDENTIFIER: .. code-block:: cmake - string(MAKE_C_IDENTIFIER <input string> <output variable>) + string(MAKE_C_IDENTIFIER <string> <output_variable>) -Convert each non-alphanumeric character in the ``<input string>`` to an -underscore and store the result in the ``<output variable>``. If the first -character of the string is a digit, an underscore will also be prepended to -the result. +Convert each non-alphanumeric character in the input ``<string>`` to an +underscore and store the result in the ``<output_variable>``. If the first +character of the ``<string>`` is a digit, an underscore will also be prepended +to the result. .. _RANDOM: .. code-block:: cmake string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] - [RANDOM_SEED <seed>] <output variable>) + [RANDOM_SEED <seed>] <output_variable>) -Return a random string of given length consisting of -characters from the given alphabet. Default length is 5 characters +Return a random string of given ``<length>`` consisting of +characters from the given ``<alphabet>``. Default length is 5 characters and default alphabet is all numbers and upper and lower case letters. If an integer ``RANDOM_SEED`` is given, its value will be used to seed the random number generator. @@ -377,18 +390,18 @@ random number generator. .. code-block:: cmake - string(TIMESTAMP <output variable> [<format string>] [UTC]) + string(TIMESTAMP <output_variable> [<format_string>] [UTC]) Write a string representation of the current date -and/or time to the output variable. +and/or time to the ``<output_variable>``. -Should the command be unable to obtain a timestamp the output variable -will be set to the empty string "". +If the command is unable to obtain a timestamp, the ``<output_variable>`` +will be set to the empty string ``""``. The optional ``UTC`` flag requests the current date/time representation to be in Coordinated Universal Time (UTC) rather than local time. -The optional ``<format string>`` may contain the following format +The optional ``<format_string>`` may contain the following format specifiers: :: @@ -415,7 +428,7 @@ specifiers: Unknown format specifiers will be ignored and copied to the output as-is. -If no explicit ``<format string>`` is given it will default to: +If no explicit ``<format_string>`` is given, it will default to: :: @@ -432,7 +445,7 @@ If no explicit ``<format string>`` is given it will default to: .. code-block:: cmake - string(UUID <output variable> NAMESPACE <namespace> NAME <name> + string(UUID <output_variable> NAMESPACE <namespace> NAME <name> TYPE <MD5|SHA1> [UPPER]) Create a universally unique identifier (aka GUID) as per RFC4122 @@ -441,6 +454,6 @@ based on the hash of the combined values of ``<namespace>`` The hash algorithm can be either ``MD5`` (Version 3 UUID) or ``SHA1`` (Version 5 UUID). A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` -where each `x` represents a lower case hexadecimal character. -Where required an uppercase representation can be requested +where each ``x`` represents a lower case hexadecimal character. +Where required, an uppercase representation can be requested with the optional ``UPPER`` flag. diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst new file mode 100644 index 000000000..569c7eb11 --- /dev/null +++ b/Help/command/target_precompile_headers.rst @@ -0,0 +1,124 @@ +target_precompile_headers +------------------------- + +Add a list of header files to precompile. + +Precompiling header files can speed up compilation by creating a partially +processed version of some header files, and then using that version during +compilations rather than repeatedly parsing the original headers. + +Main Form +^^^^^^^^^ + +.. code-block:: cmake + + target_precompile_headers(<target> + <INTERFACE|PUBLIC|PRIVATE> [header1...] + [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...]) + +The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or +:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ``<target>``. +The named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +: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 +: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. + +Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets +that will be :ref:`exported <install(EXPORT)>`, or they should at least use +the ``$<BUILD_INTERFACE:...>`` generator expression to prevent precompile +headers from appearing in an installed exported target. Consumers of a target +should typically be in control of what precompile headers they use, not have +precompile headers forced on them by the targets being consumed (since +precompile headers are not typically usage requirements). A notable exception +to this is where an :ref:`interface library <Interface Libraries>` is created +to define a commonly used set of precompile headers in one place and then other +targets link to that interface library privately. In this case, the interface +library exists specifically to propagate the precompile headers to its +consumers and the consumer is effectively still in control, since it decides +whether to link to the interface library or not. + +The list of header files is used to generate a header file named +``cmake_pch.h|xx`` which is used to generate the precompiled header file +(``.pch``, ``.gch``, ``.pchi``) artifact. The ``cmake_pch.h|xx`` header +file will be force included (``-include`` for GCC, ``/FI`` for MSVC) to +all source files, so sources do not need to have ``#include "pch.h"``. + +Header file names specified with angle brackets (e.g. ``<unordered_map>``) or +explicit double quotes (escaped for the :manual:`cmake-language(7)`, +e.g. ``[["other_header.h"]]``) will be treated as is, and include directories +must be available for the compiler to find them. Other header file names +(e.g. ``project_header.h``) are interpreted as being relative to the current +source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be +included by absolute path. + +Arguments to ``target_precompile_headers()`` may use "generator expressions" +with the syntax ``$<...>``. +See the :manual:`cmake-generator-expressions(7)` manual for available +expressions. See the :manual:`cmake-compile-features(7)` manual for +information on compile features and a list of supported compilers. +The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly +useful for specifying a language-specific header to precompile for +only one language (e.g. ``CXX`` and not ``C``). For example: + +.. code-block:: cmake + + target_precompile_headers(myTarget + PUBLIC + project_header.h + "$<$<COMPILE_LANGUAGE:CXX>:cxx_only.h>" + PRIVATE + [["other_header.h"]] + <unordered_map> + ) + +When specifying angle brackets inside a :manual:`generator expression +<cmake-generator-expressions(7)>`, be sure to encode the closing ``>`` +as ``$<ANGLE-R>``. For example: + +.. code-block:: cmake + + target_precompile_headers(mylib PRIVATE + "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>" + "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>" + ) + + +Reusing Precompile Headers +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The command also supports a second signature which can be used to specify that +one target re-uses a precompiled header file artefact from another target +instead of generating its own: + +.. code-block:: cmake + + target_precompile_headers(<target> REUSE_FROM <other_target>) + +This form sets the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` property to +``<other_target>`` and adds a dependency such that ``<target>`` will depend +on ``<other_target>``. CMake will halt with an error if the +:prop_tgt:`PRECOMPILE_HEADERS` property of ``<target>`` is already set when +the ``REUSE_FROM`` form is used. + +.. note:: + + The ``REUSE_FROM`` form requires the same set of compiler options, + compiler flags and compiler definitions for both ``<target>`` and + ``<other_target>``. Some compilers (e.g. GCC) may issue a warning if the + precompiled header file cannot be used (``-Winvalid-pch``). + +See Also +^^^^^^^^ + +To disable precompile headers for specific targets, see the +:prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property. + +To prevent precompile headers from being used when compiling a specific +source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 0bc2ca37a..edbf92ce6 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -103,15 +103,18 @@ The options are: ``<LANG>_STANDARD <std>`` Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`, + :prop_tgt:`OBJC_STANDARD`, :prop_tgt:`OBJCXX_STANDARD`, or :prop_tgt:`CUDA_STANDARD` target property of the generated project. ``<LANG>_STANDARD_REQUIRED <bool>`` Specify the :prop_tgt:`C_STANDARD_REQUIRED`, - :prop_tgt:`CXX_STANDARD_REQUIRED`, or :prop_tgt:`CUDA_STANDARD_REQUIRED` + :prop_tgt:`CXX_STANDARD_REQUIRED`, :prop_tgt:`OBJC_STANDARD_REQUIRED`, + :prop_tgt:`OBJCXX_STANDARD_REQUIRED`,or :prop_tgt:`CUDA_STANDARD_REQUIRED` target property of the generated project. ``<LANG>_EXTENSIONS <bool>`` Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_EXTENSIONS`, + :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 @@ -171,6 +174,12 @@ then the language standard variables are honored: * :variable:`CMAKE_CXX_STANDARD` * :variable:`CMAKE_CXX_STANDARD_REQUIRED` * :variable:`CMAKE_CXX_EXTENSIONS` +* :variable:`CMAKE_OBJC_STANDARD` +* :variable:`CMAKE_OBJC_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJC_EXTENSIONS` +* :variable:`CMAKE_OBJCXX_STANDARD` +* :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJCXX_EXTENSIONS` * :variable:`CMAKE_CUDA_STANDARD` * :variable:`CMAKE_CUDA_STANDARD_REQUIRED` * :variable:`CMAKE_CUDA_EXTENSIONS` |