diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/export.rst | 5 | ||||
| -rw-r--r-- | Help/command/find_package.rst | 8 | ||||
| -rw-r--r-- | Help/manual/cmake-language.7.rst | 23 | ||||
| -rw-r--r-- | Help/manual/cmake-packages.7.rst | 15 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -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/release/dev/CMP0053.rst | 6 | ||||
| -rw-r--r-- | Help/release/dev/package-disable-registry.rst | 11 | ||||
| -rw-r--r-- | Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst | 11 | ||||
| -rw-r--r-- | Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst | 13 | ||||
| -rw-r--r-- | Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst | 13 |
13 files changed, 147 insertions, 9 deletions
diff --git a/Help/command/export.rst b/Help/command/export.rst index 6b83587..d4bab35 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -51,4 +51,7 @@ projects find and use a package from the current project's build tree without help from the user. Note that the entry in the package registry that this command creates works only in conjunction with a package configuration file (<name>Config.cmake) that works with the -build tree. +build tree. In some cases, for example for packaging and for system +wide installations, it is not desirable to write the user package +registry. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable +is enabled, the ``export(PACKAGE)`` command will do nothing. diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 5d9aea6..190d05c 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -272,7 +272,9 @@ enabled. (This step is implemented only on Windows.) 6. Search paths stored in the CMake :ref:`User Package Registry`. - This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed. + This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by + setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` + to ``TRUE``. See the :manual:`cmake-packages(7)` manual for details on the user package registry. @@ -285,7 +287,9 @@ enabled. CMAKE_SYSTEM_APPBUNDLE_PATH 8. Search paths stored in the CMake :ref:`System Package Registry`. - This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed. + This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed + or by setting the + :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``. See the :manual:`cmake-packages(7)` manual for details on the system package registry. 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-packages.7.rst b/Help/manual/cmake-packages.7.rst index 1723826..c4cca6d 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -564,6 +564,21 @@ containing the package configuration file. There is no system package registry on non-Windows platforms. +.. _`Disabling the Package Registry`: + +Disabling the Package Registry +------------------------------ + +In some cases using the Package Registries is not desirable. CMake +allows to disable them using the following variables: + + * :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` disables the + :command:`export(PACKAGE)` command. + * :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the + User Package Registry in all the :command:`find_package` calls. + * :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables + the System Package Registry in all the :command:`find_package` calls. + Package Registry Example ------------------------ 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-variables.7.rst b/Help/manual/cmake-variables.7.rst index 7313cd1..a7d4af6 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -109,10 +109,13 @@ Variables that Change Behavior /variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName /variable/CMAKE_ERROR_DEPRECATED /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY /variable/CMAKE_SYSROOT /variable/CMAKE_FIND_LIBRARY_PREFIXES /variable/CMAKE_FIND_LIBRARY_SUFFIXES /variable/CMAKE_FIND_NO_INSTALL_PREFIX + /variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY + /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE /variable/CMAKE_FIND_ROOT_PATH /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE 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/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/release/dev/package-disable-registry.rst b/Help/release/dev/package-disable-registry.rst new file mode 100644 index 0000000..1b23fde --- /dev/null +++ b/Help/release/dev/package-disable-registry.rst @@ -0,0 +1,11 @@ +package-disable-registry +------------------------ + +* The :command:`export(PACKAGE)` command learned to check the + :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable to skip + exporting the package. + +* The :command:`find_package` command learned to check the + :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` and + :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` + variables to skip searching the package registries. diff --git a/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..ee109ba --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst @@ -0,0 +1,11 @@ +CMAKE_EXPORT_NO_PACKAGE_REGISTRY +-------------------------------- + +Disable the :command:`export(PACKAGE)` command. + +In some cases, for example for packaging and for system wide +installations, it is not desirable to write the user package registry. +If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable is enabled, +the :command:`export(PACKAGE)` command will do nothing. + +See also :ref:`Disabling the Package Registry`. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..9058471 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst @@ -0,0 +1,13 @@ +CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY +-------------------------------------- + +Skip :ref:`User Package Registry` in :command:`find_package` calls. + +In some cases, for example to locate only system wide installations, it +is not desirable to use the :ref:`User Package Registry` when searching +for packages. If the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` +variable is enabled, all the :command:`find_package` commands will skip +the :ref:`User Package Registry` as if they were called with the +``NO_CMAKE_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry`. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..44588b1 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst @@ -0,0 +1,13 @@ +CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY +--------------------------------------------- + +Skip :ref:`System Package Registry` in :command:`find_package` calls. + +In some cases, it is not desirable to use the +:ref:`System Package Registry` when searching for packages. If the +:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable is +enabled, all the :command:`find_package` commands will skip +the :ref:`System Package Registry` as if they were called with the +``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry`. |