CMAKE-DEVELOPER(7) CMake CMAKE-DEVELOPER(7)
NAME
cmake-developer - CMake Developer Reference
INTRODUCTION
This manual is intended for reference by developers working with
cmake-language(7) code, whether writing their own modules, authoring
their own build systems, or working on CMake itself.
See https://cmake.org/get-involved/ to get involved in development of
CMake upstream. It includes links to contribution instructions, which
in turn link to developer guides for CMake itself.
FIND MODULES
A find module is a Find<PackageName>.cmake file to be loaded by the
find_package() command when invoked for <PackageName>.
The primary task of a find module is to determine whether a package ex-
ists on the system, set the <PackageName>_FOUND variable to reflect
this and provide any variables, macros and imported targets required to
use the package. A find module is useful in cases where an upstream
library does not provide a config file package.
The traditional approach is to use variables for everything, including
libraries and executables: see the Standard Variable Names section be-
low. This is what most of the existing find modules provided by CMake
do.
The more modern approach is to behave as much like config file packages
files as possible, by providing imported target. This has the advan-
tage of propagating Target Usage Requirements to consumers.
In either case (or even when providing both variables and imported tar-
gets), find modules should provide backwards compatibility with old
versions that had the same name.
A FindFoo.cmake module will typically be loaded by the command:
find_package(Foo [major[.minor[.patch[.tweak]]]]
[EXACT] [QUIET] [REQUIRED]
[[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...]
[NO_POLICY_SCOPE])
See the find_package() documentation for details on what variables are
set for the find module. Most of these are dealt with by using Find-
PackageHandleStandardArgs.
Briefly, the module should only locate versions of the package compati-
ble with the requested version, as described by the Foo_FIND_VERSION
family of variables. If Foo_FIND_QUIETLY is set to true, it should
avoid printing messages, including anything complaining about the pack-
age not being found. If Foo_FIND_REQUIRED is set to true, the module
should issue a FATAL_ERROR if the package cannot be found. If neither
are set to true, it should print a non-fatal message if it cannot find
the package.
Packages that find multiple semi-independent parts (like bundles of li-
braries) should search for the components listed in Foo_FIND_COMPONENTS
if it is set , and only set Foo_FOUND to true if for each searched-for
component <c> that was not found, Foo_FIND_REQUIRED_<c> is not set to
true. The HANDLE_COMPONENTS argument of find_package_handle_stan-
dard_args() can be used to implement this.
If Foo_FIND_COMPONENTS is not set, which modules are searched for and
required is up to the find module, but should be documented.
For internal implementation, it is a generally accepted convention that
variables starting with underscore are for temporary use only.
Standard Variable Names
For a FindXxx.cmake module that takes the approach of setting variables
(either instead of or in addition to creating imported targets), the
following variable names should be used to keep things consistent be-
tween find modules. Note that all variables start with Xxx_ to make
sure they do not interfere with other find modules; the same considera-
tion applies to macros, functions and imported targets.
Xxx_INCLUDE_DIRS
The final set of include directories listed in one variable for
use by client code. This should not be a cache entry.
Xxx_LIBRARIES
The libraries to link against to use Xxx. These should include
full paths. This should not be a cache entry.
Xxx_DEFINITIONS
Definitions to use when compiling code that uses Xxx. This re-
ally shouldnt include options such as -DHAS_JPEG that a client
source-code file uses to decide whether to #include <jpeg.h>
Xxx_EXECUTABLE
Where to find the Xxx tool.
Xxx_Yyy_EXECUTABLE
Where to find the Yyy tool that comes with Xxx.
Xxx_LIBRARY_DIRS
Optionally, the final set of library directories listed in one
variable for use by client code. This should not be a cache en-
try.
Xxx_ROOT_DIR
Where to find the base directory of Xxx.
Xxx_VERSION_Yy
Expect Version Yy if true. Make sure at most one of these is
ever true.
Xxx_WRAP_Yy
If False, do not try to use the relevant CMake wrapping command.
Xxx_Yy_FOUND
If False, optional Yy part of Xxx system is not available.
Xxx_FOUND
Set to false, or undefined, if we havent found, or dont want to
use Xxx.
Xxx_NOT_FOUND_MESSAGE
Should be set by config-files in the case that it has set
Xxx_FOUND to FALSE. The contained message will be printed by
the find_package() command and by find_package_handle_stan-
dard_args() to inform the user about the problem.
Xxx_RUNTIME_LIBRARY_DIRS
Optionally, the runtime library search path for use when running
an executable linked to shared libraries. The list should be
used by user code to create the PATH on windows or LD_LI-
BRARY_PATH on UNIX. This should not be a cache entry.
Xxx_VERSION
The full version string of the package found, if any. Note that
many existing modules provide Xxx_VERSION_STRING instead.
Xxx_VERSION_MAJOR
The major version of the package found, if any.
Xxx_VERSION_MINOR
The minor version of the package found, if any.
Xxx_VERSION_PATCH
The patch version of the package found, if any.
The following names should not usually be used in CMakeLists.txt files,
but are typically cache variables for users to edit and control the be-
haviour of find modules (like entering the path to a library manually)
Xxx_LIBRARY
The path of the Xxx library (as used with find_library(), for
example).
Xxx_Yy_LIBRARY
The path of the Yy library that is part of the Xxx system. It
may or may not be required to use Xxx.
Xxx_INCLUDE_DIR
Where to find headers for using the Xxx library.
Xxx_Yy_INCLUDE_DIR
Where to find headers for using the Yy library of the Xxx sys-
tem.
To prevent users being overwhelmed with settings to configure, try to
keep as many options as possible out of the cache, leaving at least one
option which can be used to disable use of the module, or locate a
not-found library (e.g. Xxx_ROOT_DIR). For the same reason, mark most
cache options as advanced. For packages which provide both debug and
release binaries, it is common to create cache variables with a _LI-
BRARY_<CONFIG> suffix, such as Foo_LIBRARY_RELEASE and Foo_LIBRARY_DE-
BUG.
While these are the standard variable names, you should provide back-
wards compatibility for any old names that were actually in use. Make
sure you comment them as deprecated, so that no-o.
CMAKE-DEVELOPER(7) CMake CMAKE-DEVELOPER(7)
NAME
cmake-developer - CMake Developer Reference
INTRODUCTION
This manual is intended for reference by developers working with
cmake-language(7) code, whether writing their own modules, authoring
their own build systems, or working on CMake itself.
See https://cmake.org/get-involved/ to get involved in development of
CMake upstream. It includes links to contribution instructions, which
in turn link to developer guides for CMake itself.
FIND MODULES
A find module is a Find<PackageName>.cmake file to be loaded by the
find_package() command when invoked for <PackageName>.
The primary task of a find module is to determine whether a package ex-
ists on the system, set the <PackageName>_FOUND variable to reflect
this and provide any variables, macros and imported targets required to
use the package. A find module is useful in cases where an upstream
library does not provide a config file package.
The traditional approach is to use variables for everything, including
libraries and executables: see the Standard Variable Names section be-
low. This is what most of the existing find modules provided by CMake
do.
The more modern approach is to behave as much like config file packages
files as possible, by providing imported target. This has the advan-
tage of propagating Target Usage Requirements to consumers.
In either case (or even when providing both variables and imported tar-
gets), find modules should provide backwards compatibility with old
versions that had the same name.
A FindFoo.cmake module will typically be loaded by the command:
find_package(Foo [major[.minor[.patch[.tweak]]]]
[EXACT] [QUIET] [REQUIRED]
[[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...]
[NO_POLICY_SCOPE])
See the find_package() documentation for details on what variables are
set for the find module. Most of these are dealt with by using Find-
PackageHandleStandardArgs.
Briefly, the module should only locate versions of the package compati-
ble with the requested version, as described by the Foo_FIND_VERSION
family of variables. If Foo_FIND_QUIETLY is set to true, it should
avoid printing messages, including anything complaining about the pack-
age not being found. If Foo_FIND_REQUIRED is set to true, the module
should issue a FATAL_ERROR if the package cannot be found. If neither
are set to true, it should print a non-fatal message if it cannot find
the package.
Packages that find multiple semi-independent parts (like bundles of li-
braries) should search for the components listed in Foo_FIND_COMPONENTS
if it is set , and only set Foo_FOUND to true if for each searched-for
component <c> that was not found, Foo_FIND_REQUIRED_<c> is not set to
true. The HANDLE_COMPONENTS argument of find_package_handle_stan-
dard_args() can be used to implement this.
If Foo_FIND_COMPONENTS is not set, which modules are searched for and
required is up to the find module, but should be documented.
For internal implementation, it is a generally accepted convention that
variables starting with underscore are for temporary use only.
Standard Variable Names
For a FindXxx.cmake module that takes the approach of setting variables
(either instead of or in addition to creating imported targets), the
following variable names should be used to keep things consistent be-
tween find modules. Note that all variables start with Xxx_ to make
sure they do not interfere with other find modules; the same considera-
tion applies to macros, functions and imported targets.
Xxx_INCLUDE_DIRS
The final set of include directories listed in one variable for
use by client code. This should not be a cache entry.
Xxx_LIBRARIES
The libraries to link against to use Xxx. These should include
full paths. This should not be a cache entry.
Xxx_DEFINITIONS
Definitions to use when compiling code that uses Xxx. This re-
ally shouldnt include options such as -DHAS_JPEG that a client
source-code file uses to decide whether to #include <jpeg.h>
Xxx_EXECUTABLE
Where to find the Xxx tool.
Xxx_Yyy_EXECUTABLE
Where to find the Yyy tool that comes with Xxx.
Xxx_LIBRARY_DIRS
Optionally, the final set of library directories listed in one
variable for use by client code. This should not be a cache en-
try.
Xxx_ROOT_DIR
Where to find the base directory of Xxx.
Xxx_VERSION_Yy
Expect Version Yy if true. Make sure at most one of these is
ever true.
Xxx_WRAP_Yy
If False, do not try to use the relevant CMake wrapping command.
Xxx_Yy_FOUND
If False, optional Yy part of Xxx system is not available.
Xxx_FOUND
Set to false, or undefined, if we havent found, or dont want to
use Xxx.
Xxx_NOT_FOUND_MESSAGE
Should be set by config-files in the case that it has set
Xxx_FOUND to FALSE. The contained message will be printed by
the find_package() command and by find_package_handle_stan-
dard_args() to inform the user about the problem.
Xxx_RUNTIME_LIBRARY_DIRS
Optionally, the runtime library search path for use when running
an executable linked to shared libraries. The list should be
used by user code to create the PATH on windows or LD_LI-
BRARY_PATH on UNIX. This should not be a cache entry.
Xxx_VERSION
The full version string of the package found, if any. Note that
many existing modules provide Xxx_VERSION_STRING instead.
Xxx_VERSION_MAJOR
The major version of the package found, if any.
Xxx_VERSION_MINOR
The minor version of the package found, if any.
Xxx_VERSION_PATCH
The patch version of the package found, if any.
The following names should not usually be used in CMakeLists.txt files,
but are typically cache variables for users to edit and control the be-
haviour of find modules (like entering the path to a library manually)
Xxx_LIBRARY
The path of the Xxx library (as used with find_library(), for
example).
Xxx_Yy_LIBRARY
The path of the Yy library that is part of the Xxx system. It
may or may not be required to use Xxx.
Xxx_INCLUDE_DIR
Where to find headers for using the Xxx library.
Xxx_Yy_INCLUDE_DIR
Where to find headers for using the Yy library of the Xxx sys-
tem.
To prevent users being overwhelmed with settings to configure, try to
keep as many options as possible out of the cache, leaving at least one
option which can be used to disable use of the module, or locate a
not-found library (e.g. Xxx_ROOT_DIR). For the same reason, mark most
cache options as advanced. For packages which provide both debug and
release binaries, it is common to create cache variables with a _LI-
BRARY_<CONFIG> suffix, such as Foo_LIBRARY_RELEASE and Foo_LIBRARY_DE-
BUG.
While these are the standard variable names, you should provide back-
wards compatibility for any old names that were actually in use. Make
sure you comment them as deprecated, so that no-o.
CMAKE-DEVELOPER(7) CMake CMAKE-DEVELOPER(7)
NAME
cmake-developer - CMake Developer Reference
3.18.4 September 13, 2021 CMAKE-DEVELOPER(7)
Czas wygenerowania: 0.00044 sek.
Created with the man page lookup class by Andrew Collington.
Based on a C man page viewer by Vadim Pavlov
Unicode soft-hyphen fix (as used by RedHat) by Dan Edwards
Some optimisations by Eli Argon
Caching idea and code contribution by James Richardson
Copyright © 2003-2025 Linux.pl
Hosted by Hosting Linux.pl