This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".
The branch, master has been updated
via da1580b48e84cf1fc3bfb518d7e78b61393a0ef2 (commit)
via 26494d279fa527857139c128464b6e38260a9a0d (commit)
via 3793bed9df0c7f056eaf85c0267088fc8cea647c (commit)
via 008cb6aa991a515cd31a9b7e6a5837555ff2d43a (commit)
via f87d5f13c29a961238ccf623d4954d2d0636adaa (commit)
via 35fe47bd5d9508aa90fd1569eb2eaf3f982ebee5 (commit)
via 8e56e8b28327fbe83562ad7a4e947b2275b1479d (commit)
via d004d8c59a6daa5b27c6e737b687793f51557704 (commit)
via c2efb3efcd083523a73a2a9721b7101fbfc0fe0f (commit)
from 2296ede5ad67ace711f3f9c2dff33ea1f9b9aeb4 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=da1580b48e84cf1fc3bfb518d7e78b61393a0ef2
commit da1580b48e84cf1fc3bfb518d7e78b61393a0ef2
Merge: 26494d2 f87d5f1
Author: Brad King <brad.k...@kitware.com>
AuthorDate: Wed Oct 24 10:42:38 2018 -0400
Commit: Brad King <brad.k...@kitware.com>
CommitDate: Wed Oct 24 10:42:38 2018 -0400
Merge branch 'release-3.13'
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=26494d279fa527857139c128464b6e38260a9a0d
commit 26494d279fa527857139c128464b6e38260a9a0d
Merge: 3793bed 8e56e8b
Author: Brad King <brad.k...@kitware.com>
AuthorDate: Wed Oct 24 14:40:13 2018 +0000
Commit: Kitware Robot <kwro...@kitware.com>
CommitDate: Wed Oct 24 10:41:31 2018 -0400
Merge topic 'vs-csharp-win32-flags'
8e56e8b283 VS: Fix CSharp support for win32res: and win32icon: flags
Acked-by: Kitware Robot <kwro...@kitware.com>
Merge-request: !2516
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=3793bed9df0c7f056eaf85c0267088fc8cea647c
commit 3793bed9df0c7f056eaf85c0267088fc8cea647c
Merge: 008cb6a d004d8c
Author: Brad King <brad.k...@kitware.com>
AuthorDate: Wed Oct 24 14:40:00 2018 +0000
Commit: Kitware Robot <kwro...@kitware.com>
CommitDate: Wed Oct 24 10:40:24 2018 -0400
Merge topic 'vs-csharp-in-custom-target'
d004d8c59a VS: Fix crash on CSharp sources in a custom target
Acked-by: Kitware Robot <kwro...@kitware.com>
Merge-request: !2515
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=008cb6aa991a515cd31a9b7e6a5837555ff2d43a
commit 008cb6aa991a515cd31a9b7e6a5837555ff2d43a
Merge: 2296ede c2efb3e
Author: Brad King <brad.k...@kitware.com>
AuthorDate: Wed Oct 24 14:39:28 2018 +0000
Commit: Kitware Robot <kwro...@kitware.com>
CommitDate: Wed Oct 24 10:39:39 2018 -0400
Merge topic 'scripting-commands'
c2efb3efcd Help: Revise docs on Scripting Commands
Acked-by: Kitware Robot <kwro...@kitware.com>
Merge-request: !2504
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=c2efb3efcd083523a73a2a9721b7101fbfc0fe0f
commit c2efb3efcd083523a73a2a9721b7101fbfc0fe0f
Author: Joachim Wuttke (l) <j.wut...@fz-juelich.de>
AuthorDate: Tue Oct 16 21:50:48 2018 +0200
Commit: Joachim Wuttke (o) <j.wut...@fz-juelich.de>
CommitDate: Tue Oct 23 15:12:10 2018 +0200
Help: Revise docs on Scripting Commands
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
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.
-----------------------------------------------------------------------
Summary of changes:
Help/command/break.rst | 4 +-
Help/command/cmake_host_system_information.rst | 2 +-
Help/command/cmake_minimum_required.rst | 16 +++-
Help/command/cmake_parse_arguments.rst | 22 ++---
Help/command/cmake_policy.rst | 12 ++-
Help/command/configure_file.rst | 22 +++--
Help/command/continue.rst | 6 +-
Help/command/else.rst | 4 +-
Help/command/elseif.rst | 9 +-
Help/command/endforeach.rst | 8 +-
Help/command/endfunction.rst | 8 +-
Help/command/endif.rst | 8 +-
Help/command/endmacro.rst | 8 +-
Help/command/endwhile.rst | 8 +-
Help/command/file.rst | 32 +++----
Help/command/find_package.rst | 10 ++-
Help/command/foreach.rst | 99 +++++++++++++++-------
Help/command/function.rst | 38 +++++----
Help/command/get_cmake_property.rst | 12 +--
Help/command/get_directory_property.rst | 6 +-
Help/command/get_filename_component.rst | 30 +++----
Help/command/get_property.rst | 20 +++--
Help/command/if.rst | 25 ++++--
Help/command/include.rst | 10 +--
Help/command/include_guard.rst | 2 +-
Help/command/list.rst | 60 ++++++++-----
Help/command/macro.rst | 36 +++++---
Help/command/mark_as_advanced.rst | 27 +++---
Help/command/math.rst | 40 +++++----
Help/command/message.rst | 2 +-
Help/command/option.rst | 15 ++--
Help/command/return.rst | 7 +-
Help/command/separate_arguments.rst | 46 ++++++----
Help/command/set.rst | 12 +--
Help/command/set_directory_properties.rst | 8 +-
Help/command/set_property.rst | 27 +++---
Help/command/site_name.rst | 2 +-
Help/command/string.rst | 46 +++++-----
Help/command/unset.rst | 4 +-
Help/command/variable_watch.rst | 14 +--
Help/command/while.rst | 24 ++++--
Source/cmVS10CSharpFlagTable.h | 4 +-
Source/cmVS11CSharpFlagTable.h | 4 +-
Source/cmVS12CSharpFlagTable.h | 4 +-
Source/cmVS140CSharpFlagTable.h | 4 +-
Source/cmVS141CSharpFlagTable.h | 4 +-
Source/cmVisualStudio10TargetGenerator.cxx | 4 +
Tests/CSharpOnly/CMakeLists.txt | 3 +
.../vtkIncluded.cxx => CSharpOnly/empty.cs} | 0
.../install/pattern => CSharpOnly}/empty.txt | 0
50 files changed, 489 insertions(+), 329 deletions(-)
copy Tests/{Wrapping/vtkIncluded.cxx => CSharpOnly/empty.cs} (100%)
copy Tests/{RunCMake/install/pattern => CSharpOnly}/empty.txt (100%)
hooks/post-receive
--
CMake
_______________________________________________
Cmake-commits mailing list
Cmake-commits@cmake.org
https://cmake.org/mailman/listinfo/cmake-commits
