summaryrefslogtreecommitdiffstats
path: root/Help/command
diff options
context:
space:
mode:
Diffstat (limited to 'Help/command')
-rw-r--r--Help/command/add_custom_command.rst11
-rw-r--r--Help/command/add_custom_target.rst9
-rw-r--r--Help/command/add_library.rst2
-rw-r--r--Help/command/ctest_memcheck.rst8
-rw-r--r--Help/command/ctest_submit.rst8
-rw-r--r--Help/command/execute_process.rst27
-rw-r--r--Help/command/file.rst13
-rw-r--r--Help/command/if.rst6
-rw-r--r--Help/command/install.rst6
-rw-r--r--Help/command/source_group.rst18
-rw-r--r--Help/command/string.rst34
-rw-r--r--Help/command/target_link_libraries.rst5
-rw-r--r--Help/command/try_compile.rst36
13 files changed, 162 insertions, 21 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst
index 4ab4298..80e7edf 100644
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@@ -21,7 +21,8 @@ The first signature is for adding a custom command to produce an output::
[WORKING_DIRECTORY dir]
[COMMENT comment]
[DEPFILE depfile]
- [VERBATIM] [APPEND] [USES_TERMINAL])
+ [VERBATIM] [APPEND] [USES_TERMINAL]
+ [COMMAND_EXPAND_LISTS])
This defines a command to generate specified ``OUTPUT`` file(s).
A target created in the same directory (``CMakeLists.txt`` file)
@@ -122,6 +123,14 @@ The options are:
Arguments to ``DEPENDS`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
+``COMMAND_EXPAND_LISTS``
+ Lists in ``COMMAND`` arguments will be expanded, including those
+ created with
+ :manual:`generator expressions <cmake-generator-expressions(7)>`,
+ allowing ``COMMAND`` arguments such as
+ ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
+ to be properly expanded.
+
``IMPLICIT_DEPENDS``
Request scanning of implicit dependencies of an input file.
The language given specifies the programming language whose
diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst
index 6980d61..bd61c8b 100644
--- a/Help/command/add_custom_target.rst
+++ b/Help/command/add_custom_target.rst
@@ -12,6 +12,7 @@ Add a target with no output so it will always be built.
[WORKING_DIRECTORY dir]
[COMMENT comment]
[VERBATIM] [USES_TERMINAL]
+ [COMMAND_EXPAND_LISTS]
[SOURCES src1 [src2...]])
Adds a target with the given name that executes the given commands.
@@ -88,6 +89,14 @@ The options are:
Use the :command:`add_dependencies` command to add dependencies
on other targets.
+``COMMAND_EXPAND_LISTS``
+ Lists in ``COMMAND`` arguments will be expanded, including those
+ created with
+ :manual:`generator expressions <cmake-generator-expressions(7)>`,
+ allowing ``COMMAND`` arguments such as
+ ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
+ to be properly expanded.
+
``SOURCES``
Specify additional source files to be included in the custom target.
Specified source files will be added to IDE project files for
diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst
index 36adcbe..af75a39 100644
--- a/Help/command/add_library.rst
+++ b/Help/command/add_library.rst
@@ -33,7 +33,7 @@ type is ``STATIC`` or ``SHARED`` based on whether the current value of the
variable :variable:`BUILD_SHARED_LIBS` is ``ON``. For ``SHARED`` and
``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
property is set to ``ON`` automatically.
-A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
+A ``SHARED`` or ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK`
target property to create an OS X Framework.
If a library does not export any symbols, it must not be declared as a
diff --git a/Help/command/ctest_memcheck.rst b/Help/command/ctest_memcheck.rst
index 29bdf7d..a983d68 100644
--- a/Help/command/ctest_memcheck.rst
+++ b/Help/command/ctest_memcheck.rst
@@ -18,6 +18,7 @@ Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`.
[SCHEDULE_RANDOM <ON|OFF>]
[STOP_TIME <time-of-day>]
[RETURN_VALUE <result-var>]
+ [DEFECT_COUNT <defect-count-var>]
[QUIET]
)
@@ -26,4 +27,9 @@ Run tests with a dynamic analysis tool and store results in
``MemCheck.xml`` for submission with the :command:`ctest_submit`
command.
-The options are the same as those for the :command:`ctest_test` command.
+Most options are the same as those for the :command:`ctest_test` command.
+
+The options unique to this command are:
+
+``DEFECT_COUNT <defect-count-var>``
+ Store in the ``<defect-count-var>`` the number of defects found.
diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst
index 6830b59..a7d9708 100644
--- a/Help/command/ctest_submit.rst
+++ b/Help/command/ctest_submit.rst
@@ -56,10 +56,16 @@ Submit to CDash Upload API
::
- ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>])
+ ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
+ [RETRY_COUNT <count>]
+ [RETRY_DELAY <delay>]
+ [QUIET])
This second signature is used to upload files to CDash via the CDash
file upload API. The api first sends a request to upload to CDash along
with a content hash of the file. If CDash does not already have the file,
then it is uploaded. Along with the file, a CDash type string is specified
to tell CDash which handler to use to process the data.
+
+This signature accepts the ``RETRY_COUNT``, ``RETRY_DELAY``, and ``QUIET``
+options as described above.
diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst
index ca44b53..d617243 100644
--- a/Help/command/execute_process.rst
+++ b/Help/command/execute_process.rst
@@ -18,9 +18,10 @@ Execute one or more child processes.
[OUTPUT_QUIET]
[ERROR_QUIET]
[OUTPUT_STRIP_TRAILING_WHITESPACE]
- [ERROR_STRIP_TRAILING_WHITESPACE])
+ [ERROR_STRIP_TRAILING_WHITESPACE]
+ [ENCODING <name>])
-Runs the given sequence of one or more commands with the standard
+Runs the given sequence of one or more commands in parallel with the standard
output of each process piped to the standard input of the next.
A single standard error pipe is used for all processes.
@@ -36,6 +37,9 @@ Options:
(Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to
redirect stdin, stdout, and stderr.)
+ If a sequential execution of multiple commands is required, use multiple
+ :command:`execute_process` calls with a single ``COMMAND`` argument.
+
``WORKING_DIRECTORY``
The named directory will be set as the current working directory of
the child processes.
@@ -63,6 +67,25 @@ Options:
``OUTPUT_QUIET``, ``ERROR_QUIET``
The standard output or standard error results will be quietly ignored.
+``ENCODING <name>``
+ On Windows, the encoding that is used to decode output from the process.
+ Ignored on other platforms.
+ Valid encoding names are:
+
+ ``NONE``
+ Perform no decoding. This assumes that the process output is encoded
+ in the same way as CMake's internal encoding (UTF-8).
+ This is the default.
+ ``AUTO``
+ Use the current active console's codepage or if that isn't
+ available then use ANSI.
+ ``ANSI``
+ Use the ANSI codepage.
+ ``OEM``
+ Use the original equipment manufacturer (OEM) code page.
+ ``UTF8``
+ Use the UTF-8 codepage.
+
If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
same pipe the precedence is not specified.
If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will
diff --git a/Help/command/file.rst b/Help/command/file.rst
index 77e9f62..3e669c2 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -83,10 +83,12 @@ from the input file.
::
- file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> <filename> <variable>)
+ file(<HASH> <filename> <variable>)
Compute a cryptographic hash of the content of ``<filename>`` and
-store it in a ``<variable>``.
+store it in a ``<variable>``. The supported ``<HASH>`` algorithm names
+are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>`
+command.
------------------------------------------------------------------------------
@@ -153,7 +155,8 @@ Move a file or directory within a filesystem from ``<oldname>`` to
file(REMOVE_RECURSE [<files>...])
Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given
-files and directories, also non-empty directories
+files and directories, also non-empty directories. No error is emitted if a
+given file does not exist.
------------------------------------------------------------------------------
@@ -233,8 +236,8 @@ Additional options to ``DOWNLOAD`` are:
``EXPECTED_HASH ALGO=<value>``
Verify that the downloaded content hash matches the expected value, where
- ``ALGO`` is one of ``MD5``, ``SHA1``, ``SHA224``, ``SHA256``, ``SHA384``, or
- ``SHA512``. If it does not match, the operation fails with an error.
+ ``ALGO`` is one of the algorithms supported by ``file(<HASH>)``.
+ If it does not match, the operation fails with an error.
``EXPECTED_MD5 <value>``
Historical short-hand for ``EXPECTED_HASH MD5=<value>``.
diff --git a/Help/command/if.rst b/Help/command/if.rst
index 0941029..2a087d0 100644
--- a/Help/command/if.rst
+++ b/Help/command/if.rst
@@ -9,17 +9,17 @@ Conditionally execute a group of commands.
# then section.
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
- ...
+ #...
elseif(expression2)
# elseif section.
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
- ...
+ #...
else(expression)
# else section.
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
- ...
+ #...
endif(expression)
Evaluates the given expression. If the result is true, the commands
diff --git a/Help/command/install.rst b/Help/command/install.rst
index d57dd75..70087a4 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -90,8 +90,10 @@ project. There are five kinds of target files that may be installed:
``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``FRAMEWORK``, and ``BUNDLE``.
Executables are treated as ``RUNTIME`` targets, except that those
marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE``
-targets on OS X. Static libraries are always treated as ``ARCHIVE``
-targets. Module libraries are always treated as ``LIBRARY`` targets.
+targets on OS X. Static libraries are treated as ``ARCHIVE`` targets,
+except that those marked with the ``FRAMEWORK`` property are treated
+as ``FRAMEWORK`` targets on OS X.
+Module libraries are always treated as ``LIBRARY`` targets.
For non-DLL platforms shared libraries are treated as ``LIBRARY``
targets, except that those marked with the ``FRAMEWORK`` property are
treated as ``FRAMEWORK`` targets on OS X. For DLL platforms the DLL
diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst
index 6e3829c..938ca40 100644
--- a/Help/command/source_group.rst
+++ b/Help/command/source_group.rst
@@ -2,15 +2,27 @@ source_group
------------
Define a grouping for source files in IDE project generation.
+There are two different signatures to create source groups.
-.. code-block:: cmake
+::
source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
+ source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
Defines a group into which sources will be placed in project files.
This is intended to set up file tabs in Visual Studio.
The options are:
+``TREE``
+ CMake will automatically detect, from ``<src>`` files paths, source groups
+ it needs to create, to keep structure of source groups analogically to the
+ actual files and directories structure in the project. Paths of ``<src>``
+ files will be cut to be relative to ``<root>``.
+
+``PREFIX``
+ Source group and files located directly in ``<root>`` path, will be placed
+ in ``<prefix>`` source groups.
+
``FILES``
Any source file specified explicitly will be placed in group
``<name>``. Relative paths are interpreted with respect to the
@@ -25,11 +37,13 @@ explicitly lists the file with ``FILES`` will be favored, if any.
If no group explicitly lists the file, the *last* group whose
regular expression matches the file will be favored.
-The ``<name>`` of the group may contain backslashes to specify subgroups:
+The ``<name>`` of the group and ``<prefix>`` argument may contain backslashes
+to specify subgroups:
.. code-block:: cmake
source_group(outer\\inner ...)
+ source_group(TREE <root> PREFIX sources\\inc ...)
For backwards compatibility, the short-hand signature
diff --git a/Help/command/string.rst b/Help/command/string.rst
index 8028333..698a91d 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -206,15 +206,38 @@ Comparison
Compare the strings and store true or false in the output variable.
+.. _`Supported Hash Algorithms`:
+
Hashing
^^^^^^^
::
- string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512>
- <output variable> <input>)
+ string(<HASH> <output variable> <input>)
Compute a cryptographic hash of the input string.
+The supported ``<HASH>`` algorithm names are:
+
+``MD5``
+ Message-Digest Algorithm 5, RFC 1321.
+``SHA1``
+ US Secure Hash Algorithm 1, RFC 3174.
+``SHA224``
+ US Secure Hash Algorithms, RFC 4634.
+``SHA256``
+ US Secure Hash Algorithms, RFC 4634.
+``SHA384``
+ US Secure Hash Algorithms, RFC 4634.
+``SHA512``
+ US Secure Hash Algorithms, RFC 4634.
+``SHA3_224``
+ Keccak SHA-3.
+``SHA3_256``
+ Keccak SHA-3.
+``SHA3_384``
+ Keccak SHA-3.
+``SHA3_512``
+ Keccak SHA-3.
Generation
^^^^^^^^^^
@@ -273,6 +296,7 @@ specifiers:
::
+ %% A literal percent sign (%).
%d The day of the current month (01-31).
%H The hour on a 24-hour clock (00-23).
%I The hour on a 12-hour clock (01-12).
@@ -306,6 +330,12 @@ If no explicit ``<format string>`` is given it will default to:
Write a string which can be used as an identifier in C.
+.. note::
+
+ If the ``SOURCE_DATE_EPOCH`` environment variable is set,
+ its value will be used instead of the current time.
+ See https://reproducible-builds.org/specs/source-date-epoch/ for details.
+
UUID
""""
diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst
index 90b6575..30d69f2 100644
--- a/Help/command/target_link_libraries.rst
+++ b/Help/command/target_link_libraries.rst
@@ -53,6 +53,11 @@ Each ``<item>`` may be:
:ref:`usage requirement <Target Usage Requirements>`. This has the same
effect as passing the framework directory as an include directory.
+ On :ref:`Visual Studio Generators` for VS 2010 and above, library files
+ ending in ``.targets`` will be treated as MSBuild targets files and
+ imported into generated project files. This is not supported by other
+ generators.
+
* **A plain library name**: The generated link line will ask the linker
to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``).
diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst
index 7830deb..66ea3d7 100644
--- a/Help/command/try_compile.rst
+++ b/Help/command/try_compile.rst
@@ -35,7 +35,11 @@ Try Compiling Source Files
[COMPILE_DEFINITIONS <defs>...]
[LINK_LIBRARIES <libs>...]
[OUTPUT_VARIABLE <var>]
- [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]])
+ [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
+ [<LANG>_STANDARD <std>]
+ [<LANG>_STANDARD_REQUIRED <bool>]
+ [<LANG>_EXTENSIONS <bool>]
+ )
Try building an executable from one or more source files. The success or
failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is
@@ -82,6 +86,19 @@ The options are:
``OUTPUT_VARIABLE <var>``
Store the output from the build process the given variable.
+``<LANG>_STANDARD <std>``
+ Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_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`
+ target property of the generated project.
+
+``<LANG>_EXTENSIONS <bool>``
+ Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_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
@@ -119,3 +136,20 @@ the type of target used for the source file signature.
Set the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify
variables that must be propagated into the test project. This variable is
meant for use only in toolchain files.
+
+If :policy:`CMP0067` is set to ``NEW``, or any of the ``<LANG>_STANDARD``,
+``<LANG>_STANDARD_REQUIRED``, or ``<LANG>_EXTENSIONS`` options are used,
+then the language standard variables are honored:
+
+* :variable:`CMAKE_C_STANDARD`
+* :variable:`CMAKE_C_STANDARD_REQUIRED`
+* :variable:`CMAKE_C_EXTENSIONS`
+* :variable:`CMAKE_CXX_STANDARD`
+* :variable:`CMAKE_CXX_STANDARD_REQUIRED`
+* :variable:`CMAKE_CXX_EXTENSIONS`
+* :variable:`CMAKE_CUDA_STANDARD`
+* :variable:`CMAKE_CUDA_STANDARD_REQUIRED`
+* :variable:`CMAKE_CUDA_EXTENSIONS`
+
+Their values are used to set the corresponding target properties in
+the generated project (unless overridden by an explicit option).
generated by cgit v0.12 at 2024-10-21 06:41:43 (GMT)