Merge branch 'document-dollar-in-varnames' into release-3.13

Merge-request: !2479

Help/manual/cmake-language.7.rst

@@ -391,8 +391,9 @@ inside out, e.g. ``${outer_${inner_variable}_variable}``.
 
 Literal variable references may consist of alphanumeric characters,
 the characters ``/_.+-``, and `Escape Sequences`_.  Nested references
-may be used to evaluate variables of any name.  (See also policy
-:policy:`CMP0053` documentation for historical considerations.)
+may be used to evaluate variables of any name.  See also policy
+:policy:`CMP0053` documentation for historical considerations and reasons why
+the ``$`` is also technically permitted but is discouraged.
 
 The `Variables`_ section documents the scope of variable names
 and how their values are set.

Help/policy/CMP0053.rst

@@ -16,6 +16,10 @@ cleaned up to simplify the behavior.  Specifically:
 * Literal ``${VAR}`` reference syntax may contain only
   alphanumeric characters (``A-Z``, ``a-z``, ``0-9``) and
   the characters ``_``, ``.``, ``/``, ``-``, and ``+``.
+  Note that ``$`` is technically allowed in the ``NEW`` behavior, but is
+  invalid for ``OLD`` behavior.  This is due to an oversight during the
+  implementation of :policy:`CMP0053` and its use as a literal variable
+  reference is discouraged for this reason.
   Variables with other characters in their name may still
   be referenced indirectly, e.g.
 

Tests/RunCMake/Syntax/CMP0053-Dollar-NEW-stderr.txt

@@ -0,0 +1,2 @@
+^-->value<--
+-->value<--$

Tests/RunCMake/Syntax/CMP0053-Dollar-NEW.cmake

@@ -0,0 +1,6 @@
+cmake_policy(SET CMP0053 NEW)
+
+set($ value)
+set(dollar $)
+message("-->${${dollar}}<--")
+message("-->${$}<--")

Tests/RunCMake/Syntax/CMP0053-Dollar-OLD-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/Syntax/CMP0053-Dollar-OLD-stderr.txt

@@ -0,0 +1,24 @@
+^CMake Deprecation Warning at CMP0053-Dollar-OLD.cmake:1 \(cmake_policy\):
+  The OLD behavior for policy CMP0053 will be removed from a future version
+  of CMake.
+
+  The cmake-policies\(7\) manual explains that the OLD behaviors of all
+  policies are deprecated and that a policy should be set to OLD only under
+  specific short-term circumstances.  Projects should be ported to the NEW
+  behavior and not rely on setting a policy to OLD.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)
++
+-->value<--
+CMake Error at CMP0053-Dollar-OLD.cmake:6 \(message\):
+  Syntax error in cmake code at
+
+    .*CMP0053-Dollar-OLD.cmake:6
+
+  when parsing string
+
+    -->\${\$}<--
+
+  syntax error, unexpected \$, expecting } \(7\)
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)$

Tests/RunCMake/Syntax/CMP0053-Dollar-OLD.cmake

@@ -0,0 +1,6 @@
+cmake_policy(SET CMP0053 OLD)
+
+set($ value)
+set(dollar $)
+message("-->${${dollar}}<--")
+message("-->${$}<--")

Tests/RunCMake/Syntax/RunCMakeTest.cmake

@@ -111,6 +111,8 @@ run_cmake(CMP0053-NameWithNewlineQuoted)
 run_cmake(CMP0053-NameWithCarriageReturnQuoted)
 run_cmake(CMP0053-NameWithEscapedSpacesQuoted)
 run_cmake(CMP0053-NameWithEscapedTabsQuoted)
+run_cmake(CMP0053-Dollar-OLD)
+run_cmake(CMP0053-Dollar-NEW)
 
 # Variable special types
 run_cmake(QueryCache)