mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-06 05:40:54 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Improve grammar and wording for cmake_parse_arguments

Browse Source
This commit is contained in:
Craig Scott
2024-08-31 16:23:16 +10:00
parent 1accfd94b5
commit bb37d0e1a5
1 changed files with 29 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
Help/command/cmake_parse_arguments.rst
View File

@@ -20,48 +20,49 @@ It processes the arguments given to that macro or function,
and defines a set of variables which hold the values of the
respective options.
The first signature reads processes arguments passed in the ``<args>...``.
The first signature reads arguments passed in the ``<args>...``.
This may be used in either a :command:`macro` or a :command:`function`.
.. versionadded:: 3.7
The ``PARSE_ARGV`` signature is only for use in a :command:`function`
body. In this case the arguments that are parsed come from the
body. In this case, the arguments that are parsed come from the
``ARGV#`` variables of the calling function. The parsing starts with
the ``<N>``-th 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 ``<options>`` argument contains all options for the respective function
or macro. These are keywords that have no value following them, like 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 ``<one_value_keywords>`` argument contains all keywords for this function
or macro which are followed by one value, like the ``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
function or macro which can be followed by more than one value, like the
``TARGETS`` or ``FILES`` keywords of the :command:`install` command.
.. versionchanged:: 3.5
All keywords shall be unique. I.e. every keyword shall only be specified
once in either ``<options>``, ``<one_value_keywords>`` or
All keywords must be unique. Each keyword can only be specified
once in any of the ``<options>``, ``<one_value_keywords>``, or
``<multi_value_keywords>``. A warning will be emitted if uniqueness is
violated.
When done, ``cmake_parse_arguments`` will consider 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
or be undefined if the associated option could not be found.
For the ``<options>`` keywords, these will always be defined,
to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not.
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. For
``<one_value_keywords>`` and ``<multi_value_keywords>``, these variables
will then hold the respective value(s) from the argument list, or be undefined
if the associated keyword was not given (policy :policy:`CMP0174` can also
affect the behavior for ``<one_value_keywords>``). For the ``<options>``
keywords, these variables will always be defined, and they will be set to
``TRUE`` if the keyword is present, or ``FALSE`` if it is not.
All remaining arguments are collected in a variable
``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments
were recognized. This can be checked afterwards to see
whether your macro was called with unrecognized parameters.
whether your macro or function was called with unrecognized parameters.
.. versionadded:: 3.15
``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no
@@ -96,7 +97,7 @@ Assume ``my_install()`` has been called like this:
my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
After the ``cmake_parse_arguments`` call the macro will have set or undefined
After the ``cmake_parse_arguments`` call, the macro will have set or undefined
the following variables::
MY_INSTALL_OPTIONAL = TRUE
@@ -111,14 +112,14 @@ the following variables::
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.
Keywords terminate lists of values. If a keyword is given directly after a
``<one_value_keyword>``, that preceding ``<one_value_keyword>`` receives no
value and the keyword is added to the ``<prefix>_KEYWORDS_MISSING_VALUES``
variable. For the above example, the call
``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 (but added
to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will
therefore be set to ``TRUE``.
``MY_INSTALL_OPTIONAL`` being set to ``TRUE`` and ``MY_INSTALL_DESTINATION``
being unset. The ``MY_INSTALL_KEYWORDS_MISSING_VALUES`` variable would hold
the value ``DESTINATION``.
See Also
^^^^^^^^