97 lines
3.9 KiB
ReStructuredText
97 lines
3.9 KiB
ReStructuredText
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``.
|