diff options
Diffstat (limited to 'share/cmake-3.10/Help/command/cmake_parse_arguments.rst')
| -rw-r--r-- | share/cmake-3.10/Help/command/cmake_parse_arguments.rst | 99 |
1 files changed, 99 insertions, 0 deletions
diff --git a/share/cmake-3.10/Help/command/cmake_parse_arguments.rst b/share/cmake-3.10/Help/command/cmake_parse_arguments.rst new file mode 100644 index 0000000..b334a89 --- /dev/null +++ b/share/cmake-3.10/Help/command/cmake_parse_arguments.rst @@ -0,0 +1,99 @@ +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. + +:: + + cmake_parse_arguments(<prefix> <options> <one_value_keywords> + <multi_value_keywords> args...) + + cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords> + <multi_value_keywords>) + +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 values to have special characters like ``;`` in them. + +The ``<options>`` argument contains all options for the respective macro, +i.e. keywords which can be used when calling the macro without any value +following, like e.g. the ``OPTIONAL`` keyword of the :command:`install` +command. + +The ``<one_value_keywords>`` argument contains all keywords for this macro +which are followed by one value, like e.g. ``DESTINATION`` keyword of the +:command:`install` command. + +The ``<multi_value_keywords>`` argument contains all keywords for this +macro which can be followed by more than one value, like e.g. the +``TARGETS`` or ``FILES`` keywords of the :command:`install` command. + +.. note:: + + All keywords shall be unique. I.e. every keyword shall only be specified + once in either ``<options>``, ``<one_value_keywords>`` or + ``<multi_value_keywords>``. A warning will be emitted if uniqueness is + violated. + +When done, ``cmake_parse_arguments`` will consider for each of the +keywords listed in ``<options>``, ``<one_value_keywords>`` and +``<multi_value_keywords>`` a variable composed of the given ``<prefix>`` +followed by ``"_"`` and the name of the respective keyword. These +variables will then hold the respective value from the argument list +or be undefined if the associated option could not be found. +For the ``<options>`` keywords, these will always be defined, +to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not. + +All remaining arguments are collected in a variable +``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all argument +where recognized. This can be checked afterwards to see +whether your macro was called with unrecognized parameters. + +As an example here a ``my_install()`` macro, which takes similar arguments +as the real :command:`install` command: + +.. code-block:: cmake + + function(MY_INSTALL) + set(options OPTIONAL FAST) + set(oneValueArgs DESTINATION RENAME) + set(multiValueArgs TARGETS CONFIGURATIONS) + cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" + "${multiValueArgs}" ${ARGN} ) + + # ... + +Assume ``my_install()`` has been called like this: + +.. code-block:: cmake + + my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub) + +After the ``cmake_parse_arguments`` call the macro will have set or undefined +the following variables:: + + MY_INSTALL_OPTIONAL = TRUE + MY_INSTALL_FAST = FALSE # was not used in call to my_install + MY_INSTALL_DESTINATION = "bin" + MY_INSTALL_RENAME <UNDEFINED> # was not used + MY_INSTALL_TARGETS = "foo;bar" + MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used + MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL" + +You can then continue and process these variables. + +Keywords terminate lists of values, e.g. if directly after a +one_value_keyword another recognized keyword follows, this is +interpreted as the beginning of the new option. E.g. +``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in +``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL`` +is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty and +``MY_INSTALL_OPTIONAL`` will therefore be set to ``TRUE``. |