[Cmake-commits] CMake branch, next, updated. v2.8.12.1-5360-g0072ba9
Daniele E. Domenichelli
daniele.domenichelli at gmail.com
Tue Nov 19 11:09:36 EST 2013
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, next has been updated
via 0072ba93394deb607ed645ad54754528884bd337 (commit)
via f0db2e38984c7ac2e2da082b88ec52f378651891 (commit)
from 92908ca87cf4b66afb637bcb3a05612b3ee84fd7 (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 -----------------------------------------------------------------
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=0072ba93394deb607ed645ad54754528884bd337
commit 0072ba93394deb607ed645ad54754528884bd337
Merge: 92908ca f0db2e3
Author: Daniele E. Domenichelli <daniele.domenichelli at gmail.com>
AuthorDate: Tue Nov 19 11:09:32 2013 -0500
Commit: CMake Topic Stage <kwrobot at kitware.com>
CommitDate: Tue Nov 19 11:09:32 2013 -0500
Merge topic 'macro-args-docs' into next
f0db2e3 Help: Document macro argument caveats in more detail
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=f0db2e38984c7ac2e2da082b88ec52f378651891
commit f0db2e38984c7ac2e2da082b88ec52f378651891
Author: Daniele E. Domenichelli <daniele.domenichelli at iit.it>
AuthorDate: Mon Nov 18 14:30:52 2013 +0100
Commit: Brad King <brad.king at kitware.com>
CommitDate: Tue Nov 19 09:01:54 2013 -0500
Help: Document macro argument caveats in more detail
Add notes about macro arguments in the foreach, if, and list commands.
Add a section to the macro command documentation explaining in detail
how macro arguments are not variables.
diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst
index 8f9710c..348ebd8 100644
--- a/Help/command/foreach.rst
+++ b/Help/command/foreach.rst
@@ -42,5 +42,6 @@ three types of this iteration:
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). The ITEMS option ends argument
+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.
diff --git a/Help/command/if.rst b/Help/command/if.rst
index b879ae1..0279be7 100644
--- a/Help/command/if.rst
+++ b/Help/command/if.rst
@@ -166,7 +166,8 @@ major[.minor[.patch[.tweak]]]).
if(DEFINED <variable>)
True if the given variable is defined. It does not matter if the
-variable is true or false just if it has been set.
+variable is true or false just if it has been set. (Note macro
+arguments are not variables.)
::
diff --git a/Help/command/list.rst b/Help/command/list.rst
index f044dba..aeb1e94 100644
--- a/Help/command/list.rst
+++ b/Help/command/list.rst
@@ -50,7 +50,8 @@ propagation.
NOTES: A list in cmake is a ; separated group of strings. To create a
list the set command can be used. For example, set(var a b c d e)
creates a list with a;b;c;d;e, and set(var "a b c d e") creates a
-string or a list with one item in it.
+string or a list with one item in it. (Note macro arguments are not
+variables, and therefore cannot be used in LIST commands.)
When specifying index values, if <element index> is 0 or greater, it
is indexed from the beginning of the list, with 0 representing the
diff --git a/Help/command/macro.rst b/Help/command/macro.rst
index aa16352..258dc50 100644
--- a/Help/command/macro.rst
+++ b/Help/command/macro.rst
@@ -15,19 +15,53 @@ Define a macro named <name> that takes arguments named arg1 arg2 arg3
(...). Commands listed after macro, but before the matching 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
+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
+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
-macro and ${ARGN} holds the list of arguments past the last expected
-argument. 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. If
-you want true CMake variables and/or better CMake scope control you
-should look at the function command.
+Additionally ``${ARGV}`` holds the list of all arguments given to the
+macro and ``${ARGN}`` holds the list of arguments past the last expected
+argument.
See the cmake_policy() command documentation for the behavior of
policies inside macros.
+
+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::
+
+ if(ARGV1) # ARGV1 is not a variable
+ foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
+
+In the first case you can use ``if(${ARGV1})``, in the second case, you can
+use ``foreach(loop_var ${ARGN})`` but this will skip empty arguments.
+If you need to include them, you can use::
+
+ 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::
+
+ macro(_BAR)
+ foreach(arg IN LISTS ARGN)
+ [...]
+ endforeach()
+ endmacro()
+
+ function(_FOO)
+ _bar(x y z)
+ endfunction()
+
+ _foo(a b c)
+
+Will loop over ``a;b;c`` and not over ``x;y;z`` as one might be expecting.
+If you want true CMake variables and/or better CMake scope control you
+should look at the function command.
-----------------------------------------------------------------------
Summary of changes:
Help/command/foreach.rst | 3 +-
Help/command/if.rst | 3 +-
Help/command/list.rst | 3 +-
Help/command/macro.rst | 56 +++++++++++++++++++++++++++++++++++++---------
4 files changed, 51 insertions(+), 14 deletions(-)
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list