"Fossies" - the Fresh Open Source Software Archive

Member "cmake-3.6.2-win32-x86/share/cmake-3.6/Help/command/cmake_parse_arguments.rst" (7 Sep 2016, 3429 Bytes) of archive /windows/misc/cmake-3.6.2-win32-x86.zip:

As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.


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( <one_value_keywords> <multi_value_keywords> args…)

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.