Merge topic 'cmake-parse-arguments-one-arg-empty-string'

ceeea4e511 cmake_parse_arguments: Set variable if empty string given after keyword
2f5cc6afa1 cmParseArgumentsCommand: Use cmStrCat() for string concatenation

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9748

3 files changed, 40 insertions, 0 deletions

diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst
index 0bb1d91..70dbeeb 100644
--- a/Help/command/cmake_parse_arguments.rst
+++ b/Help/command/cmake_parse_arguments.rst
@@ -70,6 +70,12 @@ whether your macro was called with unrecognized parameters.
    received values. This can be checked to see if there were keywords without
    any values given.
 
+.. versionchanged:: 3.31
+   If a ``<one_value_keyword>`` is followed by an empty string as its value,
+   policy :policy:`CMP0174` controls whether a corresponding
+   ``<prefix>_<keyword>`` variable is defined or not.
+
+
 Consider the following example macro, ``my_install()``, which takes similar
 arguments to the real :command:`install` command:
 
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 4130e14..e257c36 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.31
 .. toctree::
    :maxdepth: 1
 
+   CMP0174: cmake_parse_arguments(PARSE_ARGV) defines a variable for an empty string after a single-value keyword. </policy/CMP0174>
    CMP0173: The CMakeFindFrameworks module is removed. </policy/CMP0173>
    CMP0172: The CPack module enables per-machine installation by default in the CPack WIX Generator. </policy/CMP0172>
    CMP0171: 'codegen' is a reserved target name. </policy/CMP0171>
diff --git a/Help/policy/CMP0174.rst b/Help/policy/CMP0174.rst
new file mode 100644
index 0000000..bde0a03
--- /dev/null
+++ b/Help/policy/CMP0174.rst
@@ -0,0 +1,33 @@
+CMP0174
+-------
+
+.. versionadded:: 3.31
+
+:command:`cmake_parse_arguments(PARSE_ARGV)` defines a variable for an empty
+string after a single-value keyword.
+
+One of the main reasons for using the ``PARSE_ARGV`` form of the
+:command:`cmake_parse_arguments` command is to more robustly handle corner
+cases related to empty values.  The non-``PARSE_ARGV`` form doesn't preserve
+empty arguments, but the ``PARSE_ARGV`` form does.  For each single-value
+keyword given, a variable should be defined if the keyword is followed by a
+value.  Prior to CMake 3.31, no variable would be defined if the value given
+was an empty string.  This meant the code could not detect the difference
+between the keyword not being given, and it being given but with an empty
+value, except by iterating over all the arguments and checking if the keyword
+is present.
+
+For the ``OLD`` behavior of this policy,
+:command:`cmake_parse_arguments(PARSE_ARGV)` does not define a variable for a
+single-value keyword followed by an empty string.
+For the ``NEW`` behavior, :command:`cmake_parse_arguments(PARSE_ARGV)` always
+defines a variable for each keyword given in the arguments, even a single-value
+keyword with an empty string as its value.  With the ``NEW`` behavior, the
+code can robustly check if a single-value keyword was given with any value
+using just ``if(DEFINED <prefix>_<keyword>)``.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt