mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-05 21:31:08 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: cmake-developer: Add section for Windows registry access.

Browse Source 
Fixes: #23905
This commit is contained in:
Marc Chevrier
2022-09-04 16:06:01 +02:00
parent 0e7bb4e783
commit 5b30ca2436
1 changed files with 79 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
Help/manual/cmake-developer.7.rst
View File

@@ -18,6 +18,85 @@ See https://cmake.org/get-involved/ to get involved in development of
CMake upstream. It includes links to contribution instructions, which CMake upstream. It includes links to contribution instructions, which
in turn link to developer guides for CMake itself. in turn link to developer guides for CMake itself.
Accessing Windows Registry
==========================
CMake offers some facilities to access the registry on ``Windows`` platforms.
Query Windows Registry
----------------------
.. versionadded:: 3.24
The :command:`cmake_host_system_information` command offers the possibility to
query the registry on the local computer. See
:ref:`cmake_host_system(QUERY_WINDOWS_REGISTRY) <Query Windows registry>` for
more information.
.. _`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.
.. _`Find Modules`: .. _`Find Modules`:
Find Modules Find Modules
@@ -242,70 +321,6 @@ backwards compatibility for any old names that were actually in use.
Make sure you comment them as deprecated, so that no-one starts using Make sure you comment them as deprecated, so that no-one starts using
them. 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 A Sample Find Module
-------------------- --------------------