From 22cca9b8100a59cd156e2ba39819171a0cf71881 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Wed, 14 Nov 2018 20:50:59 +0100 Subject: Help: describe differences between macro and function. --- Help/command/function.rst | 3 +++ Help/command/macro.rst | 45 +++++++++++++++++++++++++++++++++++---------- 2 files changed, 38 insertions(+), 10 deletions(-) diff --git a/Help/command/function.rst b/Help/command/function.rst index 7b10381..53ba754 100644 --- a/Help/command/function.rst +++ b/Help/command/function.rst @@ -23,6 +23,9 @@ details. See the :command:`cmake_policy()` command documentation for the behavior of policies inside functions. +See the :command:`macro()` command documentation for differences +between CMake functions and macros. + Invocation ^^^^^^^^^^ diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 7450929..42a99fc 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -21,6 +21,9 @@ argument of the opening ``macro`` command. See the :command:`cmake_policy()` command documentation for the behavior of policies inside macros. +See the :ref:`Macro vs Function` section below for differences +between CMake macros and :command:`functions `. + Invocation ^^^^^^^^^^ @@ -65,13 +68,36 @@ behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only way to ensure that ``${ARGV#}`` was passed to the function as an extra argument. +.. _`Macro vs Function`: + +Macro vs Function +^^^^^^^^^^^^^^^^^ + +The ``macro`` command is very similar to the :command:`function` command. +Nonetheless, there are a few important differences. + +In a function, ``ARGC``, ``ARGC`` and ``ARGV0``, ``ARGV1``, ... are +true variables in the usual CMake sense. In a macro, they are not. +They are string replacements much like the C preprocessor would do +with a macro. This has a number of consequences, as explained in +the :ref:`Argument Caveats` section below. + +Another difference between macros and functions is the control flow. +A function is executed by transfering control from the calling +statement to the function body. A macro is executed as if the macro +body were pasted in place of the calling statement. This has for +consequence that a :command:`return()` in a macro body does not +just terminate execution of the macro; rather, control is returned +from the scope of the macro call. To avoid confusion, it is recommended +to avoid :command:`return()` in macros altogether. + +.. _`Argument Caveats`: + 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 +Since ``ARGC``, ``ARGC``, ``ARGV0`` etc are not variables, +you will NOT be able to use commands like .. code-block:: cmake @@ -80,12 +106,11 @@ Therefore you will NOT be able to use commands like if(ARGC GREATER 2) # ARGC 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 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 +In the first case, you can use ``if(${ARGV1})``. 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 .. code-block:: cmake -- cgit v0.12