diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/FIND_XXX.txt | 13 | ||||
| -rw-r--r-- | Help/command/FIND_XXX_REGISTRY_QUERY.txt | 43 | ||||
| -rw-r--r-- | Help/command/FIND_XXX_REGISTRY_VIEW.txt | 41 | ||||
| -rw-r--r-- | Help/command/add_custom_command.rst | 4 | ||||
| -rw-r--r-- | Help/command/find_file.rst | 2 | ||||
| -rw-r--r-- | Help/command/find_library.rst | 2 | ||||
| -rw-r--r-- | Help/command/find_package.rst | 38 | ||||
| -rw-r--r-- | Help/command/find_path.rst | 2 | ||||
| -rw-r--r-- | Help/command/find_program.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -rw-r--r-- | Help/policy/CMP0134.rst | 39 | ||||
| -rw-r--r-- | Help/release/dev/find_item-query-windows-registry.rst | 6 |
12 files changed, 184 insertions, 9 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 1e75dc9..ab5f860 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -13,6 +13,7 @@ The general signature is: name | |NAMES| [HINTS [path | ENV var]... ] [PATHS [path | ENV var]... ] + [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] [NO_CACHE] @@ -51,6 +52,18 @@ Options include: The ``ENV var`` sub-option reads paths from a system environment variable. + .. versionchanged:: 3.24 + On ``Windows`` platform, it is possible to include registry queries as part + of the directories. Such specifications will be ignored on all other + platforms. + + .. include:: FIND_XXX_REGISTRY_QUERY.txt + +``REGISTRY_VIEW`` + .. versionadded:: 3.24 + + .. include:: FIND_XXX_REGISTRY_VIEW.txt + ``PATH_SUFFIXES`` Specify additional subdirectories to check below each directory location otherwise considered. diff --git a/Help/command/FIND_XXX_REGISTRY_QUERY.txt b/Help/command/FIND_XXX_REGISTRY_QUERY.txt new file mode 100644 index 0000000..04a087a --- /dev/null +++ b/Help/command/FIND_XXX_REGISTRY_QUERY.txt @@ -0,0 +1,43 @@ +The formal syntax, as specified using +`BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with +the regular extensions, for registry query is the following: + +.. parsed-literal:: + + registry_query ::= '[' `sep_definition`_? `root_key`_ + ((`key_separator`_ `sub_key`_)? (`value_separator`_ `value_name`_)?)? ']' + _`sep_definition` ::= '{' `value_separator`_ '}' + _`root_key` ::= 'HKLM' | 'HKEY_LOCAL_MACHINE' | 'HKCU' | 'HKEY_CURRENT_USER' | + 'HKCR' | 'HKEY_CLASSES_ROOT' | 'HKCC' | 'HKEY_CURRENT_CONFIG' | + 'HKU' | 'HKEY_USERS' + _`sub_key` ::= `element`_ (`key_separator`_ `element`_)* + _`key_separator` ::= '/' | '\\' + _`value_separator` ::= `element`_ | ';' + _`value_name` ::= `element`_ | '(default)' + _`element` ::= `character`_\+ + _`character` ::= <any character except `key_separator`_ and `value_separator`_> + +The `sep_definition`_ optional item offers the possibility to specify the +string used to separate the `sub_key`_ from the `value_name`_ item. If +not specified, the character ``;`` is used. + +.. parsed-literal:: + + # example using default separator + |FIND_XXX| (... **PATHS** "/root/[HKLM/Stuff;InstallDir]/lib[HKLM\\\\Stuff;Architecture]") + + # example using different specified separators + |FIND_XXX| (... **HINTS** "/root/[{|}HKCU/Stuff|InstallDir]/lib[{@@}HKCU\\\\Stuff@@Architecture]") + +If the `value_name`_ item is not specified or has the special name +``(default)``, the content of the default value, if any, will be returned. The +supported types for the `value_name`_ are: + +* ``REG_SZ``. +* ``REG_EXPAND_SZ``. The returned data is expanded. +* ``REG_DWORD``. +* ``REG_QWORD``. + +When the registry query failed, typically because the key does not exist or +the data type is not supported, the string ``/REGISTRY-NOTFOUND`` is substituted +to the ``[]`` query expression. diff --git a/Help/command/FIND_XXX_REGISTRY_VIEW.txt b/Help/command/FIND_XXX_REGISTRY_VIEW.txt new file mode 100644 index 0000000..39b156f --- /dev/null +++ b/Help/command/FIND_XXX_REGISTRY_VIEW.txt @@ -0,0 +1,41 @@ +Specify which registry views must be queried. This option is only meaningful +on ``Windows`` platform and will be ignored on other ones. When not +specified, |FIND_XXX_REGISTRY_VIEW_DEFAULT| view is used when :policy:`CMP0134` +policy is ``NEW``. Refer to :policy:`CMP0134` policy for default view when +policy is ``OLD`` or undefined. + +``64`` + Query the 64bit registry. On ``32bit Windows``, returns always the string + ``/REGISTRY-NOTFOUND``. + +``32`` + Query the 32bit registry. + +``64_32`` + Query both views (``64`` and ``32``) and generate a path for each. + +``32_64`` + Query both views (``32`` and ``64``) and generate a path for each. + +``HOST`` + Query the registry matching the architecture of the host: ``64`` on ``64bit + Windows`` and ``32`` on ``32bit Windows``. + +``TARGET`` + Query the registry matching the architecture specified by + :variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fallback to + ``HOST`` view. + +``BOTH`` + Query both views (``32`` and ``64``). The order depends of the following + rules: If :variable:`CMAKE_SIZEOF_VOID_P` variable is defined. Use the + following view depending of the content of this variable: + + * ``8``: ``64_32`` + * ``4``: ``32_64`` + + If :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on + architecture of the host: + + * ``64bit``: ``64_32`` + * ``32bit``: ``32`` diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index ec73f9f..4fe9326 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -288,12 +288,12 @@ The options are: .. productionlist:: depfile depfile: `rule`* - rule: `targets` (`:` (`separator` `dependencies`?)?)? `eol` + rule: `targets` (':' (`separator` `dependencies`?)?)? `eol` targets: `target` (`separator` `target`)* `separator`* target: `pathname` dependencies: `dependency` (`separator` `dependency`)* `separator`* dependency: `pathname` - separator: (space | line_continue)+ + separator: (`space` | `line_continue`)+ line_continue: '\' `eol` space: ' ' | '\t' pathname: `character`+ diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index 39dfb85..c5c4014 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -8,6 +8,8 @@ find_file .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/include`` +.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET`` + .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index ab957ce..c237e7f 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -8,6 +8,8 @@ find_library .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/lib`` +.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET`` + .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 86e26e9..0d8a166 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -1,6 +1,12 @@ find_package ------------ +.. |FIND_XXX| replace:: find_package +.. |FIND_ARGS_XXX| replace:: <PackageName> +.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET`` +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` + .. only:: html .. contents:: @@ -74,11 +80,12 @@ sections on this page. Basic Signature ^^^^^^^^^^^^^^^ -.. code-block:: cmake +.. parsed-literal:: find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] [REQUIRED] [[COMPONENTS] [components...]] [OPTIONAL_COMPONENTS components...] + [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] [NO_POLICY_SCOPE] [GLOBAL]) @@ -116,6 +123,12 @@ define what occurs in such cases. Common arrangements include assuming it should find all components, no components or some well-defined subset of the available components. +.. versionadded:: 3.24 + The ``REGISTRY_VIEW`` keyword enables to specify which registry views must be + queried. This keyword is only meaningful on ``Windows`` platform and will be + ignored on all other ones. Formally, it is up to the target package how to + interpret the registry view information given to it. + Specifying the ``GLOBAL`` keyword will promote all imported targets to a global scope in the importing project. Alternatively this functionality can be enabled by setting the variable @@ -155,7 +168,7 @@ of the ``NO_POLICY_SCOPE`` option. Full Signature ^^^^^^^^^^^^^^ -.. code-block:: cmake +.. parsed-literal:: find_package(<PackageName> [version] [EXACT] [QUIET] [REQUIRED] [[COMPONENTS] [components...]] @@ -167,6 +180,7 @@ Full Signature [CONFIGS config1 [config2 ...]] [HINTS path1 [path2 ... ]] [PATHS path1 [path2 ... ]] + [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] [PATH_SUFFIXES suffix1 [suffix2 ...]] [NO_DEFAULT_PATH] [NO_PACKAGE_ROOT_PATH] @@ -272,6 +286,19 @@ that order). if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``. * The ``lib`` path is always searched. +.. versionchanged:: 3.24 + On ``Windows`` platform, it is possible to include registry queries as part + of the directories specified through ``HINTS`` and ``PATHS`` keywords. Such + specifications will be ignored on all other platforms. + +.. include:: FIND_XXX_REGISTRY_QUERY.txt + +.. versionadded:: 3.24 + ``REGISTRY_VIEW`` can be specified to manage ``Windows`` registry queries + specified as part of ``PATHS`` and ``HINTS``. + +.. include:: FIND_XXX_REGISTRY_VIEW.txt + If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each (``W``) or (``U``) directory entry one-by-one. @@ -382,11 +409,6 @@ of the above locations to be ignored. Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable various search locations. -.. |FIND_XXX| replace:: find_package -.. |FIND_ARGS_XXX| replace:: <PackageName> -.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: - :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` - .. include:: FIND_XXX_ROOT.txt .. include:: FIND_XXX_ORDER.txt @@ -557,6 +579,8 @@ restores their original state before returning): True if ``REQUIRED`` option was given ``<PackageName>_FIND_QUIETLY`` True if ``QUIET`` option was given +``<PackageName>_FIND_REGISTRY_VIEW`` + The requested view if ``REGISTRY_VIEW`` option was given ``<PackageName>_FIND_VERSION`` Full requested version string ``<PackageName>_FIND_VERSION_MAJOR`` diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index ec66771..1d7648d 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -8,6 +8,8 @@ find_path .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/include`` +.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET`` + .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index e2ff693..f4149be 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -8,6 +8,8 @@ find_program .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin`` +.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``BOTH`` + .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 84ef15f..d1fafb5 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -58,6 +58,7 @@ Policies Introduced by CMake 3.24 .. toctree:: :maxdepth: 1 + CMP0134: Fallback to \"HOST\" Windows registry view when \"TARGET\" view is not usable. </policy/CMP0134> CMP0133: The CPack module disables SLA by default in the CPack DragNDrop Generator. </policy/CMP0133> CMP0132: Do not set compiler environment variables on first run. </policy/CMP0132> CMP0131: LINK_LIBRARIES supports the LINK_ONLY generator expression. </policy/CMP0131> diff --git a/Help/policy/CMP0134.rst b/Help/policy/CMP0134.rst new file mode 100644 index 0000000..2b562bc --- /dev/null +++ b/Help/policy/CMP0134.rst @@ -0,0 +1,39 @@ +CMP0134 +------- + +.. versionadded:: 3.24 + +The default registry view is ``TARGET`` for the :command:`find_file`, +:command:`find_path`, :command:`find_library`, and :command:`find_package` +commands and ``BOTH`` for the :command:`find_program` command. + +The default registry views in CMake 3.23 and below are selected using the +following rules: + +* if :variable:`CMAKE_SIZEOF_VOID_P` has value ``8``: + + * Use view ``64`` for all ``find_*`` commands except :command:`find_program` + command. + * Use view ``64_32`` for :command:`find_program` command. + +* if :variable:`CMAKE_SIZEOF_VOID_P` has value ``4`` or is undefined: + + * Use view ``32`` for all ``find_*`` commands except :command:`find_program` + command. + * Use view ``32_64`` for :command:`find_program` command. + +The ``OLD`` behavior for this policy is to use registry views ``64`` and +``64_32`` or ``32_64`` and ``32`` as default, depending of +:variable:`CMAKE_SIZEOF_VOID_P` variable value. +The ``NEW`` behavior for this policy is to use registry views ``TARGET`` and +``BOTH`` as default. + +This policy was introduced in CMake version 3.24. Use the +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` +explicitly. Unlike many policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0133 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/release/dev/find_item-query-windows-registry.rst b/Help/release/dev/find_item-query-windows-registry.rst new file mode 100644 index 0000000..ff0bd40 --- /dev/null +++ b/Help/release/dev/find_item-query-windows-registry.rst @@ -0,0 +1,6 @@ +find_item-query-windows-registry.rst +------------------------------------ + +* :command:`find_file`, :command:`find_path`, :command:`find_library`, + :command:`find_program`, and :command:`find_package` commands gain the + capability to specify which registry views must be queried. |