kolan/CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge topic 'macro-function-docs'

Browse Source 
4efef3f7 Help: Clarify that ARGV# beyond ARGC will have an undefined behavior (#15380)
e3363bfb Help: Refine the .rst formatting of macro and function documentation
This commit is contained in:
Brad King 2015-02-27 10:34:40 -05:00 committed by CMake Topic Stage
commit d853cb238c
2 changed files with 50 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
Help/command/function.rst
View File

@ -1,9 +1,7 @@
function function
-------- --------
Start recording a function for later invocation as a command. Start recording a function for later invocation as a command::
::
function(<name> [arg1 [arg2 [arg3 ...]]]) function(<name> [arg1 [arg2 [arg3 ...]]])
COMMAND1(ARGS ...) COMMAND1(ARGS ...)
@ -11,21 +9,28 @@ Start recording a function for later invocation as a command.
... ...
endfunction(<name>) endfunction(<name>)
Define a function named <name> that takes arguments named arg1 arg2 Define a function named ``<name>`` that takes arguments named ``arg1``,
arg3 (...). Commands listed after function, but before the matching ``arg2``, ``arg3``, (...).
endfunction, are not invoked until the function is invoked. When it Commands listed after function, but before the matching
is invoked, the commands recorded in the function are first modified :command:`endfunction()`, are not invoked until the function is invoked.
by replacing formal parameters (${arg1}) with the arguments passed, When it is invoked, the commands recorded in the function are first
and then invoked as normal commands. In addition to referencing the modified by replacing formal parameters (``${arg1}``) with the arguments
formal parameters you can reference the variable ARGC which will be passed, and then invoked as normal commands.
set to the number of arguments passed into the function as well as In addition to referencing the formal parameters you can reference the
ARGV0 ARGV1 ARGV2 ... which will have the actual values of the ``ARGC`` variable which will be set to the number of arguments passed
arguments passed in. This facilitates creating functions with into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which
optional arguments. Additionally ARGV holds the list of all arguments will have the actual values of the arguments passed in.
given to the function and ARGN holds the list of arguments past the This facilitates creating functions with optional arguments.
last expected argument. Additionally ``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
behavior. Checking that ``ARGC`` is greater than ``#`` is the only way
to ensure that ``ARGV#`` was passed to the function as an extra
argument.
A function opens a new scope: see set(var PARENT_SCOPE) for details. A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for
details.
See the cmake_policy() command documentation for the behavior of See the :command:`cmake_policy()` command documentation for the behavior
policies inside functions. of policies inside functions.

43
Help/command/macro.rst
View File

@ -1,9 +1,7 @@
macro macro
----- -----
Start recording a macro for later invocation as a command. Start recording a macro for later invocation as a command::
::
macro(<name> [arg1 [arg2 [arg3 ...]]]) macro(<name> [arg1 [arg2 [arg3 ...]]])
COMMAND1(ARGS ...) COMMAND1(ARGS ...)
@ -11,22 +9,28 @@ Start recording a macro for later invocation as a command.
... ...
endmacro(<name>) endmacro(<name>)
Define a macro named <name> that takes arguments named arg1 arg2 arg3 Define a macro named ``<name>`` that takes arguments named ``arg1``,
(...). Commands listed after macro, but before the matching endmacro, ``arg2``, ``arg3``, (...).
are not invoked until the macro is invoked. When it is invoked, the Commands listed after macro, but before the matching
commands recorded in the macro are first modified by replacing formal :command:`endmacro()`, are not invoked until the macro is invoked.
parameters (``${arg1}``) with the arguments passed, and then invoked as When it is invoked, the commands recorded in the macro are first
normal commands. In addition to referencing the formal parameters you modified by replacing formal parameters (``${arg1}``) with the arguments
can reference the values ``${ARGC}`` which will be set to the number of passed, and then invoked as normal commands.
arguments passed into the function as well as ``${ARGV0}`` ``${ARGV1}`` In addition to referencing the formal parameters you can reference the
``${ARGV2}`` ... which will have the actual values of the arguments values ``${ARGC}`` which will be set to the number of arguments passed
passed in. This facilitates creating macros with optional arguments. 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 Additionally ``${ARGV}`` holds the list of all arguments given to the
macro and ``${ARGN}`` holds the list of arguments past the last expected macro and ``${ARGN}`` holds the list of arguments past the last expected
argument. argument.
Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined
behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only
way to ensure that ``${ARGV#}`` was passed to the function as an extra
argument.
See the cmake_policy() command documentation for the behavior of See the :command:`cmake_policy()` command documentation for the behavior
policies inside macros. of policies inside macros.
Macro Argument Caveats Macro Argument Caveats
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
@ -37,10 +41,15 @@ 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::
if(ARGV1) # ARGV1 is not a variable if(ARGV1) # ARGV1 is not a variable
if(DEFINED ARGV2) # ARGV2 is not a variable
if(ARGC GREATER 2) # ARGC is not a variable
foreach(loop_var IN LISTS ARGN) # ARGN 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 In the first case, you can use ``if(${ARGV1})``.
use ``foreach(loop_var ${ARGN})`` but this will skip empty arguments. 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::
set(list_var "${ARGN}") set(list_var "${ARGN}")