summaryrefslogtreecommitdiffstats
path: root/Help/command
diff options
context:
space:
mode:
Diffstat (limited to 'Help/command')
-rw-r--r--Help/command/FIND_XXX.txt13
-rw-r--r--Help/command/FIND_XXX_REGISTRY_QUERY.txt43
-rw-r--r--Help/command/FIND_XXX_REGISTRY_VIEW.txt41
-rw-r--r--Help/command/add_custom_command.rst4
-rw-r--r--Help/command/find_file.rst2
-rw-r--r--Help/command/find_library.rst2
-rw-r--r--Help/command/find_package.rst38
-rw-r--r--Help/command/find_path.rst2
-rw-r--r--Help/command/find_program.rst2
9 files changed, 138 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::
generated by cgit v0.12 at 2024-12-29 09:22:09 (GMT)