find_* commands: add control over Windows registry views

Fixes: #22775

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.

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.

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``

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`+

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|

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|

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``

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|

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::

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>

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

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.