1 files changed, 67 insertions, 0 deletions
diff --git a/Help/command/macro.rst b/Help/command/macro.rst
new file mode 100644
index 0000000..258dc50
--- /dev/null
+++ b/Help/command/macro.rst
@@ -0,0 +1,67 @@
+macro
+-----
+
+Start recording a macro for later invocation as a command.
+
+::
+
+  macro(<name> [arg1 [arg2 [arg3 ...]]])
+    COMMAND1(ARGS ...)
+    COMMAND2(ARGS ...)
+    ...
+  endmacro(<name>)
+
+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
+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
+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.