summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2018-10-24 14:39:28 (GMT)
committerKitware Robot <kwrobot@kitware.com>2018-10-24 14:39:39 (GMT)
commit008cb6aa991a515cd31a9b7e6a5837555ff2d43a (patch)
tree1c1b234a3d67c6426efcacdae816172ccb388801
parent2296ede5ad67ace711f3f9c2dff33ea1f9b9aeb4 (diff)
parentc2efb3efcd083523a73a2a9721b7101fbfc0fe0f (diff)
downloadCMake-008cb6aa991a515cd31a9b7e6a5837555ff2d43a.zip
CMake-008cb6aa991a515cd31a9b7e6a5837555ff2d43a.tar.gz
CMake-008cb6aa991a515cd31a9b7e6a5837555ff2d43a.tar.bz2
Merge topic 'scripting-commands'
c2efb3efcd Help: Revise docs on Scripting Commands Acked-by: Kitware Robot <kwrobot@kitware.com> Merge-request: !2504
-rw-r--r--Help/command/break.rst4
-rw-r--r--Help/command/cmake_host_system_information.rst2
-rw-r--r--Help/command/cmake_minimum_required.rst16
-rw-r--r--Help/command/cmake_parse_arguments.rst22
-rw-r--r--Help/command/cmake_policy.rst12
-rw-r--r--Help/command/configure_file.rst22
-rw-r--r--Help/command/continue.rst6
-rw-r--r--Help/command/else.rst4
-rw-r--r--Help/command/elseif.rst9
-rw-r--r--Help/command/endforeach.rst8
-rw-r--r--Help/command/endfunction.rst8
-rw-r--r--Help/command/endif.rst8
-rw-r--r--Help/command/endmacro.rst8
-rw-r--r--Help/command/endwhile.rst8
-rw-r--r--Help/command/file.rst32
-rw-r--r--Help/command/find_package.rst10
-rw-r--r--Help/command/foreach.rst99
-rw-r--r--Help/command/function.rst38
-rw-r--r--Help/command/get_cmake_property.rst12
-rw-r--r--Help/command/get_directory_property.rst6
-rw-r--r--Help/command/get_filename_component.rst30
-rw-r--r--Help/command/get_property.rst20
-rw-r--r--Help/command/if.rst25
-rw-r--r--Help/command/include.rst10
-rw-r--r--Help/command/include_guard.rst2
-rw-r--r--Help/command/list.rst60
-rw-r--r--Help/command/macro.rst36
-rw-r--r--Help/command/mark_as_advanced.rst27
-rw-r--r--Help/command/math.rst40
-rw-r--r--Help/command/message.rst2
-rw-r--r--Help/command/option.rst15
-rw-r--r--Help/command/return.rst7
-rw-r--r--Help/command/separate_arguments.rst46
-rw-r--r--Help/command/set.rst12
-rw-r--r--Help/command/set_directory_properties.rst8
-rw-r--r--Help/command/set_property.rst27
-rw-r--r--Help/command/site_name.rst2
-rw-r--r--Help/command/string.rst46
-rw-r--r--Help/command/unset.rst4
-rw-r--r--Help/command/variable_watch.rst14
-rw-r--r--Help/command/while.rst24
41 files changed, 472 insertions, 319 deletions
diff --git a/Help/command/break.rst b/Help/command/break.rst
index fc2cd3c..4875a2b 100644
--- a/Help/command/break.rst
+++ b/Help/command/break.rst
@@ -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.
diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst
index 2dee93a..2e9563a 100644
--- a/Help/command/cmake_host_system_information.rst
+++ b/Help/command/cmake_host_system_information.rst
@@ -3,7 +3,7 @@ cmake_host_system_information
Query host system specific information.
-::
+.. code-block:: cmake
cmake_host_system_information(RESULT <variable> QUERY <key> ...)
diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst
index 2f1ab60..e6ebcf0 100644
--- a/Help/command/cmake_minimum_required.rst
+++ b/Help/command/cmake_minimum_required.rst
@@ -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>])
diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst
index efbef54..c8327e2 100644
--- a/Help/command/cmake_parse_arguments.rst
+++ b/Help/command/cmake_parse_arguments.rst
@@ -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>)
+
+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...``.
+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,
diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst
index c3f7cfb..a80f982 100644
--- a/Help/command/cmake_policy.rst
+++ b/Help/command/cmake_policy.rst
@@ -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)
diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst
index e08c573..29e85bd 100644
--- a/Help/command/configure_file.rst
+++ b/Help/command/configure_file.rst
@@ -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
diff --git a/Help/command/continue.rst b/Help/command/continue.rst
index 1c7d673..31c7089 100644
--- a/Help/command/continue.rst
+++ b/Help/command/continue.rst
@@ -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.
diff --git a/Help/command/else.rst b/Help/command/else.rst
index 0e5a198..a98fcd8 100644
--- a/Help/command/else.rst
+++ b/Help/command/else.rst
@@ -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.
diff --git a/Help/command/elseif.rst b/Help/command/elseif.rst
index 9a8dfed..6bf8646 100644
--- a/Help/command/elseif.rst
+++ b/Help/command/elseif.rst
@@ -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>``.
diff --git a/Help/command/endforeach.rst b/Help/command/endforeach.rst
index 9af972b..fd923d5 100644
--- a/Help/command/endforeach.rst
+++ b/Help/command/endforeach.rst
@@ -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.
diff --git a/Help/command/endfunction.rst b/Help/command/endfunction.rst
index 6cc196c..e27129d 100644
--- a/Help/command/endfunction.rst
+++ b/Help/command/endfunction.rst
@@ -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.
diff --git a/Help/command/endif.rst b/Help/command/endif.rst
index a0163bf..fc4f038 100644
--- a/Help/command/endif.rst
+++ b/Help/command/endif.rst
@@ -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.
diff --git a/Help/command/endmacro.rst b/Help/command/endmacro.rst
index 47327a7..4290ba7 100644
--- a/Help/command/endmacro.rst
+++ b/Help/command/endmacro.rst
@@ -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.
diff --git a/Help/command/endwhile.rst b/Help/command/endwhile.rst
index 798c20e..5ef585b 100644
--- a/Help/command/endwhile.rst
+++ b/Help/command/endwhile.rst
@@ -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.
diff --git a/Help/command/file.rst b/Help/command/file.rst
index d4a6006..f5279c0 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -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>]
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index 3ad571c..3ae9c2d 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -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)
diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst
index 106ba73..ae2afb2 100644
--- a/Help/command/foreach.rst
+++ b/Help/command/foreach.rst
@@ -3,45 +3,82 @@ foreach
Evaluate a group of commands for each value in a list.
-::
+.. code-block:: cmake
- foreach(loop_var arg1 arg2 ...)
- COMMAND1(ARGS ...)
- COMMAND2(ARGS ...)
- ...
- endforeach(loop_var)
+ foreach(<loop_var> <items>)
+ <commands>
+ endforeach()
-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.
+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.
- foreach(loop_var RANGE total)
- foreach(loop_var RANGE start stop [step])
+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.
-Foreach can also iterate over a generated range of numbers. There are
-three types of this iteration:
+.. code-block:: cmake
-* When specifying single number, the range will have elements [0, ... to
- "total"] (inclusive).
+ foreach(<loop_var> RANGE <stop>)
-* When specifying two numbers, the range will have elements from the
- first number to the second number (inclusive).
+In this variant, ``foreach`` iterates over the numbers
+0, 1, ... up to (and including) the nonnegative integer ``<stop>``.
-* The third optional number is the increment used to iterate from the
- first number to the second number (inclusive).
+.. 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>]])
- foreach(loop_var IN [LISTS [list1 [...]]]
- [ITEMS [item1 [...]]])
+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
+::
-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
diff --git a/Help/command/function.rst b/Help/command/function.rst
index 7ffdfee..4a223b4 100644
--- a/Help/command/function.rst
+++ b/Help/command/function.rst
@@ -1,27 +1,29 @@
function
--------
-Start recording a function for later invocation as a command::
-
- function(<name> [arg1 [arg2 [arg3 ...]]])
- COMMAND1(ARGS ...)
- COMMAND2(ARGS ...)
- ...
- endfunction(<name>)
-
-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.
+Start recording a function for later invocation as a command.
+
+.. 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.
+
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.
diff --git a/Help/command/get_cmake_property.rst b/Help/command/get_cmake_property.rst
index 497ab4e..58bf741 100644
--- a/Help/command/get_cmake_property.rst
+++ b/Help/command/get_cmake_property.rst
@@ -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.
diff --git a/Help/command/get_directory_property.rst b/Help/command/get_directory_property.rst
index bf8349c..218efa9 100644
--- a/Help/command/get_directory_property.rst
+++ b/Help/command/get_directory_property.rst
@@ -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>)
diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst
index f11c0fc..3e3c9c3 100644
--- a/Help/command/get_filename_component.rst
+++ b/Help/command/get_filename_component.rst
@@ -3,13 +3,11 @@ get_filename_component
Get a specific component of a full filename.
-------------------------------------------------------------------------------
+.. code-block:: cmake
-::
-
- get_filename_component(<VAR> <FileName> <COMP> [CACHE])
+ get_filename_component(<var> <FileName> <mode> [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>
- <COMP> [BASE_DIR <BASE_DIR>]
- [CACHE])
+ get_filename_component(<var> <FileName> <mode> [BASE_DIR <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.
diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst
index 8b85f7d..c0f9b46 100644
--- a/Help/command/get_property.rst
+++ b/Help/command/get_property.rst
@@ -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
diff --git a/Help/command/if.rst b/Help/command/if.rst
index 8abe9ba..4781f35 100644
--- a/Help/command/if.rst
+++ b/Help/command/if.rst
@@ -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
+
+.. code-block:: cmake
- if(var1)
+ 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
+
+.. code-block:: cmake
- if(var2)
+ if(var2)
which is true because ``var2`` is defined to "var1" which is not a false
constant.
diff --git a/Help/command/include.rst b/Help/command/include.rst
index eeca4c6..80968da 100644
--- a/Help/command/include.rst
+++ b/Help/command/include.rst
@@ -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`,
diff --git a/Help/command/include_guard.rst b/Help/command/include_guard.rst
index 62cce22..877aa86 100644
--- a/Help/command/include_guard.rst
+++ b/Help/command/include_guard.rst
@@ -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])
diff --git a/Help/command/list.rst b/Help/command/list.rst
index 2357a9b..bfcdf34 100644
--- a/Help/command/list.rst
+++ b/Help/command/list.rst
@@ -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>])
diff --git a/Help/command/macro.rst b/Help/command/macro.rst
index 6bee69c..2746b1b 100644
--- a/Help/command/macro.rst
+++ b/Help/command/macro.rst
@@ -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()
diff --git a/Help/command/mark_as_advanced.rst b/Help/command/mark_as_advanced.rst
index c3f94fc..5712fb4 100644
--- a/Help/command/mark_as_advanced.rst
+++ b/Help/command/mark_as_advanced.rst
@@ -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.
diff --git a/Help/command/math.rst b/Help/command/math.rst
index 63af931..4fa55f6 100644
--- a/Help/command/math.rst
+++ b/Help/command/math.rst
@@ -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.
+
+Hexadecimal numbers are recognized when prefixed with "0x", as in C code.
-Numeric constants are evaluated in decimal or hexadecimal representation.
+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``
+ 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.
- HEXADECIMAL = Result in output variable will be formatted in C code
- Hexadecimal notation.
- DECIMAL = Result in output variable will be formatted in decimal notation.
+For example
-For example::
+.. code-block:: cmake
- 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"
+ 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"
diff --git a/Help/command/message.rst b/Help/command/message.rst
index 04c62fd..2b4b1aa 100644
--- a/Help/command/message.rst
+++ b/Help/command/message.rst
@@ -3,7 +3,7 @@ message
Display a message to the user.
-::
+.. code-block:: cmake
message([<mode>] "message to display" ...)
diff --git a/Help/command/option.rst b/Help/command/option.rst
index 4fabb87..8956307 100644
--- a/Help/command/option.rst
+++ b/Help/command/option.rst
@@ -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`.
diff --git a/Help/command/return.rst b/Help/command/return.rst
index e49fb3c..830992c 100644
--- a/Help/command/return.rst
+++ b/Help/command/return.rst
@@ -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()``.
diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst
index 47982a5..fbca859 100644
--- a/Help/command/separate_arguments.rst
+++ b/Help/command/separate_arguments.rst
@@ -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>)
diff --git a/Help/command/set.rst b/Help/command/set.rst
index b24ebef..d57b177 100644
--- a/Help/command/set.rst
+++ b/Help/command/set.rst
@@ -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.
diff --git a/Help/command/set_directory_properties.rst b/Help/command/set_directory_properties.rst
index 42e7fd7..cc71522 100644
--- a/Help/command/set_directory_properties.rst
+++ b/Help/command/set_directory_properties.rst
@@ -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.
diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst
index c89e1ce..2d270ec 100644
--- a/Help/command/set_property.rst
+++ b/Help/command/set_property.rst
@@ -3,21 +3,22 @@ set_property
Set a named property in a given scope.
-::
-
- set_property(<GLOBAL |
- DIRECTORY [dir] |
- TARGET [target1 [target2 ...]] |
- SOURCE [src1 [src2 ...]] |
- INSTALL [file1 [file2 ...]] |
- TEST [test1 [test2 ...]] |
- CACHE [entry1 [entry2 ...]]>
+.. code-block:: cmake
+
+ 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.
diff --git a/Help/command/site_name.rst b/Help/command/site_name.rst
index e17c1ee..1bcaead 100644
--- a/Help/command/site_name.rst
+++ b/Help/command/site_name.rst
@@ -3,6 +3,6 @@ site_name
Set the given variable to the name of the computer.
-::
+.. code-block:: cmake
site_name(variable)
diff --git a/Help/command/string.rst b/Help/command/string.rst
index cc18069..893fb43 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -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])
diff --git a/Help/command/unset.rst b/Help/command/unset.rst
index c19dd31..1a5e49f 100644
--- a/Help/command/unset.rst
+++ b/Help/command/unset.rst
@@ -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})
diff --git a/Help/command/variable_watch.rst b/Help/command/variable_watch.rst
index a2df058..ce69bcf 100644
--- a/Help/command/variable_watch.rst
+++ b/Help/command/variable_watch.rst
@@ -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>)``
diff --git a/Help/command/while.rst b/Help/command/while.rst
index 7509da3..a4957c1 100644
--- a/Help/command/while.rst
+++ b/Help/command/while.rst
@@ -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.