Browse Source

Help: Clarify configure_file #cmakedefine01 syntax and behavior

Fixes: #21935
Elsie Hupp 5 years ago
parent
commit
c13f75982f
1 changed files with 24 additions and 2 deletions
  1. 24 2
      Help/command/configure_file.rst

+ 24 - 2
Help/command/configure_file.rst

@@ -36,8 +36,30 @@ or
 depending on whether ``VAR`` is set in CMake to any value not considered
 a false constant by the :command:`if` command.  The "..." content on the
 line after the variable name, if any, is processed as above.
-Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with
-either ``#define VAR 1`` or ``#define VAR 0`` similarly.
+
+Unlike lines of the form ``#cmakedefine VAR ...``, in lines of the form
+``#cmakedefine01 VAR``, ``VAR`` itself will expand to ``VAR 0`` or ``VAR 1``
+rather than being assigned the value ``...``. Therefore, input lines of the form
+
+.. code-block:: c
+
+  #cmakedefine01 VAR
+
+will be replaced with either
+
+.. code-block:: c
+
+  #define VAR 0
+
+or
+
+.. code-block:: c
+
+  #define VAR 1
+
+Input lines of the form ``#cmakedefine01 VAR ...`` will expand
+as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``,
+which may lead to undefined behavior.
 
 .. versionadded:: 3.10
   The result lines (with the exception of the ``#undef`` comments) can be