mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-04 21:00:17 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Revise docs on Scripting Commands

Browse Source 
Revise docs for all "Scripting Commands", except four find_XXX
that use a macro suite of their own.

* Take full advantage of the improved syntax highlighting.
* Make consequential use of <..> placeholders.
* Clarify things here and there in the text.

Specific improvements to some command docs:

* "math": Correct description of novel hexadecimal capability.
* "if", "foreach", "while": Provide link to "endif" etc
* "foreach", "while": Mention "break" and "continue".
* "foreach": Simplify explanation of ``RANGE`` and ``IN`` signatures;
   advise against negative arguments or reverse ranges (compare issue #18461)
* "endif", "endfunction" etc: Explain that the argument is optional and
   maintained for compatibility only
This commit is contained in:
Joachim Wuttke (l)
2018-10-16 21:50:48 +02:00
committed by Joachim Wuttke (o)
parent 7053dd301c
commit c2efb3efcd
41 changed files with 478 additions and 325 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
Help/command/break.rst
View File

@@ -3,10 +3,10 @@ break
Break from an enclosing foreach or while loop. Break from an enclosing foreach or while loop.
:: .. code-block:: cmake
break() break()
Breaks from an enclosing foreach loop or while loop Breaks from an enclosing :command:`foreach` or :command:`while` loop.
See also the :command:`continue` command. See also the :command:`continue` command.

2
Help/command/cmake_host_system_information.rst
View File

@@ -3,7 +3,7 @@ cmake_host_system_information
Query host system specific information. Query host system specific information.
:: .. code-block:: cmake
cmake_host_system_information(RESULT <variable> QUERY <key> ...) cmake_host_system_information(RESULT <variable> QUERY <key> ...)

16
Help/command/cmake_minimum_required.rst
View File

@@ -1,11 +1,15 @@
cmake_minimum_required cmake_minimum_required
---------------------- ----------------------
Set the minimum required version of cmake for a project and Require a minimum version of cmake.
update `Policy Settings`_ to match the version given::
.. code-block:: cmake
cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR]) cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
Sets the minimum required version of cmake for a project.
Also updates the policy settings as explained below.
``<min>`` and the optional ``<max>`` are each CMake versions of the form ``<min>`` and the optional ``<max>`` are each CMake versions of the form
``major.minor[.patch[.tweak]]``, and the ``...`` is literal. ``major.minor[.patch[.tweak]]``, and the ``...`` is literal.
@@ -47,13 +51,17 @@ as of a given CMake version and tells newer CMake versions to warn
about their new policies. about their new policies.
When a ``<min>`` version higher than 2.4 is specified the command When a ``<min>`` version higher than 2.4 is specified the command
implicitly invokes:: implicitly invokes
.. code-block:: cmake
cmake_policy(VERSION <min>[...<max>]) cmake_policy(VERSION <min>[...<max>])
which sets CMake policies based on the range of versions specified. which sets CMake policies based on the range of versions specified.
When a ``<min>`` version 2.4 or lower is given the command implicitly When a ``<min>`` version 2.4 or lower is given the command implicitly
invokes:: invokes
.. code-block:: cmake
cmake_policy(VERSION 2.4[...<max>]) cmake_policy(VERSION 2.4[...<max>])

22
Help/command/cmake_parse_arguments.rst
View File

@@ -1,26 +1,28 @@
cmake_parse_arguments cmake_parse_arguments
--------------------- ---------------------
``cmake_parse_arguments`` is intended to be used in macros or functions for Parse function or macro arguments.
parsing the arguments given to that macro or function. It processes the
arguments and defines a set of variables which hold the values of the
respective options.
:: .. code-block:: cmake
cmake_parse_arguments(<prefix> <options> <one_value_keywords> cmake_parse_arguments(<prefix> <options> <one_value_keywords>
<multi_value_keywords> args...) <multi_value_keywords> <args>...)
cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords> cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
<multi_value_keywords>) <one_value_keywords> <multi_value_keywords>)
The first signature reads processes arguments passed in the ``args...``. This command is for use in macros or functions.
It processes the arguments given to that macro or function,
and defines a set of variables which hold the values of the
respective options.
The first signature reads processes arguments passed in the ``<args>...``.
This may be used in either a :command:`macro` or a :command:`function`. This may be used in either a :command:`macro` or a :command:`function`.
The ``PARSE_ARGV`` signature is only for use in a :command:`function` The ``PARSE_ARGV`` signature is only for use in a :command:`function`
body. In this case the arguments that are parsed come from the body. In this case the arguments that are parsed come from the
``ARGV#`` variables of the calling function. The parsing starts with ``ARGV#`` variables of the calling function. The parsing starts with
the Nth argument, where ``N`` is an unsigned integer. This allows for the ``<N>``-th argument, where ``<N>`` is an unsigned integer. This allows for
the values to have special characters like ``;`` in them. the values to have special characters like ``;`` in them.
The ``<options>`` argument contains all options for the respective macro, The ``<options>`` argument contains all options for the respective macro,

12
Help/command/cmake_policy.rst
View File

@@ -22,7 +22,9 @@ Setting Policies by CMake Version
The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW`` The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
behavior. While setting policies individually is supported, we behavior. While setting policies individually is supported, we
encourage projects to set policies based on CMake versions:: encourage projects to set policies based on CMake versions:
.. code-block:: cmake
cmake_policy(VERSION <min>[...<max>]) cmake_policy(VERSION <min>[...<max>])
@@ -50,7 +52,7 @@ command implicitly calls ``cmake_policy(VERSION)`` too.
Setting Policies Explicitly Setting Policies Explicitly
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
:: .. code-block:: cmake
cmake_policy(SET CMP<NNNN> NEW) cmake_policy(SET CMP<NNNN> NEW)
cmake_policy(SET CMP<NNNN> OLD) cmake_policy(SET CMP<NNNN> OLD)
@@ -66,7 +68,7 @@ policy state to ``NEW``.
Checking Policy Settings Checking Policy Settings
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
:: .. code-block:: cmake
cmake_policy(GET CMP<NNNN> <variable>) cmake_policy(GET CMP<NNNN> <variable>)
@@ -85,7 +87,9 @@ scripts loaded by :command:`include` and :command:`find_package` commands
except when invoked with the ``NO_POLICY_SCOPE`` option except when invoked with the ``NO_POLICY_SCOPE`` option
(see also policy :policy:`CMP0011`). (see also policy :policy:`CMP0011`).
The ``cmake_policy`` command provides an interface to manage custom The ``cmake_policy`` command provides an interface to manage custom
entries on the policy stack:: entries on the policy stack:
.. code-block:: cmake
cmake_policy(PUSH) cmake_policy(PUSH)
cmake_policy(POP) cmake_policy(POP)

22
Help/command/configure_file.rst
View File

@@ -3,7 +3,7 @@ configure_file
Copy a file to another location and modify its contents. Copy a file to another location and modify its contents.
:: .. code-block:: cmake
configure_file(<input> <output> configure_file(<input> <output>
[COPYONLY] [ESCAPE_QUOTES] [@ONLY] [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
@@ -13,15 +13,21 @@ Copies an ``<input>`` file to an ``<output>`` file and substitutes
variable values referenced as ``@VAR@`` or ``${VAR}`` in the input variable values referenced as ``@VAR@`` or ``${VAR}`` in the input
file content. Each variable reference will be replaced with the file content. Each variable reference will be replaced with the
current value of the variable, or the empty string if the variable current value of the variable, or the empty string if the variable
is not defined. Furthermore, input lines of the form:: is not defined. Furthermore, input lines of the form
.. code-block:: c
#cmakedefine VAR ... #cmakedefine VAR ...
will be replaced with either:: will be replaced with either
.. code-block:: c
#define VAR ... #define VAR ...
or:: or
.. code-block:: c
/* #undef VAR */ /* #undef VAR */
@@ -33,12 +39,16 @@ either ``#define VAR 1`` or ``#define VAR 0`` similarly.
The result lines (with the exception of the ``#undef`` comments) can be The result lines (with the exception of the ``#undef`` comments) can be
indented using spaces and/or tabs between the ``#`` character indented using spaces and/or tabs between the ``#`` character
and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace
indentation will be preserved in the output lines:: indentation will be preserved in the output lines:
.. code-block:: c
# cmakedefine VAR # cmakedefine VAR
# cmakedefine01 VAR # cmakedefine01 VAR
will be replaced, if ``VAR`` is defined, with:: will be replaced, if ``VAR`` is defined, with
.. code-block:: c
# define VAR # define VAR
# define VAR 1 # define VAR 1

6
Help/command/continue.rst
View File

@@ -3,10 +3,12 @@ continue
Continue to the top of enclosing foreach or while loop. Continue to the top of enclosing foreach or while loop.
:: .. code-block:: cmake
continue() continue()
The ``continue`` command allows a cmake script to abort the rest of a block The ``continue`` command allows a cmake script to abort the rest of a block
in a :command:`foreach` or :command:`while` loop, and start at the top of in a :command:`foreach` or :command:`while` loop, and start at the top of
the next iteration. See also the :command:`break` command. the next iteration.
See also the :command:`break` command.

4
Help/command/else.rst
View File

@@ -3,8 +3,8 @@ else
Starts the else portion of an if block. Starts the else portion of an if block.
:: .. code-block:: cmake
else(expression) else([<condition>])
See the :command:`if` command. See the :command:`if` command.

9
Help/command/elseif.rst
View File

@@ -1,10 +1,11 @@
elseif elseif
------ ------
Starts the elseif portion of an if block. Starts an elseif portion of an if block.
:: .. code-block:: cmake
elseif(expression) elseif(<condition>)
See the :command:`if` command. See the :command:`if` command, especially for the syntax and logic
of the ``<condition>``.

8
Help/command/endforeach.rst
View File

@@ -3,8 +3,12 @@ endforeach
Ends a list of commands in a foreach block. Ends a list of commands in a foreach block.
:: .. code-block:: cmake
endforeach(expression) endforeach([<loop_var>])
See the :command:`foreach` command. See the :command:`foreach` command.
The optional ``<loop_var>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<loop_var>`` argument of
the opening ``foreach`` clause.

8
Help/command/endfunction.rst
View File

@@ -3,8 +3,12 @@ endfunction
Ends a list of commands in a function block. Ends a list of commands in a function block.
:: .. code-block:: cmake
endfunction(expression) endfunction([<name>])
See the :command:`function` command. See the :command:`function` command.
The optional ``<name>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<name>`` argument
of the opening ``function`` command.

8
Help/command/endif.rst
View File

@@ -3,8 +3,12 @@ endif
Ends a list of commands in an if block. Ends a list of commands in an if block.
:: .. code-block:: cmake
endif(expression) endif([<condition>])
See the :command:`if` command. See the :command:`if` command.
The optional ``<condition>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the argument of the opening
``if`` clause.

8
Help/command/endmacro.rst
View File

@@ -3,8 +3,12 @@ endmacro
Ends a list of commands in a macro block. Ends a list of commands in a macro block.
:: .. code-block:: cmake
endmacro(expression) endmacro([<name>])
See the :command:`macro` command. See the :command:`macro` command.
The optional ``<name>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<name>`` argument
of the opening ``macro`` command.

8
Help/command/endwhile.rst
View File

@@ -3,8 +3,12 @@ endwhile
Ends a list of commands in a while block. Ends a list of commands in a while block.
:: .. code-block:: cmake
endwhile(expression) endwhile([<condition>])
See the :command:`while` command. See the :command:`while` command.
The optional ``<condition>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the argument of the opening
``while`` clause.

32
Help/command/file.rst
View File

@@ -42,7 +42,7 @@ Reading
.. _READ: .. _READ:
:: .. code-block:: cmake
file(READ <filename> <variable> file(READ <filename> <variable>
[OFFSET <offset>] [LIMIT <max-in>] [HEX]) [OFFSET <offset>] [LIMIT <max-in>] [HEX])
@@ -54,7 +54,7 @@ be converted to a hexadecimal representation (useful for binary data).
.. _STRINGS: .. _STRINGS:
:: .. code-block:: cmake
file(STRINGS <filename> <variable> [<options>...]) file(STRINGS <filename> <variable> [<options>...])
@@ -105,7 +105,7 @@ from the input file.
.. _HASH: .. _HASH:
:: .. code-block:: cmake
file(<HASH> <filename> <variable>) file(<HASH> <filename> <variable>)
@@ -116,7 +116,7 @@ command.
.. _TIMESTAMP: .. _TIMESTAMP:
:: .. code-block:: cmake
file(TIMESTAMP <filename> <variable> [<format>] [UTC]) file(TIMESTAMP <filename> <variable> [<format>] [UTC])
@@ -133,7 +133,7 @@ Writing
.. _WRITE: .. _WRITE:
.. _APPEND: .. _APPEND:
:: .. code-block:: cmake
file(WRITE <filename> <content>...) file(WRITE <filename> <content>...)
file(APPEND <filename> <content>...) file(APPEND <filename> <content>...)
@@ -150,7 +150,7 @@ to update the file only when its content changes.
.. _TOUCH: .. _TOUCH:
.. _TOUCH_NOCREATE: .. _TOUCH_NOCREATE:
:: .. code-block:: cmake
file(TOUCH [<files>...]) file(TOUCH [<files>...])
file(TOUCH_NOCREATE [<files>...]) file(TOUCH_NOCREATE [<files>...])
@@ -167,7 +167,7 @@ modified.
.. _GENERATE: .. _GENERATE:
:: .. code-block:: cmake
file(GENERATE OUTPUT output-file file(GENERATE OUTPUT output-file
<INPUT input-file|CONTENT content> <INPUT input-file|CONTENT content>
@@ -217,7 +217,7 @@ Filesystem
.. _GLOB: .. _GLOB:
.. _GLOB_RECURSE: .. _GLOB_RECURSE:
:: .. code-block:: cmake
file(GLOB <variable> file(GLOB <variable>
[LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
@@ -272,7 +272,7 @@ Examples of recursive globbing include::
.. _RENAME: .. _RENAME:
:: .. code-block:: cmake
file(RENAME <oldname> <newname>) file(RENAME <oldname> <newname>)
@@ -282,7 +282,7 @@ Move a file or directory within a filesystem from ``<oldname>`` to
.. _REMOVE: .. _REMOVE:
.. _REMOVE_RECURSE: .. _REMOVE_RECURSE:
:: .. code-block:: cmake
file(REMOVE [<files>...]) file(REMOVE [<files>...])
file(REMOVE_RECURSE [<files>...]) file(REMOVE_RECURSE [<files>...])
@@ -293,7 +293,7 @@ given file does not exist.
.. _MAKE_DIRECTORY: .. _MAKE_DIRECTORY:
:: .. code-block:: cmake
file(MAKE_DIRECTORY [<directories>...]) file(MAKE_DIRECTORY [<directories>...])
@@ -302,7 +302,7 @@ Create the given directories and their parents as needed.
.. _COPY: .. _COPY:
.. _INSTALL: .. _INSTALL:
:: .. code-block:: cmake
file(<COPY|INSTALL> <files>... DESTINATION <dir> file(<COPY|INSTALL> <files>... DESTINATION <dir>
[FILE_PERMISSIONS <permissions>...] [FILE_PERMISSIONS <permissions>...]
@@ -338,7 +338,7 @@ Path Conversion
.. _RELATIVE_PATH: .. _RELATIVE_PATH:
:: .. code-block:: cmake
file(RELATIVE_PATH <variable> <directory> <file>) file(RELATIVE_PATH <variable> <directory> <file>)
@@ -348,7 +348,7 @@ store it in the ``<variable>``.
.. _TO_CMAKE_PATH: .. _TO_CMAKE_PATH:
.. _TO_NATIVE_PATH: .. _TO_NATIVE_PATH:
:: .. code-block:: cmake
file(TO_CMAKE_PATH "<path>" <variable>) file(TO_CMAKE_PATH "<path>" <variable>)
file(TO_NATIVE_PATH "<path>" <variable>) file(TO_NATIVE_PATH "<path>" <variable>)
@@ -370,7 +370,7 @@ Transfer
.. _DOWNLOAD: .. _DOWNLOAD:
.. _UPLOAD: .. _UPLOAD:
:: .. code-block:: cmake
file(DOWNLOAD <url> <file> [<options>...]) file(DOWNLOAD <url> <file> [<options>...])
file(UPLOAD <file> <url> [<options>...]) file(UPLOAD <file> <url> [<options>...])
@@ -460,7 +460,7 @@ Locking
.. _LOCK: .. _LOCK:
:: .. code-block:: cmake
file(LOCK <path> [DIRECTORY] [RELEASE] file(LOCK <path> [DIRECTORY] [RELEASE]
[GUARD <FUNCTION|FILE|PROCESS>] [GUARD <FUNCTION|FILE|PROCESS>]

10
Help/command/find_package.rst
View File

@@ -12,7 +12,7 @@ Find an external project, and load its settings.
Basic Signature and Module Mode Basic Signature and Module Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:: .. code-block:: cmake
find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
[REQUIRED] [[COMPONENTS] [components...]] [REQUIRED] [[COMPONENTS] [components...]]
@@ -67,7 +67,9 @@ full command signature and details of the search process. Project
maintainers wishing to provide a package to be found by this command maintainers wishing to provide a package to be found by this command
are encouraged to read on. are encouraged to read on.
The complete Config mode command signature is:: The complete Config mode command signature is
.. code-block:: cmake
find_package(<PackageName> [version] [EXACT] [QUIET] find_package(<PackageName> [version] [EXACT] [QUIET]
[REQUIRED] [[COMPONENTS] [components...]] [REQUIRED] [[COMPONENTS] [components...]]
@@ -202,7 +204,9 @@ is set no attempt is made to choose a highest or closest version number.
To control the order in which ``find_package`` checks for compatibility use To control the order in which ``find_package`` checks for compatibility use
the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
For instance in order to select the highest version one can set:: For instance in order to select the highest version one can set
.. code-block:: cmake
SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)

117
Help/command/foreach.rst
View File

@@ -3,45 +3,82 @@ foreach
Evaluate a group of commands for each value in a list. Evaluate a group of commands for each value in a list.
.. code-block:: cmake
foreach(<loop_var> <items>)
<commands>
endforeach()
where ``<items>`` is a list of items that are separated by
semicolon or whitespace.
All commands between ``foreach`` and the matching ``endforeach`` are recorded
without being invoked. Once the ``endforeach`` is evaluated, the recorded
list of commands is invoked once for each item in ``<items>``.
At the beginning of each iteration the variable ``loop_var`` will be set
to the value of the current item.
The commands :command:`break` and :command:`continue` provide means to
escape from the normal control flow.
Per legacy, the :command:`endforeach` command admits
an optional ``<loop_var>`` argument.
If used, it must be a verbatim
repeat of the argument of the opening
``foreach`` command.
.. code-block:: cmake
foreach(<loop_var> RANGE <stop>)
In this variant, ``foreach`` iterates over the numbers
0, 1, ... up to (and including) the nonnegative integer ``<stop>``.
.. code-block:: cmake
foreach(<loop_var> RANGE <start> <stop> [<step>])
In this variant, ``foreach`` iterates over the numbers from
``<start>`` up to at most ``<stop>`` in steps of ``<step>``.
If ``<step>`` is not specified, then the step size is 1.
The three arguments ``<start>`` ``<stop>`` ``<step>`` must
all be nonnegative integers, and ``<stop>`` must not be
smaller than ``<start>``; otherwise you enter the danger zone
of undocumented behavior that may change in future releases.
.. code-block:: cmake
foreach(loop_var IN [LISTS [<lists>]] [ITEMS [<items>]])
In this variant, ``<lists>`` is a whitespace or semicolon
separated list of list-valued variables. The ``foreach``
command iterates over each item in each given list.
The ``<items>`` following the ``ITEMS`` keyword are processed
as in the first variant of the ``foreach`` command.
The forms ``LISTS A`` and ``ITEMS ${A}`` are
equivalent.
The following example shows how the ``LISTS`` option is
processed:
.. code-block:: cmake
set(A 0;1)
set(B 2 3)
set(C "4 5")
set(D 6;7 8)
set(E "")
foreach(X IN LISTS A B C D E)
message(STATUS "X=${X}")
endforeach()
yields
:: ::
foreach(loop_var arg1 arg2 ...) -- X=0
COMMAND1(ARGS ...) -- X=1
COMMAND2(ARGS ...) -- X=2
... -- X=3
endforeach(loop_var) -- X=4 5
-- X=6
All commands between foreach and the matching endforeach are recorded -- X=7
without being invoked. Once the endforeach is evaluated, the recorded -- X=8
list of commands is invoked once for each argument listed in the
original foreach command. Before each iteration of the loop
``${loop_var}`` will be set as a variable with the current value in the
list.
::
foreach(loop_var RANGE total)
foreach(loop_var RANGE start stop [step])
Foreach can also iterate over a generated range of numbers. There are
three types of this iteration:
* When specifying single number, the range will have elements [0, ... to
"total"] (inclusive).
* When specifying two numbers, the range will have elements from the
first number to the second number (inclusive).
* The third optional number is the increment used to iterate from the
first number to the second number (inclusive).
::
foreach(loop_var IN [LISTS [list1 [...]]]
[ITEMS [item1 [...]]])
Iterates over a precise list of items. The ``LISTS`` option names
list-valued variables to be traversed, including empty elements (an
empty string is a zero-length list). (Note macro
arguments are not variables.) The ``ITEMS`` option ends argument
parsing and includes all arguments following it in the iteration.

34
Help/command/function.rst
View File

@@ -1,27 +1,29 @@
function function
-------- --------
Start recording a function for later invocation as a command:: Start recording a function for later invocation as a command.
function(<name> [arg1 [arg2 [arg3 ...]]]) .. code-block:: cmake
COMMAND1(ARGS ...)
COMMAND2(ARGS ...) function(<name> [<arg1> ...])
... <commands>
endfunction(<name>) endfunction()
Defines a function named ``<name>`` that takes arguments
named ``<arg1>``, ...
The ``<commands>`` in the function definition are recorded;
they are not invoked until the function is invoked. When
the function is invoked, the recorded ``<commands>`` are first
modified by replacing formal parameters (``${arg1}``, ...)
with the arguments passed, and then invoked as normal commands.
Define a function named ``<name>`` that takes arguments named ``arg1``,
``arg2``, ``arg3``, (...).
Commands listed after function, but before the matching
:command:`endfunction()`, are not invoked until the function is invoked.
When it is invoked, the commands recorded in the function are first
modified by replacing formal parameters (``${arg1}``) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the In addition to referencing the formal parameters you can reference the
``ARGC`` variable which will be set to the number of arguments passed ``ARGC`` variable which will be set to the number of arguments passed
into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which
will have the actual values of the arguments passed in. will have the actual values of the arguments passed in.
This facilitates creating functions with optional arguments. This facilitates creating functions with optional arguments.
Additionally ``ARGV`` holds the list of all arguments given to the
Furthermore, ``ARGV`` holds the list of all arguments given to the
function and ``ARGN`` holds the list of arguments past the last expected function and ``ARGN`` holds the list of arguments past the last expected
argument. argument.
Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined
@@ -29,6 +31,10 @@ behavior. Checking that ``ARGC`` is greater than ``#`` is the only way
to ensure that ``ARGV#`` was passed to the function as an extra to ensure that ``ARGV#`` was passed to the function as an extra
argument. argument.
Per legacy, the :command:`endfunction` command admits an optional
``<name>`` argument. If used, it must be a verbatim repeat of the
argument of the opening ``function`` command.
A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for
details. details.

12
Help/command/get_cmake_property.rst
View File

@@ -3,14 +3,14 @@ get_cmake_property
Get a global property of the CMake instance. Get a global property of the CMake instance.
:: .. code-block:: cmake
get_cmake_property(VAR property) get_cmake_property(<var> <property>)
Get a global property from the CMake instance. The value of the property is Gets a global property from the CMake instance. The value of
stored in the variable ``VAR``. If the property is not found, ``VAR`` the ``<property>`` is stored in the variable ``<var>``.
will be set to "NOTFOUND". See the :manual:`cmake-properties(7)` manual If the property is not found, ``<var>`` will be set to ``"NOTFOUND"``.
for available properties. See the :manual:`cmake-properties(7)` manual for available properties.
See also the :command:`get_property` command ``GLOBAL`` option. See also the :command:`get_property` command ``GLOBAL`` option.

6
Help/command/get_directory_property.rst
View File

@@ -3,11 +3,11 @@ get_directory_property
Get a property of ``DIRECTORY`` scope. Get a property of ``DIRECTORY`` scope.
:: .. code-block:: cmake
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>) get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Store a property of directory scope in the named ``<variable>``. Stores a property of directory scope in the named ``<variable>``.
The ``DIRECTORY`` argument specifies another directory from which The ``DIRECTORY`` argument specifies another directory from which
to retrieve the property value instead of the current directory. to retrieve the property value instead of the current directory.
The specified directory must have already been traversed by CMake. The specified directory must have already been traversed by CMake.
@@ -18,7 +18,7 @@ if the property is not found for the nominated directory scope,
the search will chain to a parent scope as described for the the search will chain to a parent scope as described for the
:command:`define_property` command. :command:`define_property` command.
:: .. code-block:: cmake
get_directory_property(<variable> [DIRECTORY <dir>] get_directory_property(<variable> [DIRECTORY <dir>]
DEFINITION <var-name>) DEFINITION <var-name>)

30
Help/command/get_filename_component.rst
View File

@@ -3,13 +3,11 @@ get_filename_component
Get a specific component of a full filename. Get a specific component of a full filename.
------------------------------------------------------------------------------ .. code-block:: cmake
:: get_filename_component(<var> <FileName> <mode> [CACHE])
get_filename_component(<VAR> <FileName> <COMP> [CACHE]) Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of:
Set ``<VAR>`` to a component of ``<FileName>``, where ``<COMP>`` is one of:
:: ::
@@ -24,15 +22,11 @@ The longest file extension is always considered. If the optional
``CACHE`` argument is specified, the result variable is added to the ``CACHE`` argument is specified, the result variable is added to the
cache. cache.
------------------------------------------------------------------------------ .. code-block:: cmake
:: get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
get_filename_component(<VAR> <FileName> Sets ``<var>`` to the absolute path of ``<FileName>``, where ``<mode>`` is one
<COMP> [BASE_DIR <BASE_DIR>]
[CACHE])
Set ``<VAR>`` to the absolute path of ``<FileName>``, where ``<COMP>`` is one
of: of:
:: ::
@@ -41,7 +35,7 @@ of:
REALPATH = Full path to existing file with symlinks resolved REALPATH = Full path to existing file with symlinks resolved
If the provided ``<FileName>`` is a relative path, it is evaluated relative If the provided ``<FileName>`` is a relative path, it is evaluated relative
to the given base directory ``<BASE_DIR>``. If no base directory is to the given base directory ``<dir>``. If no base directory is
provided, the default base directory will be provided, the default base directory will be
:variable:`CMAKE_CURRENT_SOURCE_DIR`. :variable:`CMAKE_CURRENT_SOURCE_DIR`.
@@ -49,16 +43,12 @@ Paths are returned with forward slashes and have no trailing slashes. If the
optional ``CACHE`` argument is specified, the result variable is added to the optional ``CACHE`` argument is specified, the result variable is added to the
cache. cache.
------------------------------------------------------------------------------ .. code-block:: cmake
:: get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
get_filename_component(<VAR> <FileName>
PROGRAM [PROGRAM_ARGS <ARG_VAR>]
[CACHE])
The program in ``<FileName>`` will be found in the system search path or The program in ``<FileName>`` will be found in the system search path or
left as a full path. If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then left as a full path. If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then
any command-line arguments present in the ``<FileName>`` string are split any command-line arguments present in the ``<FileName>`` string are split
from the program name and stored in ``<ARG_VAR>``. This is used to from the program name and stored in ``<arg_var>``. This is used to
separate a program name from its arguments in a command line string. separate a program name from its arguments in a command line string.

20
Help/command/get_property.rst
View File

@@ -3,32 +3,33 @@ get_property
Get a property. Get a property.
:: .. code-block:: cmake
get_property(<variable> get_property(<variable>
<GLOBAL | <GLOBAL |
DIRECTORY [dir] | DIRECTORY [<dir>] |
TARGET <target> | TARGET <target> |
SOURCE <source> | SOURCE <source> |
INSTALL <file> | INSTALL <file> |
TEST <test> | TEST <test> |
CACHE <entry> | CACHE <entry> |
VARIABLE> VARIABLE >
PROPERTY <name> PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS]) [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
Get one property from one object in a scope. The first argument Gets one property from one object in a scope.
specifies the variable in which to store the result. The second
argument determines the scope from which to get the property. It must The first argument specifies the variable in which to store the result.
be one of the following: The second argument determines the scope from which to get the property.
It must be one of the following:
``GLOBAL`` ``GLOBAL``
Scope is unique and does not accept a name. Scope is unique and does not accept a name.
``DIRECTORY`` ``DIRECTORY``
Scope defaults to the current directory but another Scope defaults to the current directory but another
directory (already processed by CMake) may be named by full or directory (already processed by CMake) may be named by the
relative path. full or relative path ``<dir>``.
``TARGET`` ``TARGET``
Scope must name one existing target. Scope must name one existing target.
@@ -58,6 +59,7 @@ value indicating whether the property has been set. If the ``DEFINED``
option is given the variable is set to a boolean value indicating option is given the variable is set to a boolean value indicating
whether the property has been defined such as with the whether the property has been defined such as with the
:command:`define_property` command. :command:`define_property` command.
If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a
string containing documentation for the requested property. If string containing documentation for the requested property. If
documentation is requested for a property that has not been defined documentation is requested for a property that has not been defined

25
Help/command/if.rst
View File

@@ -6,7 +6,7 @@ Conditionally execute a group of commands.
Synopsis Synopsis
^^^^^^^^ ^^^^^^^^
:: .. code-block:: cmake
if(<condition>) if(<condition>)
<commands> <commands>
@@ -23,8 +23,11 @@ Otherwise, optional ``elseif`` blocks are processed in the same way.
Finally, if no ``condition`` is true, ``commands`` in the optional ``else`` Finally, if no ``condition`` is true, ``commands`` in the optional ``else``
block are executed. block are executed.
Per legacy, the ``else`` and ``endif`` clause may also have a ``condition`` argument, Per legacy, the :command:`else` and :command:`elseif` commands admit
which then must be a verbatim repeat of the argument of the opening ``if`` clause. an optional ``<condition>`` argument.
If used, it must be a verbatim
repeat of the argument of the opening
``if`` command.
Condition Syntax Condition Syntax
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
@@ -202,21 +205,27 @@ The if command was written very early in CMake's history, predating
the ``${}`` variable evaluation syntax, and for convenience evaluates the ``${}`` variable evaluation syntax, and for convenience evaluates
variables named by its arguments as shown in the above signatures. variables named by its arguments as shown in the above signatures.
Note that normal variable evaluation with ``${}`` applies before the if Note that normal variable evaluation with ``${}`` applies before the if
command even receives the arguments. Therefore code like:: command even receives the arguments. Therefore code like
.. code-block:: cmake
set(var1 OFF) set(var1 OFF)
set(var2 "var1") set(var2 "var1")
if(${var2}) if(${var2})
appears to the if command as:: appears to the if command as
if(var1) .. code-block:: cmake
if(var1)
and is evaluated according to the ``if(<variable>)`` case documented and is evaluated according to the ``if(<variable>)`` case documented
above. The result is ``OFF`` which is false. However, if we remove the above. The result is ``OFF`` which is false. However, if we remove the
``${}`` from the example then the command sees:: ``${}`` from the example then the command sees
if(var2) .. code-block:: cmake
if(var2)
which is true because ``var2`` is defined to "var1" which is not a false which is true because ``var2`` is defined to "var1" which is not a false
constant. constant.

10
Help/command/include.rst
View File

@@ -3,16 +3,16 @@ include
Load and run CMake code from a file or module. Load and run CMake code from a file or module.
:: .. code-block:: cmake
include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>] include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
[NO_POLICY_SCOPE]) [NO_POLICY_SCOPE])
Load and run CMake code from the file given. Variable reads and Loads and runs CMake code from the file given. Variable reads and
writes access the scope of the caller (dynamic scoping). If ``OPTIONAL`` writes access the scope of the caller (dynamic scoping). If ``OPTIONAL``
is present, then no error is raised if the file does not exist. If is present, then no error is raised if the file does not exist. If
``RESULT_VARIABLE`` is given the variable will be set to the full filename ``RESULT_VARIABLE`` is given the variable ``<var>`` will be set to the
which has been included or NOTFOUND if it failed. full filename which has been included or ``NOTFOUND`` if it failed.
If a module is specified instead of a file, the file with name If a module is specified instead of a file, the file with name
``<modulename>.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`, ``<modulename>.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`,

2
Help/command/include_guard.rst
View File

@@ -3,7 +3,7 @@ include_guard
Provides an include guard for the file currently being processed by CMake. Provides an include guard for the file currently being processed by CMake.
:: .. code-block:: cmake
include_guard([DIRECTORY|GLOBAL]) include_guard([DIRECTORY|GLOBAL])

60
Help/command/list.rst
View File

@@ -64,7 +64,7 @@ Reading
.. _LENGTH: .. _LENGTH:
:: .. code-block:: cmake
list(LENGTH <list> <output variable>) list(LENGTH <list> <output variable>)
@@ -72,7 +72,7 @@ Returns the list's length.
.. _GET: .. _GET:
:: .. code-block:: cmake
list(GET <list> <element index> [<element index> ...] <output variable>) list(GET <list> <element index> [<element index> ...] <output variable>)
@@ -80,7 +80,7 @@ Returns the list of elements specified by indices from the list.
.. _JOIN: .. _JOIN:
:: .. code-block:: cmake
list(JOIN <list> <glue> <output variable>) list(JOIN <list> <glue> <output variable>)
@@ -90,7 +90,7 @@ from :command:`string` command.
.. _SUBLIST: .. _SUBLIST:
:: .. code-block:: cmake
list(SUBLIST <list> <begin> <length> <output variable>) list(SUBLIST <list> <begin> <length> <output variable>)
@@ -104,7 +104,7 @@ Search
.. _FIND: .. _FIND:
:: .. code-block:: cmake
list(FIND <list> <value> <output variable>) list(FIND <list> <value> <output variable>)
@@ -116,7 +116,7 @@ Modification
.. _APPEND: .. _APPEND:
:: .. code-block:: cmake
list(APPEND <list> [<element> ...]) list(APPEND <list> [<element> ...])
@@ -124,7 +124,7 @@ Appends elements to the list.
.. _FILTER: .. _FILTER:
:: .. code-block:: cmake
list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
@@ -136,7 +136,7 @@ For more information on regular expressions see also the
.. _INSERT: .. _INSERT:
:: .. code-block:: cmake
list(INSERT <list> <element_index> <element> [<element> ...]) list(INSERT <list> <element_index> <element> [<element> ...])
@@ -144,7 +144,7 @@ Inserts elements to the list to the specified location.
.. _REMOVE_ITEM: .. _REMOVE_ITEM:
:: .. code-block:: cmake
list(REMOVE_ITEM <list> <value> [<value> ...]) list(REMOVE_ITEM <list> <value> [<value> ...])
@@ -152,7 +152,7 @@ Removes the given items from the list.
.. _REMOVE_AT: .. _REMOVE_AT:
:: .. code-block:: cmake
list(REMOVE_AT <list> <index> [<index> ...]) list(REMOVE_AT <list> <index> [<index> ...])
@@ -160,7 +160,7 @@ Removes items at given indices from the list.
.. _REMOVE_DUPLICATES: .. _REMOVE_DUPLICATES:
:: .. code-block:: cmake
list(REMOVE_DUPLICATES <list>) list(REMOVE_DUPLICATES <list>)
@@ -168,7 +168,7 @@ Removes duplicated items in the list.
.. _TRANSFORM: .. _TRANSFORM:
:: .. code-block:: cmake
list(TRANSFORM <list> <ACTION> [<SELECTOR>] list(TRANSFORM <list> <ACTION> [<SELECTOR>]
[OUTPUT_VARIABLE <output variable>]) [OUTPUT_VARIABLE <output variable>])
@@ -190,30 +190,40 @@ The actions have exactly the same semantics as sub-commands of
The ``<ACTION>`` may be one of: The ``<ACTION>`` may be one of:
``APPEND``, ``PREPEND``: Append, prepend specified value to each element of ``APPEND``, ``PREPEND``: Append, prepend specified value to each element of
the list. :: the list.
.. code-block:: cmake
list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower ``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower
characters. :: characters.
.. code-block:: cmake
list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
``STRIP``: Remove leading and trailing spaces from each element of the ``STRIP``: Remove leading and trailing spaces from each element of the
list. :: list.
.. code-block:: cmake
list(TRANSFORM <list> STRIP ...) list(TRANSFORM <list> STRIP ...)
``GENEX_STRIP``: Strip any ``GENEX_STRIP``: Strip any
:manual:`generator expressions <cmake-generator-expressions(7)>` from each :manual:`generator expressions <cmake-generator-expressions(7)>` from each
element of the list. :: element of the list.
.. code-block:: cmake
list(TRANSFORM <list> GENEX_STRIP ...) list(TRANSFORM <list> GENEX_STRIP ...)
``REPLACE``: Match the regular expression as many times as possible and ``REPLACE``: Match the regular expression as many times as possible and
substitute the replacement expression for the match for each element substitute the replacement expression for the match for each element
of the list of the list
(Same semantic as ``REGEX REPLACE`` from :command:`string` command). :: (Same semantic as ``REGEX REPLACE`` from :command:`string` command).
.. code-block:: cmake
list(TRANSFORM <list> REPLACE <regular_expression> list(TRANSFORM <list> REPLACE <regular_expression>
<replace_expression> ...) <replace_expression> ...)
@@ -223,17 +233,23 @@ type of selector can be specified at a time.
The ``<SELECTOR>`` may be one of: The ``<SELECTOR>`` may be one of:
``AT``: Specify a list of indexes. :: ``AT``: Specify a list of indexes.
.. code-block:: cmake
list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
``FOR``: Specify a range with, optionally, an increment used to iterate over ``FOR``: Specify a range with, optionally, an increment used to iterate over
the range. :: the range.
.. code-block:: cmake
list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
``REGEX``: Specify a regular expression. Only elements matching the regular ``REGEX``: Specify a regular expression. Only elements matching the regular
expression will be transformed. :: expression will be transformed.
.. code-block:: cmake
list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
@@ -243,7 +259,7 @@ Ordering
.. _REVERSE: .. _REVERSE:
:: .. code-block:: cmake
list(REVERSE <list>) list(REVERSE <list>)
@@ -251,7 +267,7 @@ Reverses the contents of the list in-place.
.. _SORT: .. _SORT:
:: .. code-block:: cmake
list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])

36
Help/command/macro.rst
View File

@@ -1,27 +1,29 @@
macro macro
----- -----
Start recording a macro for later invocation as a command:: Start recording a macro for later invocation as a command
macro(<name> [arg1 [arg2 [arg3 ...]]]) .. code-block:: cmake
COMMAND1(ARGS ...)
COMMAND2(ARGS ...) macro(<name> [<arg1> ...])
... <commands>
endmacro(<name>) endmacro(<name>)
Define a macro named ``<name>`` that takes arguments named ``arg1``, Defines a macro named ``<name>`` that takes arguments
``arg2``, ``arg3``, (...). named ``<arg1>``, ...
Commands listed after macro, but before the matching Commands listed after macro, but before the matching
:command:`endmacro()`, are not invoked until the macro is invoked. :command:`endmacro()`, are not invoked until the macro is invoked.
When it is invoked, the commands recorded in the macro are first When it is invoked, the commands recorded in the macro are first
modified by replacing formal parameters (``${arg1}``) with the arguments modified by replacing formal parameters (``${arg1}``, ...)
passed, and then invoked as normal commands. with the arguments passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the In addition to referencing the formal parameters you can reference the
values ``${ARGC}`` which will be set to the number of arguments passed values ``${ARGC}`` which will be set to the number of arguments passed
into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``, into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``,
... which will have the actual values of the arguments passed in. ... which will have the actual values of the arguments passed in.
This facilitates creating macros with optional arguments. This facilitates creating macros with optional arguments.
Additionally ``${ARGV}`` holds the list of all arguments given to the
Furthermore, ``${ARGV}`` holds the list of all arguments given to the
macro and ``${ARGN}`` holds the list of arguments past the last expected macro and ``${ARGN}`` holds the list of arguments past the last expected
argument. argument.
Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined
@@ -38,7 +40,9 @@ Macro Argument Caveats
Note that the parameters to a macro and values such as ``ARGN`` are Note that the parameters to a macro and values such as ``ARGN`` are
not variables in the usual CMake sense. They are string not variables in the usual CMake sense. They are string
replacements much like the C preprocessor would do with a macro. replacements much like the C preprocessor would do with a macro.
Therefore you will NOT be able to use commands like:: Therefore you will NOT be able to use commands like
.. code-block:: cmake
if(ARGV1) # ARGV1 is not a variable if(ARGV1) # ARGV1 is not a variable
if(DEFINED ARGV2) # ARGV2 is not a variable if(DEFINED ARGV2) # ARGV2 is not a variable
@@ -50,18 +54,22 @@ In the second and third case, the proper way to check if an optional
variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``. variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``.
In the last case, you can use ``foreach(loop_var ${ARGN})`` but this In the last case, you can use ``foreach(loop_var ${ARGN})`` but this
will skip empty arguments. will skip empty arguments.
If you need to include them, you can use:: If you need to include them, you can use
.. code-block:: cmake
set(list_var "${ARGN}") set(list_var "${ARGN}")
foreach(loop_var IN LISTS list_var) foreach(loop_var IN LISTS list_var)
Note that if you have a variable with the same name in the scope from Note that if you have a variable with the same name in the scope from
which the macro is called, using unreferenced names will use the which the macro is called, using unreferenced names will use the
existing variable instead of the arguments. For example:: existing variable instead of the arguments. For example:
.. code-block:: cmake
macro(_BAR) macro(_BAR)
foreach(arg IN LISTS ARGN) foreach(arg IN LISTS ARGN)
[...] <commands>
endforeach() endforeach()
endmacro() endmacro()

27
Help/command/mark_as_advanced.rst
View File

@@ -3,17 +3,22 @@ mark_as_advanced
Mark cmake cached variables as advanced. Mark cmake cached variables as advanced.
:: .. code-block:: cmake
mark_as_advanced([CLEAR|FORCE] VAR [VAR2 ...]) mark_as_advanced([CLEAR|FORCE] <var1> ...)
Mark the named cached variables as advanced. An advanced variable Sets the advanced/non-advanced state of the named
will not be displayed in any of the cmake GUIs unless the show cached variables.
advanced option is on. If ``CLEAR`` is the first argument advanced
variables are changed back to unadvanced. If ``FORCE`` is the first
argument, then the variable is made advanced. If neither ``FORCE`` nor
``CLEAR`` is specified, new values will be marked as advanced, but if the
variable already has an advanced/non-advanced state, it will not be
changed.
It does nothing in script mode. An advanced variable will not be displayed in any
of the cmake GUIs unless the ``show advanced`` option is on.
In script mode, the advanced/non-advanced state has no effect.
If the keyword ``CLEAR`` is given
then advanced variables are changed back to unadvanced.
If the keyword ``FORCE`` is given
then the variables are made advanced.
If neither ``FORCE`` nor ``CLEAR`` is specified,
new values will be marked as advanced, but if a
variable already has an advanced/non-advanced state,
it will not be changed.

40
Help/command/math.rst
View File

@@ -1,30 +1,36 @@
math math
---- ----
Mathematical expressions. Evaluate a mathematical expression.
:: .. code-block:: cmake
math(EXPR <output-variable> <math-expression> [OUTPUT_FORMAT <format>]) math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
``EXPR`` evaluates mathematical expression and returns result in the Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the
output variable. Example mathematical expression is ``5 * (10 + 13)``. resulting value.
The mathematical expression must be given as a string (i.e. enclosed in
double quotation marks). An example is ``"5 * (10 + 13)"``.
Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``, Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``,
``^``, ``~``, ``<<``, ``>>``, and ``(...)``. They have the same meaning ``^``, ``~``, ``<<``, ``>>``, and ``(...)``; they have the same meaning
as they do in C code. as in C code.
Numeric constants are evaluated in decimal or hexadecimal representation. Hexadecimal numbers are recognized when prefixed with "0x", as in C code.
The result is formatted according to the option "OUTPUT_FORMAT" , The result is formatted according to the option ``OUTPUT_FORMAT``,
where ``<format>`` is one of: where ``<format>`` is one of
::
HEXADECIMAL = Result in output variable will be formatted in C code ``HEXADECIMAL``
Hexadecimal notation. Hexadecimal notation as in C code, i. e. starting with "0x".
DECIMAL = Result in output variable will be formatted in decimal notation. ``DECIMAL``
Decimal notation. Which is also used if no ``OUTPUT_FORMAT`` option
is specified.
For example:: For example
math(EXPR value "100 * 0xA" DECIMAL) results in value is set to "1000" .. code-block:: cmake
math(EXPR value "100 * 0xA" HEXADECIMAL) results in value is set to "0x3e8"
math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000"
math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8"

2
Help/command/message.rst
View File

@@ -3,7 +3,7 @@ message
Display a message to the user. Display a message to the user.
:: .. code-block:: cmake
message([<mode>] "message to display" ...) message([<mode>] "message to display" ...)

15
Help/command/option.rst
View File

@@ -1,17 +1,16 @@
option option
------ ------
Provides an option that the user can optionally select. Provide an option that the user can optionally select.
:: .. code-block:: cmake
option(<option_variable> "help string describing option" option(<variable> "<help_text>" [value])
[initial value])
Provide an option for the user to select as ``ON`` or ``OFF``. If no Provides an option for the user to select as ``ON`` or ``OFF``.
initial value is provided, ``OFF`` is used. If the option is already If no initial ``<value>`` is provided, ``OFF`` is used.
set as a normal variable then the command does nothing If ``<variable>`` is already set as a normal variable
(see policy :policy:`CMP0077`). then the command does nothing (see policy :policy:`CMP0077`).
If you have options that depend on the values of other options, see If you have options that depend on the values of other options, see
the module help for :module:`CMakeDependentOption`. the module help for :module:`CMakeDependentOption`.

7
Help/command/return.rst
View File

@@ -3,7 +3,7 @@ return
Return from a file, directory or function. Return from a file, directory or function.
:: .. code-block:: cmake
return() return()
@@ -14,5 +14,6 @@ and control is returned to the including file. If it is encountered in a
file which is not included by another file, e.g. a ``CMakeLists.txt``, file which is not included by another file, e.g. a ``CMakeLists.txt``,
control is returned to the parent directory if there is one. If return is 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. called in a function, control is returned to the caller of the function.
Note that a macro is not a function and does not handle return like a
function does. Note that a :command:`macro <macro>`, unlike a :command:`function <function>`,
is expanded in place and therefore cannot handle ``return()``.

46
Help/command/separate_arguments.rst
View File

@@ -1,33 +1,43 @@
separate_arguments separate_arguments
------------------ ------------------
Parse space-separated arguments into a semicolon-separated list. Parse command-line arguments into a semicolon-separated list.
:: .. code-block:: cmake
separate_arguments(<var> <NATIVE|UNIX|WINDOWS>_COMMAND "<args>") separate_arguments(<variable> <mode> <args>)
Parses a UNIX- or Windows-style command-line string "<args>" and Parses a space-separated string ``<args>`` into a list of items,
stores a semicolon-separated list of the arguments in ``<var>``. The and stores this list in semicolon-separated standard form in ``<variable>``.
entire command line must be given in one "<args>" argument.
The ``UNIX_COMMAND`` mode separates arguments by unquoted whitespace. It This function is intended for parsing command-line arguments.
recognizes both single-quote and double-quote pairs. A backslash The entire command line must be passed as one string in the
escapes the next literal character (``\"`` is ``"``); there are no special argument ``<args>``.
escapes (``\n`` is just ``n``).
The ``WINDOWS_COMMAND`` mode parses a Windows command-line using the same The exact parsing rules depend on the operating system.
syntax the runtime library uses to construct argv at startup. It They are specified by the ``<mode>`` argument which must
separates arguments by whitespace that is not double-quoted. be one of the following keywords:
Backslashes are literal unless they precede double-quotes. See the
MSDN article `Parsing C Command-Line Arguments`_ for details.
The ``NATIVE_COMMAND`` mode parses a Windows command-line if the host ``UNIX_COMMAND``
system is Windows, and a UNIX command-line otherwise. Arguments are separated by by unquoted whitespace.
Both single-quote and double-quote pairs are respected.
A backslash escapes the next literal character (``\"`` is ``"``);
there are no special escapes (``\n`` is just ``n``).
``WINDOWS_COMMAND``
A Windows command-line is parsed using the same
syntax the runtime library uses to construct argv at startup. It
separates arguments by whitespace that is not double-quoted.
Backslashes are literal unless they precede double-quotes. See the
MSDN article `Parsing C Command-Line Arguments`_ for details.
``NATIVE_COMMAND``
Proceeds as in ``WINDOWS_COMMAND`` mode if the host system is Windows.
Otherwise proceeds as in ``UNIX_COMMAND`` mode.
.. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx .. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx
:: .. code-block:: cmake
separate_arguments(<var>) separate_arguments(<var>)

12
Help/command/set.rst
View File

@@ -15,11 +15,11 @@ unset. See the :command:`unset` command to unset variables explicitly.
Set Normal Variable Set Normal Variable
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
:: .. code-block:: cmake
set(<variable> <value>... [PARENT_SCOPE]) set(<variable> <value>... [PARENT_SCOPE])
Set the given ``<variable>`` in the current function or directory scope. Sets the given ``<variable>`` in the current function or directory scope.
If the ``PARENT_SCOPE`` option is given the variable will be set in If the ``PARENT_SCOPE`` option is given the variable will be set in
the scope above the current scope. Each new directory or function the scope above the current scope. Each new directory or function
@@ -32,11 +32,11 @@ undefined and if it had a value, it is still that value).
Set Cache Entry Set Cache Entry
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
:: .. code-block:: cmake
set(<variable> <value>... CACHE <type> <docstring> [FORCE]) set(<variable> <value>... CACHE <type> <docstring> [FORCE])
Set the given cache ``<variable>`` (cache entry). Since cache entries Sets the given cache ``<variable>`` (cache entry). Since cache entries
are meant to provide user-settable values this does not overwrite are meant to provide user-settable values this does not overwrite
existing cache entries by default. Use the ``FORCE`` option to existing cache entries by default. Use the ``FORCE`` option to
overwrite existing entries. overwrite existing entries.
@@ -84,8 +84,8 @@ current working directory and convert it to an absolute path.
Set Environment Variable Set Environment Variable
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
:: .. code-block:: cmake
set(ENV{<variable>} <value>...) set(ENV{<variable>} <value>...)
Set the current process environment ``<variable>`` to the given value. Sets the current process environment ``<variable>`` to the given value.

8
Help/command/set_directory_properties.rst
View File

@@ -1,11 +1,13 @@
set_directory_properties set_directory_properties
------------------------ ------------------------
Set properties of the current directory and subdirectories in key-value pairs. Set properties of the current directory and subdirectories.
:: .. code-block:: cmake
set_directory_properties(PROPERTIES prop1 value1 prop2 value2) set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
Sets properties of the current directory and its subdirectories in key-value pairs.
See :ref:`Directory Properties` for the list of properties known to CMake See :ref:`Directory Properties` for the list of properties known to CMake
and their individual documentation for the behavior of each property. and their individual documentation for the behavior of each property.

25
Help/command/set_property.rst
View File

@@ -3,21 +3,22 @@ set_property
Set a named property in a given scope. Set a named property in a given scope.
:: .. code-block:: cmake
set_property(<GLOBAL | set_property(<GLOBAL |
DIRECTORY [dir] | DIRECTORY [<dir>] |
TARGET [target1 [target2 ...]] | TARGET [<target1> ...] |
SOURCE [src1 [src2 ...]] | SOURCE [<src1> ...] |
INSTALL [file1 [file2 ...]] | INSTALL [<file1> ...] |
TEST [test1 [test2 ...]] | TEST [<test1> ...] |
CACHE [entry1 [entry2 ...]]> CACHE [<entry1> ...] >
[APPEND] [APPEND_STRING] [APPEND] [APPEND_STRING]
PROPERTY <name> [value1 [value2 ...]]) PROPERTY <name> [value1 ...])
Set one property on zero or more objects of a scope. The first Sets one property on zero or more objects of a scope.
argument determines the scope in which the property is set. It must
be one of the following: The first argument determines the scope in which the property is set.
It must be one of the following:
``GLOBAL`` ``GLOBAL``
Scope is unique and does not accept a name. Scope is unique and does not accept a name.

2
Help/command/site_name.rst
View File

@@ -3,6 +3,6 @@ site_name
Set the given variable to the name of the computer. Set the given variable to the name of the computer.
:: .. code-block:: cmake
site_name(variable) site_name(variable)

46
Help/command/string.rst
View File

@@ -48,7 +48,7 @@ Search and Replace
.. _FIND: .. _FIND:
:: .. code-block:: cmake
string(FIND <string> <substring> <output variable> [REVERSE]) string(FIND <string> <substring> <output variable> [REVERSE])
@@ -59,7 +59,7 @@ substring. If the substring is not found, a position of -1 is returned.
.. _REPLACE: .. _REPLACE:
:: .. code-block:: cmake
string(REPLACE <match_string> string(REPLACE <match_string>
<replace_string> <output variable> <replace_string> <output variable>
@@ -73,7 +73,7 @@ Regular Expressions
.. _`REGEX MATCH`: .. _`REGEX MATCH`:
:: .. code-block:: cmake
string(REGEX MATCH <regular_expression> string(REGEX MATCH <regular_expression>
<output variable> <input> [<input>...]) <output variable> <input> [<input>...])
@@ -83,7 +83,7 @@ All ``<input>`` arguments are concatenated before matching.
.. _`REGEX MATCHALL`: .. _`REGEX MATCHALL`:
:: .. code-block:: cmake
string(REGEX MATCHALL <regular_expression> string(REGEX MATCHALL <regular_expression>
<output variable> <input> [<input>...]) <output variable> <input> [<input>...])
@@ -94,7 +94,7 @@ All ``<input>`` arguments are concatenated before matching.
.. _`REGEX REPLACE`: .. _`REGEX REPLACE`:
:: .. code-block:: cmake
string(REGEX REPLACE <regular_expression> string(REGEX REPLACE <regular_expression>
<replace_expression> <output variable> <replace_expression> <output variable>
@@ -177,7 +177,7 @@ Manipulation
.. _APPEND: .. _APPEND:
:: .. code-block:: cmake
string(APPEND <string variable> [<input>...]) string(APPEND <string variable> [<input>...])
@@ -185,7 +185,7 @@ Append all the input arguments to the string.
.. _PREPEND: .. _PREPEND:
:: .. code-block:: cmake
string(PREPEND <string variable> [<input>...]) string(PREPEND <string variable> [<input>...])
@@ -193,7 +193,7 @@ Prepend all the input arguments to the string.
.. _CONCAT: .. _CONCAT:
:: .. code-block:: cmake
string(CONCAT <output variable> [<input>...]) string(CONCAT <output variable> [<input>...])
@@ -202,7 +202,7 @@ the result in the named output variable.
.. _JOIN: .. _JOIN:
:: .. code-block:: cmake
string(JOIN <glue> <output variable> [<input>...]) string(JOIN <glue> <output variable> [<input>...])
@@ -215,7 +215,7 @@ special characters like ``;`` in them.
.. _TOLOWER: .. _TOLOWER:
:: .. code-block:: cmake
string(TOLOWER <string1> <output variable>) string(TOLOWER <string1> <output variable>)
@@ -223,7 +223,7 @@ Convert string to lower characters.
.. _TOUPPER: .. _TOUPPER:
:: .. code-block:: cmake
string(TOUPPER <string1> <output variable>) string(TOUPPER <string1> <output variable>)
@@ -231,7 +231,7 @@ Convert string to upper characters.
.. _LENGTH: .. _LENGTH:
:: .. code-block:: cmake
string(LENGTH <string> <output variable>) string(LENGTH <string> <output variable>)
@@ -239,7 +239,7 @@ Store in an output variable a given string's length.
.. _SUBSTRING: .. _SUBSTRING:
:: .. code-block:: cmake
string(SUBSTRING <string> <begin> <length> <output variable>) string(SUBSTRING <string> <begin> <length> <output variable>)
@@ -253,7 +253,7 @@ If string is shorter than length then end of string is used instead.
.. _STRIP: .. _STRIP:
:: .. code-block:: cmake
string(STRIP <string> <output variable>) string(STRIP <string> <output variable>)
@@ -262,7 +262,7 @@ trailing spaces removed.
.. _GENEX_STRIP: .. _GENEX_STRIP:
:: .. code-block:: cmake
string(GENEX_STRIP <input string> <output variable>) string(GENEX_STRIP <input string> <output variable>)
@@ -274,7 +274,7 @@ Comparison
.. _COMPARE: .. _COMPARE:
:: .. code-block:: cmake
string(COMPARE LESS <string1> <string2> <output variable>) string(COMPARE LESS <string1> <string2> <output variable>)
string(COMPARE GREATER <string1> <string2> <output variable>) string(COMPARE GREATER <string1> <string2> <output variable>)
@@ -292,7 +292,7 @@ Hashing
.. _`HASH`: .. _`HASH`:
:: .. code-block:: cmake
string(<HASH> <output variable> <input>) string(<HASH> <output variable> <input>)
@@ -325,7 +325,7 @@ Generation
.. _ASCII: .. _ASCII:
:: .. code-block:: cmake
string(ASCII <number> [<number> ...] <output variable>) string(ASCII <number> [<number> ...] <output variable>)
@@ -333,7 +333,7 @@ Convert all numbers into corresponding ASCII characters.
.. _CONFIGURE: .. _CONFIGURE:
:: .. code-block:: cmake
string(CONFIGURE <string1> <output variable> string(CONFIGURE <string1> <output variable>
[@ONLY] [ESCAPE_QUOTES]) [@ONLY] [ESCAPE_QUOTES])
@@ -342,7 +342,7 @@ Transform a string like :command:`configure_file` transforms a file.
.. _MAKE_C_IDENTIFIER: .. _MAKE_C_IDENTIFIER:
:: .. code-block:: cmake
string(MAKE_C_IDENTIFIER <input string> <output variable>) string(MAKE_C_IDENTIFIER <input string> <output variable>)
@@ -353,7 +353,7 @@ the result.
.. _RANDOM: .. _RANDOM:
:: .. code-block:: cmake
string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
[RANDOM_SEED <seed>] <output variable>) [RANDOM_SEED <seed>] <output variable>)
@@ -366,7 +366,7 @@ random number generator.
.. _TIMESTAMP: .. _TIMESTAMP:
:: .. code-block:: cmake
string(TIMESTAMP <output variable> [<format string>] [UTC]) string(TIMESTAMP <output variable> [<format string>] [UTC])
@@ -421,7 +421,7 @@ If no explicit ``<format string>`` is given it will default to:
.. _UUID: .. _UUID:
:: .. code-block:: cmake
string(UUID <output variable> NAMESPACE <namespace> NAME <name> string(UUID <output variable> NAMESPACE <namespace> NAME <name>
TYPE <MD5|SHA1> [UPPER]) TYPE <MD5|SHA1> [UPPER])

4
Help/command/unset.rst
View File

@@ -3,7 +3,7 @@ unset
Unset a variable, cache variable, or environment variable. Unset a variable, cache variable, or environment variable.
:: .. code-block:: cmake
unset(<variable> [CACHE | PARENT_SCOPE]) unset(<variable> [CACHE | PARENT_SCOPE])
@@ -24,7 +24,7 @@ for further details.
``<variable>`` can be an environment variable such as: ``<variable>`` can be an environment variable such as:
:: .. code-block:: cmake
unset(ENV{LD_LIBRARY_PATH}) unset(ENV{LD_LIBRARY_PATH})

14
Help/command/variable_watch.rst
View File

@@ -3,11 +3,13 @@ variable_watch
Watch the CMake variable for change. Watch the CMake variable for change.
:: .. code-block:: cmake
variable_watch(<variable name> [<command to execute>]) variable_watch(<variable> [<command>])
If the specified variable changes, the message will be printed about If the specified ``<variable>`` changes, a message will be printed
the variable being changed. If the command is specified, the command to inform about the change.
will be executed. The command will receive the following arguments:
COMMAND(<variable> <access> <value> <current list file> <stack>) Additionally, if ``<command>`` is given, this command will be executed.
The command will receive the following arguments:
``COMMAND(<variable> <access> <value> <current_list_file> <stack>)``

24
Help/command/while.rst
View File

@@ -3,15 +3,23 @@ while
Evaluate a group of commands while a condition is true Evaluate a group of commands while a condition is true
:: .. code-block:: cmake
while(condition) while(<condition>)
COMMAND1(ARGS ...) <commands>
COMMAND2(ARGS ...) endwhile()
...
endwhile(condition)
All commands between while and the matching :command:`endwhile` are recorded All commands between while and the matching :command:`endwhile` are recorded
without being invoked. Once the :command:`endwhile` is evaluated, the without being invoked. Once the :command:`endwhile` is evaluated, the
recorded list of commands is invoked as long as the condition is true. The recorded list of commands is invoked as long as the ``<condition>`` is true.
condition is evaluated using the same logic as the :command:`if` command.
The ``<condition>`` has the same syntax and is evaluated using the same logic
as described at length for the :command:`if` command.
The commands :command:`break` and :command:`continue` provide means to
escape from the normal control flow.
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.