diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/manual/cmake-language.7.rst | 23 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 3 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 3 | ||||
| -rw-r--r-- | Help/policy/CMP0010.rst | 3 | ||||
| -rw-r--r-- | Help/policy/CMP0053.rst | 44 | ||||
| -rw-r--r-- | Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst | 2 | ||||
| -rw-r--r-- | Help/prop_tgt/CXX_STANDARD.rst | 17 | ||||
| -rw-r--r-- | Help/prop_tgt/CXX_STANDARD_REQUIRED.rst | 14 | ||||
| -rw-r--r-- | Help/release/dev/CMP0053.rst | 6 | ||||
| -rw-r--r-- | Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst | 8 |
11 files changed, 113 insertions, 11 deletions
diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 1e4c6c5..b83dcad 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -287,6 +287,8 @@ For example: Instead use a `Quoted Argument`_ or a `Bracket Argument`_ to represent the content. +.. _`Escape Sequences`: + Escape Sequences ---------------- @@ -294,16 +296,20 @@ An *escape sequence* is a ``\`` followed by one character: .. productionlist:: escape_sequence: `escape_identity` | `escape_encoded` | `escape_semicolon` - escape_identity: '\(' | '\)' | '\#' | '\"' | '\ ' | - : '\\' | '\$' | '\@' | '\^' + escape_identity: '\' <match '[^A-Za-z0-9;]'> escape_encoded: '\t' | '\r' | '\n' escape_semicolon: '\;' -A ``\`` followed by one of ``()#" \#@^`` simply encodes the literal +A ``\`` followed by a non-alphanumeric character simply encodes the literal character without interpreting it as syntax. A ``\t``, ``\r``, or ``\n`` -encodes a tab, carriage return, or newline character, respectively. -A ``\;`` encodes itself but may be used in an `Unquoted Argument`_ -to encode the ``;`` without dividing the argument value on it. +encodes a tab, carriage return, or newline character, respectively. A ``\;`` +outside of any `Variable References`_ encodes itself but may be used in an +`Unquoted Argument`_ to encode the ``;`` without dividing the argument +value on it. A ``\;`` inside `Variable References`_ encodes the literal +``;`` character. (See also policy :policy:`CMP0053` documentation for +historical considerations.) + +.. _`Variable References`: Variable References ------------------- @@ -315,6 +321,11 @@ or by the empty string if the variable is not set. Variable references can nest and are evaluated from the 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.) + The `Variables`_ section documents the scope of variable names and how their values are set. diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 4b895fe..136cf5c 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -104,3 +104,4 @@ All Policies /policy/CMP0050 /policy/CMP0051 /policy/CMP0052 + /policy/CMP0053 diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index da21e29..14d2e7f 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -108,8 +108,9 @@ Properties on Targets /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /prop_tgt/CONFIG_OUTPUT_NAME /prop_tgt/CONFIG_POSTFIX - /prop_tgt/CXX_STANDARD /prop_tgt/CXX_EXTENSIONS + /prop_tgt/CXX_STANDARD + /prop_tgt/CXX_STANDARD_REQUIRED /prop_tgt/DEBUG_POSTFIX /prop_tgt/DEFINE_SYMBOL /prop_tgt/EchoString diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 6cdccea..a7d4af6 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -261,8 +261,9 @@ Variables for Languages /variable/CMAKE_COMPILER_IS_GNULANG /variable/CMAKE_CXX_COMPILE_FEATURES - /variable/CMAKE_CXX_STANDARD /variable/CMAKE_CXX_EXTENSIONS + /variable/CMAKE_CXX_STANDARD + /variable/CMAKE_CXX_STANDARD_REQUIRED /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG diff --git a/Help/policy/CMP0010.rst b/Help/policy/CMP0010.rst index 01699e1..9d2eb76 100644 --- a/Help/policy/CMP0010.rst +++ b/Help/policy/CMP0010.rst @@ -10,6 +10,9 @@ variable reference is an error. The OLD behavior for this policy is to warn about the error, leave the string untouched, and continue. The NEW behavior for this policy is to report an error. +If :policy:`CMP0053` is set to ``NEW``, this policy has no effect +and is treated as always being ``NEW``. + This policy was introduced in CMake version 2.6.3. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. diff --git a/Help/policy/CMP0053.rst b/Help/policy/CMP0053.rst new file mode 100644 index 0000000..fac430e --- /dev/null +++ b/Help/policy/CMP0053.rst @@ -0,0 +1,44 @@ +CMP0053 +------- + +Simplify variable reference and escape sequence evaluation. + +CMake 3.1 introduced a much faster implementation of evaluation of the +:ref:`Variable References` and :ref:`Escape Sequences` documented in the +:manual:`cmake-language(7)` manual. While the behavior is identical +to the legacy implementation in most cases, some corner cases were +cleaned up to simplify the behavior. Specifically: + +* Expansion of ``@VAR@`` reference syntax defined by the + :command:`configure_file` and :command:`string(CONFIGURE)` + commands is no longer performed in other contexts. + +* Literal ``${VAR}`` reference syntax may contain only + alphanumeric characters (``A-Z``, ``a-z``, ``0-9``) and + the characters ``_``, ``.``, ``/``, ``-``, and ``+``. + Variables with other characters in their name may still + be referenced indirectly, e.g. + + .. code-block:: cmake + + set(varname "otherwise & disallowed $ characters") + message("${${varname}}") + +* The setting of policy :policy:`CMP0010` is not considered, + so improper variable reference syntax is always an error. + +* More characters are allowed to be escaped in variable names. + Previously, only ``()#" \#@^`` were valid characters to + escape. Now any non-alphanumeric, non-semicolon, non-NUL + character may be escaped following the ``escape_identity`` + production in the :ref:`Escape Sequences` section of the + :manual:`cmake-language(7)` manual. + +The ``OLD`` behavior for this policy is to honor the legacy behavior for +variable references and escape sequences. The ``NEW`` behavior is to +use the simpler variable expansion and escape sequence evaluation rules. + +This policy was introduced in CMake version 3.1. +CMake version |release| warns when the policy is not set and uses +``OLD`` behavior. Use the :command:`cmake_policy` command to set +it to ``OLD`` or ``NEW`` explicitly. diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index b8b0fcd..643bd3b 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -73,7 +73,7 @@ The features known to this version of CMake are: .. _N1986: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1986.pdf ``cxx_deleted_functions`` - Deleted functions, as defined in N2346_. + Deleted functions, as defined in N2346_. .. _N2346: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index e1b6e78..fdd5aac 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -1,14 +1,27 @@ CXX_STANDARD ------------ -The C++ standard whose features are required to build this target. +The C++ standard whose features are requested to build this target. -This property specifies the C++ standard whose features are required +This property specifies the C++ standard whose features are requested to build this target. For some compilers, this results in adding a flag such as ``-std=c++11`` to the compile line. Supported values are ``98`` and ``11``. +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY CXX_STANDARD 11) + +with a compiler which does not support ``-std=c++11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=c++98`` flag if supported. This "decay" behavior may be controlled +with the :prop_tgt:`CXX_STANDARD_REQUIRED` target property. + This property is initialized by the value of the :variable:`CMAKE_CXX_STANDARD` variable if it is set when a target is created. diff --git a/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..f082805 --- /dev/null +++ b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst @@ -0,0 +1,14 @@ +CXX_STANDARD_REQUIRED +--------------------- + +Boolean describing whether the value of :prop_tgt:`CXX_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`CXX_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`CXX_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. + +This property is initialized by the value of +the :variable:`CMAKE_CXX_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/release/dev/CMP0053.rst b/Help/release/dev/CMP0053.rst new file mode 100644 index 0000000..3b835fb --- /dev/null +++ b/Help/release/dev/CMP0053.rst @@ -0,0 +1,6 @@ +CMP0053 +------- + +* The :manual:`cmake-language(7)` syntax for :ref:`Variable References` and + :ref:`Escape Sequences` was simplified in order to allow a much faster + implementation. See policy :policy:`CMP0053`. diff --git a/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..ff005da --- /dev/null +++ b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst @@ -0,0 +1,8 @@ +CMAKE_CXX_STANDARD_REQUIRED +--------------------------- + +Default value for ``CXX_STANDARD_REQUIRED`` property of targets. + +This variable is used to initialize the :prop_tgt:`CXX_STANDARD_REQUIRED` +property on all targets. See that target property for additional +information. |