# 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 `macro()` or a `function()`.

The `PARSE_ARGV` signature is only for use in a `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 `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 `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 `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 `install()` command:

    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:

    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`.