diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/cmake_parse_arguments.rst | 78 | ||||
| -rw-r--r-- | Help/manual/cmake-commands.7.rst | 1 | ||||
| -rw-r--r-- | Help/release/dev/CMakeParseArguments-native-impl.rst | 6 |
3 files changed, 85 insertions, 0 deletions
diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst new file mode 100644 index 0000000..7638b61 --- /dev/null +++ b/Help/command/cmake_parse_arguments.rst @@ -0,0 +1,78 @@ +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...) + + +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. + +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``. diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 5b92b51..d0c2986 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -29,6 +29,7 @@ These commands may be used freely in CMake projects. /command/build_command /command/cmake_host_system_information /command/cmake_minimum_required + /command/cmake_parse_arguments /command/cmake_policy /command/configure_file /command/continue diff --git a/Help/release/dev/CMakeParseArguments-native-impl.rst b/Help/release/dev/CMakeParseArguments-native-impl.rst new file mode 100644 index 0000000..114a099 --- /dev/null +++ b/Help/release/dev/CMakeParseArguments-native-impl.rst @@ -0,0 +1,6 @@ +CMakeParseArguments-native-impl +------------------------------- + +* The :command:`cmake_parse_arguments` command is now implemented natively. + The :module:`CMakeParseArguments` module remains as an empty placeholder + for compatibility. |