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 have defined 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. | |
For the ``<options>`` keywords this will be ``TRUE`` or ``FALSE``. | |
All remaining arguments are collected in a variable | |
``<prefix>_UNPARSED_ARGUMENTS``, 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 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 = "" (was not used) | |
MY_INSTALL_TARGETS = "foo;bar" | |
MY_INSTALL_CONFIGURATIONS = "" (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``. |