1cmake_parse_arguments 2--------------------- 3 4Parse function or macro arguments. 5 6.. code-block:: cmake 7 8 cmake_parse_arguments(<prefix> <options> <one_value_keywords> 9 <multi_value_keywords> <args>...) 10 11 cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options> 12 <one_value_keywords> <multi_value_keywords>) 13 14.. versionadded:: 3.5 15 This command is implemented natively. Previously, it has been defined in the 16 module :module:`CMakeParseArguments`. 17 18This command is for use in macros or functions. 19It processes the arguments given to that macro or function, 20and defines a set of variables which hold the values of the 21respective options. 22 23The first signature reads processes arguments passed in the ``<args>...``. 24This may be used in either a :command:`macro` or a :command:`function`. 25 26.. versionadded:: 3.7 27 The ``PARSE_ARGV`` signature is only for use in a :command:`function` 28 body. In this case the arguments that are parsed come from the 29 ``ARGV#`` variables of the calling function. The parsing starts with 30 the ``<N>``-th argument, where ``<N>`` is an unsigned integer. 31 This allows for the values to have special characters like ``;`` in them. 32 33The ``<options>`` argument contains all options for the respective macro, 34i.e. keywords which can be used when calling the macro without any value 35following, like e.g. the ``OPTIONAL`` keyword of the :command:`install` 36command. 37 38The ``<one_value_keywords>`` argument contains all keywords for this macro 39which are followed by one value, like e.g. ``DESTINATION`` keyword of the 40:command:`install` command. 41 42The ``<multi_value_keywords>`` argument contains all keywords for this 43macro which can be followed by more than one value, like e.g. the 44``TARGETS`` or ``FILES`` keywords of the :command:`install` command. 45 46.. versionchanged:: 3.5 47 All keywords shall be unique. I.e. every keyword shall only be specified 48 once in either ``<options>``, ``<one_value_keywords>`` or 49 ``<multi_value_keywords>``. A warning will be emitted if uniqueness is 50 violated. 51 52When done, ``cmake_parse_arguments`` will consider for each of the 53keywords listed in ``<options>``, ``<one_value_keywords>`` and 54``<multi_value_keywords>`` a variable composed of the given ``<prefix>`` 55followed by ``"_"`` and the name of the respective keyword. These 56variables will then hold the respective value from the argument list 57or be undefined if the associated option could not be found. 58For the ``<options>`` keywords, these will always be defined, 59to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not. 60 61All remaining arguments are collected in a variable 62``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments 63were recognized. This can be checked afterwards to see 64whether your macro was called with unrecognized parameters. 65 66.. versionadded:: 3.15 67 ``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no 68 values at all are collected in a variable 69 ``<prefix>_KEYWORDS_MISSING_VALUES`` that will be undefined if all keywords 70 received values. This can be checked to see if there were keywords without 71 any values given. 72 73Consider the following example macro, ``my_install()``, which takes similar 74arguments to the real :command:`install` command: 75 76.. code-block:: cmake 77 78 macro(my_install) 79 set(options OPTIONAL FAST) 80 set(oneValueArgs DESTINATION RENAME) 81 set(multiValueArgs TARGETS CONFIGURATIONS) 82 cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" 83 "${multiValueArgs}" ${ARGN} ) 84 85 # ... 86 87Assume ``my_install()`` has been called like this: 88 89.. code-block:: cmake 90 91 my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS) 92 93After the ``cmake_parse_arguments`` call the macro will have set or undefined 94the following variables:: 95 96 MY_INSTALL_OPTIONAL = TRUE 97 MY_INSTALL_FAST = FALSE # was not used in call to my_install 98 MY_INSTALL_DESTINATION = "bin" 99 MY_INSTALL_RENAME <UNDEFINED> # was not used 100 MY_INSTALL_TARGETS = "foo;bar" 101 MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used 102 MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL" 103 MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS" 104 # No value for "CONFIGURATIONS" given 105 106You can then continue and process these variables. 107 108Keywords terminate lists of values, e.g. if directly after a 109``one_value_keyword`` another recognized keyword follows, this is 110interpreted as the beginning of the new option. E.g. 111``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in 112``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL`` 113is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added 114to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will 115therefore be set to ``TRUE``. 116