1CMAKE-DEVELOPER(7)                   CMake                  CMAKE-DEVELOPER(7)
2
3
4

NAME

6       cmake-developer - CMake Developer Reference
7

INTRODUCTION

9       This  manual  is  intended  for  reference  by  developers working with
10       cmake-language(7) code, whether writing their  own  modules,  authoring
11       their own build systems, or working on CMake itself.
12
13       See  https://cmake.org/get-involved/  to get involved in development of
14       CMake upstream.  It includes links to contribution instructions,  which
15       in turn link to developer guides for CMake itself.
16

ACCESSING WINDOWS REGISTRY

18       CMake  offers  some  facilities to access the registry on Windows plat‐
19       forms.
20
21   Query Windows Registry
22       New in version 3.24.
23
24
25       The cmake_host_system_information() command offers the  possibility  to
26       query     the     registry     on     the     local    computer.    See
27       cmake_host_system(QUERY_WINDOWS_REGISTRY) for more information.
28
29   Find Using Windows Registry
30       Changed in version 3.24.
31
32
33       Options HINTS and PATHS of  find_file(),  find_library(),  find_path(),
34       find_program(),  and  find_package() commands offer the possibility, on
35       Windows platform, to query the registry.
36
37       The formal syntax, as specified using BNF notation with the regular ex‐
38       tensions, for registry query is the following:
39
40       registry_query  ::=  '[' sep_definition? root_key
41                                ((key_separator sub_key)? (value_separator value_name_)?)? ']'
42       sep_definition  ::=  '{' value_separator '}'
43       root_key        ::=  'HKLM' | 'HKEY_LOCAL_MACHINE' | 'HKCU' | 'HKEY_CURRENT_USER' |
44                            'HKCR' | 'HKEY_CLASSES_ROOT' | 'HKCC' | 'HKEY_CURRENT_CONFIG' |
45                            'HKU' | 'HKEY_USERS'
46       sub_key         ::=  element (key_separator element)*
47       key_separator   ::=  '/' | '\\'
48       value_separator ::=  element | ';'
49       value_name      ::=  element | '(default)'
50       element         ::=  character\+
51       character       ::=  <any character except key_separator and value_separator>
52
53
54       The  sep_definition optional item offers the possibility to specify the
55       string used to separate the sub_key from the value_name  item.  If  not
56       specified,  the  character ; is used. Multiple registry_query items can
57       be specified as part of a path.
58
59          # example using default separator
60          find_file(... PATHS "/root/[HKLM/Stuff;InstallDir]/lib[HKLM\\\\Stuff;Architecture]")
61
62          # example using different specified separators
63          find_library(... HINTS "/root/[{|}HKCU/Stuff|InstallDir]/lib[{@@}HKCU\\\\Stuff@@Architecture]")
64
65       If the value_name item is not specified or has the  special  name  (de‐
66       fault), the content of the default value, if any, will be returned. The
67       supported types for the value_name are:
68
69REG_SZ.
70
71REG_EXPAND_SZ. The returned data is expanded.
72
73REG_DWORD.
74
75REG_QWORD.
76
77       When the registry query failed, typically because the key does not  ex‐
78       ist or the data type is not supported, the string /REGISTRY-NOTFOUND is
79       substituted to the [] query expression.
80

FIND MODULES

82       A "find module" is a Find<PackageName>.cmake file to be loaded  by  the
83       find_package() command when invoked for <PackageName>.
84
85       The  primary task of a find module is to determine whether a package is
86       available, set the <PackageName>_FOUND variable  to  reflect  this  and
87       provide  any variables, macros and imported targets required to use the
88       package.  A find module is useful in cases where  an  upstream  library
89       does not provide a config file package.
90
91       The  traditional approach is to use variables for everything, including
92       libraries and executables: see the Standard Variable Names section  be‐
93       low.   This is what most of the existing find modules provided by CMake
94       do.
95
96       The more modern approach is to behave as much like config file packages
97       files  as  possible, by providing imported target.  This has the advan‐
98       tage of propagating Transitive Usage Requirements to consumers.
99
100       In either case (or even when providing both variables and imported tar‐
101       gets),  find  modules  should  provide backwards compatibility with old
102       versions that had the same name.
103
104       A FindFoo.cmake module will typically be loaded by the command:
105
106          find_package(Foo [major[.minor[.patch[.tweak]]]]
107                       [EXACT] [QUIET] [REQUIRED]
108                       [[COMPONENTS] [components...]]
109                       [OPTIONAL_COMPONENTS components...]
110                       [NO_POLICY_SCOPE])
111
112       See the find_package() documentation for details on what variables  are
113       set  for  the  find  module.   Most  of  these  are dealt with by using
114       FindPackageHandleStandardArgs.
115
116       Briefly, the module should only locate versions of the package compati‐
117       ble  with  the  requested version, as described by the Foo_FIND_VERSION
118       family of variables.  If Foo_FIND_QUIETLY is set  to  true,  it  should
119       avoid printing messages, including anything complaining about the pack‐
120       age not being found.  If Foo_FIND_REQUIRED is set to true,  the  module
121       should  issue a FATAL_ERROR if the package cannot be found.  If neither
122       are set to true, it should print a non-fatal message if it cannot  find
123       the package.
124
125       Packages that find multiple semi-independent parts (like bundles of li‐
126       braries) should search for the components listed in Foo_FIND_COMPONENTS
127       if  it is set , and only set Foo_FOUND to true if for each searched-for
128       component <c> that was not found, Foo_FIND_REQUIRED_<c> is not  set  to
129       true.   The  HANDLE_COMPONENTS  argument  of  find_package_handle_stan‐
130       dard_args() can be used to implement this.
131
132       If Foo_FIND_COMPONENTS is not set, which modules are searched  for  and
133       required is up to the find module, but should be documented.
134
135       For internal implementation, it is a generally accepted convention that
136       variables starting with underscore are for temporary use only.
137
138   Standard Variable Names
139       For a FindXxx.cmake module that takes the approach of setting variables
140       (either  instead  of  or in addition to creating imported targets), the
141       following variable names should be used to keep things  consistent  be‐
142       tween  Find  modules.   Note  that all variables start with Xxx_, which
143       (unless otherwise noted) must match  exactly  the  name  of  the  Find‐
144       Xxx.cmake file, including upper/lowercase.  This prefix on the variable
145       names ensures that they do not conflict with variables  of  other  Find
146       modules.   The  same  pattern  should  also be followed for any macros,
147       functions and imported targets defined by the Find module.
148
149       Xxx_INCLUDE_DIRS
150              The final set of include directories listed in one variable  for
151              use  by client code. This should not be a cache entry (note that
152              this also means this variable should not be used as  the  result
153              variable  of  a  find_path() command - see Xxx_INCLUDE_DIR below
154              for that).
155
156       Xxx_LIBRARIES
157              The libraries to use with the module.  These may be  CMake  tar‐
158              gets,  full  absolute paths to a library binary or the name of a
159              library that the linker must find  in  its  search  path.   This
160              should  not  be  a  cache  entry (note that this also means this
161              variable should  not  be  used  as  the  result  variable  of  a
162              find_library() command - see Xxx_LIBRARY below for that).
163
164       Xxx_DEFINITIONS
165              The compile definitions to use when compiling code that uses the
166              module.   This  really  shouldn't  include   options   such   as
167              -DHAS_JPEG that a client source-code file uses to decide whether
168              to #include <jpeg.h>
169
170       Xxx_EXECUTABLE
171              The full absolute path to an  executable.   In  this  case,  Xxx
172              might not be the name of the module, it might be the name of the
173              tool (usually converted to all uppercase),  assuming  that  tool
174              has such a well-known name that it is unlikely that another tool
175              with the same name exists.  It would be appropriate to use  this
176              as the result variable of a find_program() command.
177
178       Xxx_YYY_EXECUTABLE
179              Similar to Xxx_EXECUTABLE except here the Xxx is always the mod‐
180              ule name and YYY is the tool name (again, usually  fully  upper‐
181              case).   Prefer  this  form  if the tool name is not very widely
182              known or has the potential  to clash  with  another  tool.   For
183              greater  consistency,  also  prefer this form if the module pro‐
184              vides more than one executable.
185
186       Xxx_LIBRARY_DIRS
187              Optionally, the final set of library directories listed  in  one
188              variable  for use by client code. This should not be a cache en‐
189              try.
190
191       Xxx_ROOT_DIR
192              Where to find the base directory of the module.
193
194       Xxx_VERSION_VV
195              Variables of this form specify whether the Xxx module being pro‐
196              vided  is  version  VV  of the module.  There should not be more
197              than one variable of this form set to true for a  given  module.
198              For  example,  a module Barry might have evolved over many years
199              and gone through a number of different major versions.   Version
200              3  of the Barry module might set the variable Barry_VERSION_3 to
201              true,  whereas  an  older  version  of  the  module  might   set
202              Barry_VERSION_2  to true instead.  It would be an error for both
203              Barry_VERSION_3 and Barry_VERSION_2 to both be set to true.
204
205       Xxx_WRAP_YY
206              When a variable of this form is set to false, it indicates  that
207              the  relevant wrapping command should not be used.  The wrapping
208              command depends on the module, it may be implied by  the  module
209              name or it might be specified by the YY part of the variable.
210
211       Xxx_Yy_FOUND
212              For  variables  of  this form, Yy is the name of a component for
213              the module.  It should match exactly one of the valid  component
214              names  that  may be passed to the find_package() command for the
215              module.  If a variable of this form is set to  false,  it  means
216              that  the  Yy  component  of  module Xxx was not found or is not
217              available.  Variables of this form would typically be  used  for
218              optional  components so that the caller can check whether an op‐
219              tional component is available.
220
221       Xxx_FOUND
222              When the find_package() command  returns  to  the  caller,  this
223              variable  will  be  set to true if the module was deemed to have
224              been found successfully.
225
226       Xxx_NOT_FOUND_MESSAGE
227              Should be set by config-files  in  the  case  that  it  has  set
228              Xxx_FOUND  to  FALSE.   The contained message will be printed by
229              the        find_package()         command         and         by
230              find_package_handle_standard_args() to inform the user about the
231              problem.  Use this instead of calling message() directly to  re‐
232              port a reason for failing to find the module or package.
233
234       Xxx_RUNTIME_LIBRARY_DIRS
235              Optionally, the runtime library search path for use when running
236              an executable linked to shared libraries.  The  list  should  be
237              used  by  user  code  to  create  the  PATH on windows or LD_LI‐
238              BRARY_PATH on UNIX.  This should not be a cache entry.
239
240       Xxx_VERSION
241              The full version string of the package found, if any.  Note that
242              many existing modules provide Xxx_VERSION_STRING instead.
243
244       Xxx_VERSION_MAJOR
245              The major version of the package found, if any.
246
247       Xxx_VERSION_MINOR
248              The minor version of the package found, if any.
249
250       Xxx_VERSION_PATCH
251              The patch version of the package found, if any.
252
253       The following names should not usually be used in CMakeLists.txt files.
254       They are intended for use by Find modules to specify and cache the  lo‐
255       cations  of specific files or directories.  Users are typically able to
256       set and edit these variables to control the behavior  of  Find  modules
257       (like entering the path to a library manually):
258
259       Xxx_LIBRARY
260              The  path  of  the  library.  Use this form only when the module
261              provides a single library.  It is appropriate to use this as the
262              result variable in a find_library() command.
263
264       Xxx_Yy_LIBRARY
265              The  path  of  library  Yy provided by the module Xxx.  Use this
266              form when the module provides more than  one  library  or  where
267              other modules may also provide a library of the same name. It is
268              also appropriate to use this form as the result  variable  in  a
269              find_library() command.
270
271       Xxx_INCLUDE_DIR
272              When  the  module  provides only a single library, this variable
273              can be used to specify where to find headers for using  the  li‐
274              brary  (or  more  accurately, the path that consumers of the li‐
275              brary should add to their header search path).  It would be  ap‐
276              propriate  to  use  this as the result variable in a find_path()
277              command.
278
279       Xxx_Yy_INCLUDE_DIR
280              If the module provides more than one library or where other mod‐
281              ules  may  also provide a library of the same name, this form is
282              recommended for specifying where to find headers for  using  li‐
283              brary Yy provided by the module.  Again, it would be appropriate
284              to use this as the result variable in a find_path() command.
285
286       To prevent users being overwhelmed with settings to configure,  try  to
287       keep as many options as possible out of the cache, leaving at least one
288       option which can be used to disable use of  the  module,  or  locate  a
289       not-found  library (e.g. Xxx_ROOT_DIR).  For the same reason, mark most
290       cache options as advanced.  For packages which provide both  debug  and
291       release  binaries,  it  is common to create cache variables with a _LI‐
292       BRARY_<CONFIG> suffix, such as Foo_LIBRARY_RELEASE and  Foo_LIBRARY_DE‐
293       BUG.   The  SelectLibraryConfigurations  module can be helpful for such
294       cases.
295
296       While these are the standard variable names, you should  provide  back‐
297       wards  compatibility for any old names that were actually in use.  Make
298       sure you comment them as deprecated, so that no-one starts using them.
299
300   A Sample Find Module
301       We will describe how to create a simple find module for a library Foo.
302
303       The top of the module should begin with a license notice, followed by a
304       blank line, and then followed by a Bracket Comment.  The comment should
305       begin with .rst: to indicate that the rest of its content  is  reStruc‐
306       turedText-format documentation.  For example:
307
308          # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
309          # file Copyright.txt or https://cmake.org/licensing for details.
310
311          #[=======================================================================[.rst:
312          FindFoo
313          -------
314
315          Finds the Foo library.
316
317          Imported Targets
318          ^^^^^^^^^^^^^^^^
319
320          This module provides the following imported targets, if found:
321
322          ``Foo::Foo``
323            The Foo library
324
325          Result Variables
326          ^^^^^^^^^^^^^^^^
327
328          This will define the following variables:
329
330          ``Foo_FOUND``
331            True if the system has the Foo library.
332          ``Foo_VERSION``
333            The version of the Foo library which was found.
334          ``Foo_INCLUDE_DIRS``
335            Include directories needed to use Foo.
336          ``Foo_LIBRARIES``
337            Libraries needed to link to Foo.
338
339          Cache Variables
340          ^^^^^^^^^^^^^^^
341
342          The following cache variables may also be set:
343
344          ``Foo_INCLUDE_DIR``
345            The directory containing ``foo.h``.
346          ``Foo_LIBRARY``
347            The path to the Foo library.
348
349          #]=======================================================================]
350
351       The module documentation consists of:
352
353       • An underlined heading specifying the module name.
354
355       • A  simple description of what the module finds.  More description may
356         be required for some packages.  If there are caveats or other details
357         users of the module should be aware of, specify them here.
358
359       • A section listing imported targets provided by the module, if any.
360
361       • A section listing result variables provided by the module.
362
363       • Optionally  a  section listing cache variables used by the module, if
364         any.
365
366       If the package provides any macros or functions, they should be  listed
367       in  an  additional  section,  but can be documented by additional .rst:
368       comment blocks immediately above where those macros  or  functions  are
369       defined.
370
371       The find module implementation may begin below the documentation block.
372       Now the actual libraries and so on have to be  found.   The  code  here
373       will  obviously  vary  from  module to module (dealing with that, after
374       all, is the point of find modules), but there tends to be a common pat‐
375       tern for libraries.
376
377       First, we try to use pkg-config to find the library.  Note that we can‐
378       not rely on this, as it may not be available, but it  provides  a  good
379       starting point.
380
381          find_package(PkgConfig)
382          pkg_check_modules(PC_Foo QUIET Foo)
383
384       This should define some variables starting PC_Foo_ that contain the in‐
385       formation from the Foo.pc file.
386
387       Now we need to find the libraries and include files; we use the  infor‐
388       mation from pkg-config to provide hints to CMake about where to look.
389
390          find_path(Foo_INCLUDE_DIR
391            NAMES foo.h
392            PATHS ${PC_Foo_INCLUDE_DIRS}
393            PATH_SUFFIXES Foo
394          )
395          find_library(Foo_LIBRARY
396            NAMES foo
397            PATHS ${PC_Foo_LIBRARY_DIRS}
398          )
399
400       Alternatively,  if  the  library  is available with multiple configura‐
401       tions, you can use SelectLibraryConfigurations to automatically set the
402       Foo_LIBRARY variable instead:
403
404          find_library(Foo_LIBRARY_RELEASE
405            NAMES foo
406            PATHS ${PC_Foo_LIBRARY_DIRS}/Release
407          )
408          find_library(Foo_LIBRARY_DEBUG
409            NAMES foo
410            PATHS ${PC_Foo_LIBRARY_DIRS}/Debug
411          )
412
413          include(SelectLibraryConfigurations)
414          select_library_configurations(Foo)
415
416       If  you have a good way of getting the version (from a header file, for
417       example), you can use that information  to  set  Foo_VERSION  (although
418       note  that  find modules have traditionally used Foo_VERSION_STRING, so
419       you may want to set both).  Otherwise, attempt to use  the  information
420       from pkg-config
421
422          set(Foo_VERSION ${PC_Foo_VERSION})
423
424       Now  we can use FindPackageHandleStandardArgs to do most of the rest of
425       the work for us
426
427          include(FindPackageHandleStandardArgs)
428          find_package_handle_standard_args(Foo
429            FOUND_VAR Foo_FOUND
430            REQUIRED_VARS
431              Foo_LIBRARY
432              Foo_INCLUDE_DIR
433            VERSION_VAR Foo_VERSION
434          )
435
436       This will check that the REQUIRED_VARS contain values (that do not  end
437       in  -NOTFOUND)  and  set  Foo_FOUND  appropriately.  It will also cache
438       those values.  If Foo_VERSION is set, and a required version was passed
439       to  find_package(), it will check the requested version against the one
440       in Foo_VERSION.  It will also print messages as appropriate; note  that
441       if  the  package was found, it will print the contents of the first re‐
442       quired variable to indicate where it was found.
443
444       At this point, we have to provide a way for users of the find module to
445       link  to  the  library or libraries that were found.  There are two ap‐
446       proaches, as discussed in the Find Modules section above.   The  tradi‐
447       tional variable approach looks like
448
449          if(Foo_FOUND)
450            set(Foo_LIBRARIES ${Foo_LIBRARY})
451            set(Foo_INCLUDE_DIRS ${Foo_INCLUDE_DIR})
452            set(Foo_DEFINITIONS ${PC_Foo_CFLAGS_OTHER})
453          endif()
454
455       If  more  than one library was found, all of them should be included in
456       these variables (see the Standard Variable Names section for  more  in‐
457       formation).
458
459       When  providing imported targets, these should be namespaced (hence the
460       Foo::  prefix);  CMake   will   recognize   that   values   passed   to
461       target_link_libraries()  that  contain :: in their name are supposed to
462       be imported targets (rather than just library names), and will  produce
463       appropriate diagnostic messages if that target does not exist (see pol‐
464       icy CMP0028).
465
466          if(Foo_FOUND AND NOT TARGET Foo::Foo)
467            add_library(Foo::Foo UNKNOWN IMPORTED)
468            set_target_properties(Foo::Foo PROPERTIES
469              IMPORTED_LOCATION "${Foo_LIBRARY}"
470              INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}"
471              INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"
472            )
473          endif()
474
475       One thing to note about this is that the  INTERFACE_INCLUDE_DIRECTORIES
476       and similar properties should only contain information about the target
477       itself, and not any of its dependencies.  Instead,  those  dependencies
478       should  also  be targets, and CMake should be told that they are depen‐
479       dencies of this target.  CMake will then combine all the necessary  in‐
480       formation automatically.
481
482       The  type  of  the IMPORTED target created in the add_library() command
483       can always be specified as UNKNOWN type.  This simplifies the  code  in
484       cases  where static or shared variants may be found, and CMake will de‐
485       termine the type by inspecting the files.
486
487       If  the  library  is  available  with  multiple   configurations,   the
488       IMPORTED_CONFIGURATIONS target property should also be populated:
489
490          if(Foo_FOUND)
491            if (NOT TARGET Foo::Foo)
492              add_library(Foo::Foo UNKNOWN IMPORTED)
493            endif()
494            if (Foo_LIBRARY_RELEASE)
495              set_property(TARGET Foo::Foo APPEND PROPERTY
496                IMPORTED_CONFIGURATIONS RELEASE
497              )
498              set_target_properties(Foo::Foo PROPERTIES
499                IMPORTED_LOCATION_RELEASE "${Foo_LIBRARY_RELEASE}"
500              )
501            endif()
502            if (Foo_LIBRARY_DEBUG)
503              set_property(TARGET Foo::Foo APPEND PROPERTY
504                IMPORTED_CONFIGURATIONS DEBUG
505              )
506              set_target_properties(Foo::Foo PROPERTIES
507                IMPORTED_LOCATION_DEBUG "${Foo_LIBRARY_DEBUG}"
508              )
509            endif()
510            set_target_properties(Foo::Foo PROPERTIES
511              INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}"
512              INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"
513            )
514          endif()
515
516       The  RELEASE variant should be listed first in the property so that the
517       variant is chosen if the user uses a configuration which is not an  ex‐
518       act match for any listed IMPORTED_CONFIGURATIONS.
519
520       Most  of  the  cache variables should be hidden in the ccmake interface
521       unless the user explicitly asks to edit them.
522
523          mark_as_advanced(
524            Foo_INCLUDE_DIR
525            Foo_LIBRARY
526          )
527
528       If this module replaces an older version, you should set  compatibility
529       variables to cause the least disruption possible.
530
531          # compatibility variables
532          set(Foo_VERSION_STRING ${Foo_VERSION})
533
535       2000-2023 Kitware, Inc. and Contributors
536
537
538
539
5403.25.2                           Jan 19, 2023               CMAKE-DEVELOPER(7)
Impressum