reactos/CMake
1
0
Fork 0
mirror of https://github.com/reactos/CMake.git synced 2025-02-02 01:55:03 +00:00
Code Issues Actions 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
Show Stats 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.
::
.. code-block:: cmake
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.

2
Help/command/cmake_host_system_information.rst
View File

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

16
Help/command/cmake_minimum_required.rst
View File

@ -1,11 +1,15 @@
cmake_minimum_required
----------------------
Set the minimum required version of cmake for a project and
update `Policy Settings`_ to match the version given::
Require a minimum version of cmake.
.. code-block:: cmake
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
``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.
When a ``<min>`` version higher than 2.4 is specified the command
implicitly invokes::
implicitly invokes
.. code-block:: cmake
cmake_policy(VERSION <min>[...<max>])
which sets CMake policies based on the range of versions specified.
When a ``<min>`` version 2.4 or lower is given the command implicitly
invokes::
invokes
.. code-block:: cmake
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`` is intended to be used in macros or functions for
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.
Parse function or macro arguments.
::
.. code-block:: cmake
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>
<multi_value_keywords>)
cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
<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`.
The ``PARSE_ARGV`` signature is only for use in a :command:`function`
body. In this case the arguments that are parsed come from the
``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 ``<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``
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>])
@ -50,7 +52,7 @@ command implicitly calls ``cmake_policy(VERSION)`` too.
Setting Policies Explicitly
^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
cmake_policy(SET CMP<NNNN> NEW)
cmake_policy(SET CMP<NNNN> OLD)
@ -66,7 +68,7 @@ policy state to ``NEW``.
Checking Policy Settings
^^^^^^^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
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
(see also policy :policy:`CMP0011`).
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(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.
::
.. code-block:: cmake
configure_file(<input> <output>
[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
file content. Each variable reference will be replaced with the
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 ...
will be replaced with either::
will be replaced with either
.. code-block:: c
#define VAR ...
or::
or
.. code-block:: c
/* #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
indented using spaces and/or tabs between the ``#`` character
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
# 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 1

6
Help/command/continue.rst
View File

@ -3,10 +3,12 @@ continue
Continue to the top of enclosing foreach or while loop.
::
.. code-block:: cmake
continue()
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
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.
::
.. code-block:: cmake
else(expression)
else([<condition>])
See the :command:`if` command.

9
Help/command/elseif.rst
View File

@ -1,10 +1,11 @@
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.
::
.. code-block:: cmake
endforeach(expression)
endforeach([<loop_var>])
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.
::
.. code-block:: cmake
endfunction(expression)
endfunction([<name>])
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.
::
.. code-block:: cmake
endif(expression)
endif([<condition>])
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.
::
.. code-block:: cmake
endmacro(expression)
endmacro([<name>])
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.
::
.. code-block:: cmake
endwhile(expression)
endwhile([<condition>])
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:
::
.. code-block:: cmake
file(READ <filename> <variable>
[OFFSET <offset>] [LIMIT <max-in>] [HEX])
@ -54,7 +54,7 @@ be converted to a hexadecimal representation (useful for binary data).
.. _STRINGS:
::
.. code-block:: cmake
file(STRINGS <filename> <variable> [<options>...])
@ -105,7 +105,7 @@ from the input file.
.. _HASH:
::
.. code-block:: cmake
file(<HASH> <filename> <variable>)
@ -116,7 +116,7 @@ command.
.. _TIMESTAMP:
::
.. code-block:: cmake
file(TIMESTAMP <filename> <variable> [<format>] [UTC])
@ -133,7 +133,7 @@ Writing
.. _WRITE:
.. _APPEND:
::
.. code-block:: cmake
file(WRITE <filename> <content>...)
file(APPEND <filename> <content>...)
@ -150,7 +150,7 @@ to update the file only when its content changes.
.. _TOUCH:
.. _TOUCH_NOCREATE:
::
.. code-block:: cmake
file(TOUCH [<files>...])
file(TOUCH_NOCREATE [<files>...])
@ -167,7 +167,7 @@ modified.
.. _GENERATE:
::
.. code-block:: cmake
file(GENERATE OUTPUT output-file
<INPUT input-file|CONTENT content>
@ -217,7 +217,7 @@ Filesystem
.. _GLOB:
.. _GLOB_RECURSE:
::
.. code-block:: cmake
file(GLOB <variable>
[LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
@ -272,7 +272,7 @@ Examples of recursive globbing include::
.. _RENAME:
::
.. code-block:: cmake
file(RENAME <oldname> <newname>)
@ -282,7 +282,7 @@ Move a file or directory within a filesystem from ``<oldname>`` to
.. _REMOVE:
.. _REMOVE_RECURSE:
::
.. code-block:: cmake
file(REMOVE [<files>...])
file(REMOVE_RECURSE [<files>...])
@ -293,7 +293,7 @@ given file does not exist.
.. _MAKE_DIRECTORY:
::
.. code-block:: cmake
file(MAKE_DIRECTORY [<directories>...])
@ -302,7 +302,7 @@ Create the given directories and their parents as needed.
.. _COPY:
.. _INSTALL:
::
.. code-block:: cmake
file(<COPY|INSTALL> <files>... DESTINATION <dir>
[FILE_PERMISSIONS <permissions>...]
@ -338,7 +338,7 @@ Path Conversion
.. _RELATIVE_PATH:
::
.. code-block:: cmake
file(RELATIVE_PATH <variable> <directory> <file>)
@ -348,7 +348,7 @@ store it in the ``<variable>``.
.. _TO_CMAKE_PATH:
.. _TO_NATIVE_PATH:
::
.. code-block:: cmake
file(TO_CMAKE_PATH "<path>" <variable>)
file(TO_NATIVE_PATH "<path>" <variable>)
@ -370,7 +370,7 @@ Transfer
.. _DOWNLOAD:
.. _UPLOAD:
::
.. code-block:: cmake
file(DOWNLOAD <url> <file> [<options>...])
file(UPLOAD <file> <url> [<options>...])
@ -460,7 +460,7 @@ Locking
.. _LOCK:
::
.. code-block:: cmake
file(LOCK <path> [DIRECTORY] [RELEASE]
[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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
[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
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]
[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
the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
: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_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.
.. 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 ...)
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endforeach(loop_var)
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 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.
-- X=0
-- X=1
-- X=2
-- X=3
-- X=4 5
-- X=6
-- X=7
-- X=8

34
Help/command/function.rst
View File

@ -1,27 +1,29 @@
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 ...]]])
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endfunction(<name>)
.. code-block:: cmake
function(<name> [<arg1> ...])
<commands>
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
``ARGC`` variable which will be set to the number of arguments passed
into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which
will have the actual values of the arguments passed in.
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
argument.
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
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
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.
::
.. 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
stored in the variable ``VAR``. If the property is not found, ``VAR``
will be set to "NOTFOUND". See the :manual:`cmake-properties(7)` manual
for available properties.
Gets a global property from the CMake instance. The value of
the ``<property>`` is stored in the variable ``<var>``.
If the property is not found, ``<var>`` will be set to ``"NOTFOUND"``.
See the :manual:`cmake-properties(7)` manual for available properties.
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.
::
.. code-block:: cmake
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
to retrieve the property value instead of the current directory.
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
:command:`define_property` command.
::
.. code-block:: cmake
get_directory_property(<variable> [DIRECTORY <dir>]
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.
------------------------------------------------------------------------------
.. code-block:: cmake
::
get_filename_component(<var> <FileName> <mode> [CACHE])
get_filename_component(<VAR> <FileName> <COMP> [CACHE])
Set ``<VAR>`` to a component of ``<FileName>``, where ``<COMP>`` is one of:
Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` 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.
------------------------------------------------------------------------------
.. code-block:: cmake
::
get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
get_filename_component(<VAR> <FileName>
<COMP> [BASE_DIR <BASE_DIR>]
[CACHE])
Set ``<VAR>`` to the absolute path of ``<FileName>``, where ``<COMP>`` is one
Sets ``<var>`` to the absolute path of ``<FileName>``, where ``<mode>`` is one
of:
::
@ -41,7 +35,7 @@ of:
REALPATH = Full path to existing file with symlinks resolved
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
: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
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
left as a full path. If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then
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.

20
Help/command/get_property.rst
View File

@ -3,32 +3,33 @@ get_property
Get a property.
::
.. code-block:: cmake
get_property(<variable>
<GLOBAL |
DIRECTORY [dir] |
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
VARIABLE>
VARIABLE >
PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
Get one property from one object in a scope. The first argument
specifies the variable in which to store the result. The second
argument determines the scope from which to get the property. It must
be one of the following:
Gets one property from one object in a scope.
The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the property.
It must be one of the following:
``GLOBAL``
Scope is unique and does not accept a name.
``DIRECTORY``
Scope defaults to the current directory but another
directory (already processed by CMake) may be named by full or
relative path.
directory (already processed by CMake) may be named by the
full or relative path ``<dir>``.
``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
whether the property has been defined such as with the
:command:`define_property` command.
If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a
string containing documentation for the requested property. If
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
^^^^^^^^
::
.. code-block:: cmake
if(<condition>)
<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``
block are executed.
Per legacy, the ``else`` and ``endif`` clause may also have a ``condition`` argument,
which then must be a verbatim repeat of the argument of the opening ``if`` clause.
Per legacy, the :command:`else` and :command:`elseif` commands admit
an optional ``<condition>`` argument.
If used, it must be a verbatim
repeat of the argument of the opening
``if`` command.
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
variables named by its arguments as shown in the above signatures.
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(var2 "var1")
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
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
constant.

10
Help/command/include.rst
View File

@ -3,16 +3,16 @@ include
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])
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``
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
which has been included or NOTFOUND if it failed.
``RESULT_VARIABLE`` is given the variable ``<var>`` will be set to the
full filename which has been included or ``NOTFOUND`` if it failed.
If a module is specified instead of a file, the file with name
``<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.
::
.. code-block:: cmake
include_guard([DIRECTORY|GLOBAL])

60
Help/command/list.rst
View File

@ -64,7 +64,7 @@ Reading
.. _LENGTH:
::
.. code-block:: cmake
list(LENGTH <list> <output variable>)
@ -72,7 +72,7 @@ Returns the list's length.
.. _GET:
::
.. code-block:: cmake
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:
::
.. code-block:: cmake
list(JOIN <list> <glue> <output variable>)
@ -90,7 +90,7 @@ from :command:`string` command.
.. _SUBLIST:
::
.. code-block:: cmake
list(SUBLIST <list> <begin> <length> <output variable>)
@ -104,7 +104,7 @@ Search
.. _FIND:
::
.. code-block:: cmake
list(FIND <list> <value> <output variable>)
@ -116,7 +116,7 @@ Modification
.. _APPEND:
::
.. code-block:: cmake
list(APPEND <list> [<element> ...])
@ -124,7 +124,7 @@ Appends elements to the list.
.. _FILTER:
::
.. code-block:: cmake
list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
@ -136,7 +136,7 @@ For more information on regular expressions see also the
.. _INSERT:
::
.. code-block:: cmake
list(INSERT <list> <element_index> <element> [<element> ...])
@ -144,7 +144,7 @@ Inserts elements to the list to the specified location.
.. _REMOVE_ITEM:
::
.. code-block:: cmake
list(REMOVE_ITEM <list> <value> [<value> ...])
@ -152,7 +152,7 @@ Removes the given items from the list.
.. _REMOVE_AT:
::
.. code-block:: cmake
list(REMOVE_AT <list> <index> [<index> ...])
@ -160,7 +160,7 @@ Removes items at given indices from the list.
.. _REMOVE_DUPLICATES:
::
.. code-block:: cmake
list(REMOVE_DUPLICATES <list>)
@ -168,7 +168,7 @@ Removes duplicated items in the list.
.. _TRANSFORM:
::
.. code-block:: cmake
list(TRANSFORM <list> <ACTION> [<SELECTOR>]
[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:
``APPEND``, ``PREPEND``: Append, prepend specified value to each element of
the list. ::
the list.
.. code-block:: cmake
list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower
characters. ::
characters.
.. code-block:: cmake
list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
``STRIP``: Remove leading and trailing spaces from each element of the
list. ::
list.
.. code-block:: cmake
list(TRANSFORM <list> STRIP ...)
``GENEX_STRIP``: Strip any
: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 ...)
``REPLACE``: Match the regular expression as many times as possible and
substitute the replacement expression for the match for each element
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>
<replace_expression> ...)
@ -223,17 +233,23 @@ type of selector can be specified at a time.
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> ...] ...)
``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>] ...)
``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> ...)
@ -243,7 +259,7 @@ Ordering
.. _REVERSE:
::
.. code-block:: cmake
list(REVERSE <list>)
@ -251,7 +267,7 @@ Reverses the contents of the list in-place.
.. _SORT:
::
.. code-block:: cmake
list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])

36
Help/command/macro.rst
View File

@ -1,27 +1,29 @@
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 ...]]])
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
.. code-block:: cmake
macro(<name> [<arg1> ...])
<commands>
endmacro(<name>)
Define a macro named ``<name>`` that takes arguments named ``arg1``,
``arg2``, ``arg3``, (...).
Defines a macro named ``<name>`` that takes arguments
named ``<arg1>``, ...
Commands listed after macro, but before the matching
:command:`endmacro()`, are not invoked until the macro is invoked.
When it is invoked, the commands recorded in the macro are first
modified by replacing formal parameters (``${arg1}``) with the arguments
passed, and then invoked as normal commands.
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
values ``${ARGC}`` which will be set to the number of arguments passed
into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``,
... which will have the actual values of the arguments passed in.
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
argument.
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
not variables in the usual CMake sense. They are string
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(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)``.
In the last case, you can use ``foreach(loop_var ${ARGN})`` but this
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}")
foreach(loop_var IN LISTS list_var)
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
existing variable instead of the arguments. For example::
existing variable instead of the arguments. For example:
.. code-block:: cmake
macro(_BAR)
foreach(arg IN LISTS ARGN)
[...]
<commands>
endforeach()
endmacro()

27
Help/command/mark_as_advanced.rst
View File

@ -3,17 +3,22 @@ mark_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
will not be displayed in any of the cmake GUIs unless the show
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.
Sets the advanced/non-advanced state of the named
cached variables.
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
----
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
output variable. Example mathematical expression is ``5 * (10 + 13)``.
Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the
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 ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``,
``^``, ``~``, ``<<``, ``>>``, and ``(...)``. They have the same meaning
as they do in C code.
``^``, ``~``, ``<<``, ``>>``, and ``(...)``; they have the same meaning
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" ,
where ``<format>`` is one of:
::
The result is formatted according to the option ``OUTPUT_FORMAT``,
where ``<format>`` is one of
HEXADECIMAL = Result in output variable will be formatted in C code
Hexadecimal notation.
DECIMAL = Result in output variable will be formatted in decimal notation.
``HEXADECIMAL``
Hexadecimal notation as in C code, i. e. starting with "0x".
``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"
math(EXPR value "100 * 0xA" HEXADECIMAL) results in value is set to "0x3e8"
.. code-block:: cmake
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.
::
.. code-block:: cmake
message([<mode>] "message to display" ...)

15
Help/command/option.rst
View File

@ -1,17 +1,16 @@
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"
[initial value])
option(<variable> "<help_text>" [value])
Provide an option for the user to select as ``ON`` or ``OFF``. If no
initial value is provided, ``OFF`` is used. If the option is already
set as a normal variable then the command does nothing
(see policy :policy:`CMP0077`).
Provides an option for the user to select as ``ON`` or ``OFF``.
If no initial ``<value>`` is provided, ``OFF`` is used.
If ``<variable>`` is already set as a normal variable
then the command does nothing (see policy :policy:`CMP0077`).
If you have options that depend on the values of other options, see
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.
::
.. code-block:: cmake
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``,
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.
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
------------------
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
stores a semicolon-separated list of the arguments in ``<var>``. The
entire command line must be given in one "<args>" argument.
Parses a space-separated string ``<args>`` into a list of items,
and stores this list in semicolon-separated standard form in ``<variable>``.
The ``UNIX_COMMAND`` mode separates arguments by unquoted whitespace. It
recognizes both single-quote and double-quote pairs. A backslash
escapes the next literal character (``\"`` is ``"``); there are no special
escapes (``\n`` is just ``n``).
This function is intended for parsing command-line arguments.
The entire command line must be passed as one string in the
argument ``<args>``.
The ``WINDOWS_COMMAND`` mode parses a Windows command-line 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.
The exact parsing rules depend on the operating system.
They are specified by the ``<mode>`` argument which must
be one of the following keywords:
The ``NATIVE_COMMAND`` mode parses a Windows command-line if the host
system is Windows, and a UNIX command-line otherwise.
``UNIX_COMMAND``
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
::
.. code-block:: cmake
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
^^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
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
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
^^^^^^^^^^^^^^^
::
.. code-block:: cmake
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
existing cache entries by default. Use the ``FORCE`` option to
overwrite existing entries.
@ -84,8 +84,8 @@ current working directory and convert it to an absolute path.
Set Environment Variable
^^^^^^^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
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 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
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.
::
.. code-block:: cmake
set_property(<GLOBAL |
DIRECTORY [dir] |
TARGET [target1 [target2 ...]] |
SOURCE [src1 [src2 ...]] |
INSTALL [file1 [file2 ...]] |
TEST [test1 [test2 ...]] |
CACHE [entry1 [entry2 ...]]>
set_property(<GLOBAL |
DIRECTORY [<dir>] |
TARGET [<target1> ...] |
SOURCE [<src1> ...] |
INSTALL [<file1> ...] |
TEST [<test1> ...] |
CACHE [<entry1> ...] >
[APPEND] [APPEND_STRING]
PROPERTY <name> [value1 [value2 ...]])
PROPERTY <name> [value1 ...])
Set one property on zero or more objects of a scope. The first
argument determines the scope in which the property is set. It must
be one of the following:
Sets one property on zero or more objects of a scope.
The first argument determines the scope in which the property is set.
It must be one of the following:
``GLOBAL``
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.
::
.. code-block:: cmake
site_name(variable)

46
Help/command/string.rst
View File

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

4
Help/command/unset.rst
View File

@ -3,7 +3,7 @@ unset
Unset a variable, cache variable, or environment variable.
::
.. code-block:: cmake
unset(<variable> [CACHE | PARENT_SCOPE])
@ -24,7 +24,7 @@ for further details.
``<variable>`` can be an environment variable such as:
::
.. code-block:: cmake
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.
::
.. 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
the variable being changed. If the command is specified, the command
will be executed. The command will receive the following arguments:
COMMAND(<variable> <access> <value> <current list file> <stack>)
If the specified ``<variable>`` changes, a message will be printed
to inform about the change.
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
::
.. code-block:: cmake
while(condition)
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endwhile(condition)
while(<condition>)
<commands>
endwhile()
All commands between while and the matching :command:`endwhile` are recorded
without being invoked. Once the :command:`endwhile` is evaluated, the
recorded list of commands is invoked as long as the condition is true. The
condition is evaluated using the same logic as the :command:`if` command.
recorded list of commands is invoked as long as the ``<condition>`` is true.
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.