mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-04-24 07:08:38 -05:00
Code Issues Packages Projects Releases Wiki Activity

Help: Avoid duplicating registry query syntax in multiple find_* commands

Browse Source 
In commit 8d7e80cf3d (find_* commands: add control over Windows registry
views, 2022-04-16) we added documentation that is repeated by multiple
find commands.  Move it to a dedicated manual section to avoid duplication.
This commit is contained in:
Marc Chevrier
2022-05-18 14:15:03 +02:00
committed by Brad King
parent 9f469d533d
commit 98af010b5c
4 changed files with 68 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Help/command/FIND_XXX.txt
+2 -4
View File
@@ -54,10 +54,8 @@ Options include:
.. 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
of the directories, using a :ref:`dedicated syntax <Find Using Windows Registry>`.
Such specifications will be ignored on all other platforms.
``REGISTRY_VIEW``
.. versionadded:: 3.24
Help/command/FIND_XXX_REGISTRY_QUERY.txt
-43
View File
@@ -1,43 +0,0 @@
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_package.rst
+3 -4
View File
@@ -309,10 +309,9 @@ that order).
.. 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
of the directories specified through ``HINTS`` and ``PATHS`` keywords, using
a :ref:`dedicated syntax <Find Using Windows Registry>`. Such specifications
will be ignored on all other platforms.
.. versionadded:: 3.24
``REGISTRY_VIEW`` can be specified to manage ``Windows`` registry queries
Help/manual/cmake-developer.7.rst
+63
View File
@@ -242,6 +242,69 @@ backwards compatibility for any old names that were actually in use.
Make sure you comment them as deprecated, so that no-one starts using
them.
.. _`Find Using Windows Registry`:
Find Using Windows Registry
---------------------------
.. versionchanged:: 3.24
Options ``HINTS`` and ``PATHS`` of :command:`find_file`,
:command:`find_library`, :command:`find_path`, :command:`find_program`, and
:command:`find_package` commands offer the possibility, on ``Windows``
platform, to query the registry.
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:
.. raw:: latex
\begin{small}
.. productionlist::
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`>
.. raw:: latex
\end{small}
The :token:`sep_definition` optional item offers the possibility to specify
the string used to separate the :token:`sub_key` from the :token:`value_name`
item. If not specified, the character ``;`` is used. Multiple
:token:`registry_query` items can be specified as part of a path.
.. code-block:: cmake
# example using default separator
find_file(... PATHS "/root/[HKLM/Stuff;InstallDir]/lib[HKLM\\\\Stuff;Architecture]")
# example using different specified separators
find_library(... HINTS "/root/[{|}HKCU/Stuff|InstallDir]/lib[{@@}HKCU\\\\Stuff@@Architecture]")
If the :token:`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 :token:`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.
A Sample Find Module
--------------------