| .\" Man page generated from reStructuredText. |
| . |
| .TH "CMAKE-DEVELOPER" "7" "Apr 12, 2022" "3.23.1" "CMake" |
| .SH NAME |
| cmake-developer \- CMake Developer Reference |
| . |
| .nr rst2man-indent-level 0 |
| . |
| .de1 rstReportMargin |
| \\$1 \\n[an-margin] |
| level \\n[rst2man-indent-level] |
| level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| - |
| \\n[rst2man-indent0] |
| \\n[rst2man-indent1] |
| \\n[rst2man-indent2] |
| .. |
| .de1 INDENT |
| .\" .rstReportMargin pre: |
| . RS \\$1 |
| . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] |
| . nr rst2man-indent-level +1 |
| .\" .rstReportMargin post: |
| .. |
| .de UNINDENT |
| . RE |
| .\" indent \\n[an-margin] |
| .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| .nr rst2man-indent-level -1 |
| .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| .in \\n[rst2man-indent\\n[rst2man-indent-level]]u |
| .. |
| .SH INTRODUCTION |
| .sp |
| This manual is intended for reference by developers working with |
| \fBcmake\-language(7)\fP code, whether writing their own modules, |
| authoring their own build systems, or working on CMake itself. |
| .sp |
| See \fI\%https://cmake.org/get\-involved/\fP to get involved in development of |
| CMake upstream. It includes links to contribution instructions, which |
| in turn link to developer guides for CMake itself. |
| .SH FIND MODULES |
| .sp |
| A "find module" is a \fBFind<PackageName>.cmake\fP file to be loaded by the |
| \fBfind_package()\fP command when invoked for \fB<PackageName>\fP\&. |
| .sp |
| The primary task of a find module is to determine whether a package is |
| available, set the \fB<PackageName>_FOUND\fP 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\&. |
| .sp |
| The traditional approach is to use variables for everything, including |
| libraries and executables: see the \fI\%Standard Variable Names\fP section |
| below. This is what most of the existing find modules provided by CMake |
| do. |
| .sp |
| The more modern approach is to behave as much like |
| config file packages files as possible, by |
| providing imported target\&. This has the advantage |
| of propagating Target Usage Requirements to consumers. |
| .sp |
| In either case (or even when providing both variables and imported |
| targets), find modules should provide backwards compatibility with old |
| versions that had the same name. |
| .sp |
| A FindFoo.cmake module will typically be loaded by the command: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Foo [major[.minor[.patch[.tweak]]]] |
| [EXACT] [QUIET] [REQUIRED] |
| [[COMPONENTS] [components...]] |
| [OPTIONAL_COMPONENTS components...] |
| [NO_POLICY_SCOPE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| See the \fBfind_package()\fP documentation for details on what |
| variables are set for the find module. Most of these are dealt with by |
| using \fBFindPackageHandleStandardArgs\fP\&. |
| .sp |
| Briefly, the module should only locate versions of the package |
| compatible with the requested version, as described by the |
| \fBFoo_FIND_VERSION\fP family of variables. If \fBFoo_FIND_QUIETLY\fP is |
| set to true, it should avoid printing messages, including anything |
| complaining about the package not being found. If \fBFoo_FIND_REQUIRED\fP |
| is set to true, the module should issue a \fBFATAL_ERROR\fP 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. |
| .sp |
| Packages that find multiple semi\-independent parts (like bundles of |
| libraries) should search for the components listed in |
| \fBFoo_FIND_COMPONENTS\fP if it is set , and only set \fBFoo_FOUND\fP to |
| true if for each searched\-for component \fB<c>\fP that was not found, |
| \fBFoo_FIND_REQUIRED_<c>\fP is not set to true. The \fBHANDLE_COMPONENTS\fP |
| argument of \fBfind_package_handle_standard_args()\fP can be used to |
| implement this. |
| .sp |
| If \fBFoo_FIND_COMPONENTS\fP is not set, which modules are searched for |
| and required is up to the find module, but should be documented. |
| .sp |
| For internal implementation, it is a generally accepted convention that |
| variables starting with underscore are for temporary use only. |
| .SS Standard Variable Names |
| .sp |
| For a \fBFindXxx.cmake\fP 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 between Find modules. Note that all variables start with |
| \fBXxx_\fP, which (unless otherwise noted) must match exactly the name |
| of the \fBFindXxx.cmake\fP file, including upper/lowercase. |
| This prefix on the variable names ensures that they do not conflict with |
| variables of other Find modules. The same pattern should also be followed |
| for any macros, functions and imported targets defined by the Find module. |
| .INDENT 0.0 |
| .TP |
| .B \fBXxx_INCLUDE_DIRS\fP |
| The final set of include directories listed in one variable for use by |
| client code. This should not be a cache entry (note that this also means |
| this variable should not be used as the result variable of a |
| \fBfind_path()\fP command \- see \fBXxx_INCLUDE_DIR\fP below for that). |
| .TP |
| .B \fBXxx_LIBRARIES\fP |
| The libraries to use with the module. These may be CMake targets, full |
| absolute paths to a library binary or the name of a library that the |
| linker must find in its search path. This should not be a cache entry |
| (note that this also means this variable should not be used as the |
| result variable of a \fBfind_library()\fP command \- see |
| \fBXxx_LIBRARY\fP below for that). |
| .TP |
| .B \fBXxx_DEFINITIONS\fP |
| The compile definitions to use when compiling code that uses the module. |
| This really shouldn\(aqt include options such as \fB\-DHAS_JPEG\fP that a client |
| source\-code file uses to decide whether to \fB#include <jpeg.h>\fP |
| .TP |
| .B \fBXxx_EXECUTABLE\fP |
| The full absolute path to an executable. In this case, \fBXxx\fP might not |
| be the name of the module, it might be the name of the tool (usually |
| converted to all uppercase), assuming that tool has such a well\-known name |
| that it is unlikely that another tool with the same name exists. It would |
| be appropriate to use this as the result variable of a |
| \fBfind_program()\fP command. |
| .TP |
| .B \fBXxx_YYY_EXECUTABLE\fP |
| Similar to \fBXxx_EXECUTABLE\fP except here the \fBXxx\fP is always the module |
| name and \fBYYY\fP is the tool name (again, usually fully uppercase). |
| Prefer this form if the tool name is not very widely known or has the |
| potential to clash with another tool. For greater consistency, also |
| prefer this form if the module provides more than one executable. |
| .TP |
| .B \fBXxx_LIBRARY_DIRS\fP |
| Optionally, the final set of library directories listed in one |
| variable for use by client code. This should not be a cache entry. |
| .TP |
| .B \fBXxx_ROOT_DIR\fP |
| Where to find the base directory of the module. |
| .TP |
| .B \fBXxx_VERSION_VV\fP |
| Variables of this form specify whether the \fBXxx\fP module being provided |
| is version \fBVV\fP of the module. There should not be more than one |
| variable of this form set to true for a given module. For example, a |
| module \fBBarry\fP might have evolved over many years and gone through a |
| number of different major versions. Version 3 of the \fBBarry\fP module |
| might set the variable \fBBarry_VERSION_3\fP to true, whereas an older |
| version of the module might set \fBBarry_VERSION_2\fP to true instead. |
| It would be an error for both \fBBarry_VERSION_3\fP and \fBBarry_VERSION_2\fP |
| to both be set to true. |
| .TP |
| .B \fBXxx_WRAP_YY\fP |
| When a variable of this form is set to false, it indicates that the |
| relevant wrapping command should not be used. The wrapping command |
| depends on the module, it may be implied by the module name or it might |
| be specified by the \fBYY\fP part of the variable. |
| .TP |
| .B \fBXxx_Yy_FOUND\fP |
| For variables of this form, \fBYy\fP is the name of a component for the |
| module. It should match exactly one of the valid component names that |
| may be passed to the \fBfind_package()\fP command for the module. |
| If a variable of this form is set to false, it means that the \fBYy\fP |
| component of module \fBXxx\fP was not found or is not available. |
| Variables of this form would typically be used for optional components |
| so that the caller can check whether an optional component is available. |
| .TP |
| .B \fBXxx_FOUND\fP |
| When the \fBfind_package()\fP command returns to the caller, this |
| variable will be set to true if the module was deemed to have been found |
| successfully. |
| .TP |
| .B \fBXxx_NOT_FOUND_MESSAGE\fP |
| Should be set by config\-files in the case that it has set |
| \fBXxx_FOUND\fP to FALSE. The contained message will be printed by the |
| \fBfind_package()\fP command and by |
| \fBfind_package_handle_standard_args()\fP to inform the user about the |
| problem. Use this instead of calling \fBmessage()\fP directly to |
| report a reason for failing to find the module or package. |
| .TP |
| .B \fBXxx_RUNTIME_LIBRARY_DIRS\fP |
| 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 \fBPATH\fP on windows or \fBLD_LIBRARY_PATH\fP on |
| UNIX. This should not be a cache entry. |
| .TP |
| .B \fBXxx_VERSION\fP |
| The full version string of the package found, if any. Note that many |
| existing modules provide \fBXxx_VERSION_STRING\fP instead. |
| .TP |
| .B \fBXxx_VERSION_MAJOR\fP |
| The major version of the package found, if any. |
| .TP |
| .B \fBXxx_VERSION_MINOR\fP |
| The minor version of the package found, if any. |
| .TP |
| .B \fBXxx_VERSION_PATCH\fP |
| The patch version of the package found, if any. |
| .UNINDENT |
| .sp |
| The following names should not usually be used in \fBCMakeLists.txt\fP files. |
| They are intended for use by Find modules to specify and cache the locations |
| of specific files or directories. Users are typically able to set and edit |
| these variables to control the behavior of Find modules (like entering the |
| path to a library manually): |
| .INDENT 0.0 |
| .TP |
| .B \fBXxx_LIBRARY\fP |
| The path of the library. Use this form only when the module provides a |
| single library. It is appropriate to use this as the result variable |
| in a \fBfind_library()\fP command. |
| .TP |
| .B \fBXxx_Yy_LIBRARY\fP |
| The path of library \fBYy\fP provided by the module \fBXxx\fP\&. Use this form |
| when the module provides more than one library or where other modules may |
| also provide a library of the same name. It is also appropriate to use |
| this form as the result variable in a \fBfind_library()\fP command. |
| .TP |
| .B \fBXxx_INCLUDE_DIR\fP |
| When the module provides only a single library, this variable can be used |
| to specify where to find headers for using the library (or more accurately, |
| the path that consumers of the library should add to their header search |
| path). It would be appropriate to use this as the result variable in a |
| \fBfind_path()\fP command. |
| .TP |
| .B \fBXxx_Yy_INCLUDE_DIR\fP |
| If the module provides more than one library or where other modules may |
| also provide a library of the same name, this form is recommended for |
| specifying where to find headers for using library \fBYy\fP provided by |
| the module. Again, it would be appropriate to use this as the result |
| variable in a \fBfind_path()\fP command. |
| .UNINDENT |
| .sp |
| 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. \fBXxx_ROOT_DIR\fP). 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 |
| \fB_LIBRARY_<CONFIG>\fP suffix, such as \fBFoo_LIBRARY_RELEASE\fP and |
| \fBFoo_LIBRARY_DEBUG\fP\&. The \fBSelectLibraryConfigurations\fP module |
| can be helpful for such cases. |
| .sp |
| While these are the standard variable names, you should provide |
| 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. |
| .SS A Sample Find Module |
| .sp |
| We will describe how to create a simple find module for a library \fBFoo\fP\&. |
| .sp |
| The top of the module should begin with a license notice, followed by |
| a blank line, and then followed by a Bracket Comment\&. The comment |
| should begin with \fB\&.rst:\fP to indicate that the rest of its content is |
| reStructuredText\-format documentation. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # Distributed under the OSI\-approved BSD 3\-Clause License. See accompanying |
| # file Copyright.txt or https://cmake.org/licensing for details. |
| |
| #[=======================================================================[.rst: |
| FindFoo |
| \-\-\-\-\-\-\- |
| |
| Finds the Foo library. |
| |
| Imported Targets |
| ^^^^^^^^^^^^^^^^ |
| |
| This module provides the following imported targets, if found: |
| |
| \(ga\(gaFoo::Foo\(ga\(ga |
| The Foo library |
| |
| Result Variables |
| ^^^^^^^^^^^^^^^^ |
| |
| This will define the following variables: |
| |
| \(ga\(gaFoo_FOUND\(ga\(ga |
| True if the system has the Foo library. |
| \(ga\(gaFoo_VERSION\(ga\(ga |
| The version of the Foo library which was found. |
| \(ga\(gaFoo_INCLUDE_DIRS\(ga\(ga |
| Include directories needed to use Foo. |
| \(ga\(gaFoo_LIBRARIES\(ga\(ga |
| Libraries needed to link to Foo. |
| |
| Cache Variables |
| ^^^^^^^^^^^^^^^ |
| |
| The following cache variables may also be set: |
| |
| \(ga\(gaFoo_INCLUDE_DIR\(ga\(ga |
| The directory containing \(ga\(gafoo.h\(ga\(ga. |
| \(ga\(gaFoo_LIBRARY\(ga\(ga |
| The path to the Foo library. |
| |
| #]=======================================================================] |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The module documentation consists of: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| An underlined heading specifying the module name. |
| .IP \(bu 2 |
| A simple description of what the module finds. |
| More description may be required for some packages. If there are |
| caveats or other details users of the module should be aware of, |
| specify them here. |
| .IP \(bu 2 |
| A section listing imported targets provided by the module, if any. |
| .IP \(bu 2 |
| A section listing result variables provided by the module. |
| .IP \(bu 2 |
| Optionally a section listing cache variables used by the module, if any. |
| .UNINDENT |
| .sp |
| If the package provides any macros or functions, they should be listed in |
| an additional section, but can be documented by additional \fB\&.rst:\fP |
| comment blocks immediately above where those macros or functions are defined. |
| .sp |
| The find module implementation may begin below the documentation block. |
| Now the actual libraries and so on have to be found. The code here will |
| obviously vary from module to module (dealing with that, after all, is the |
| point of find modules), but there tends to be a common pattern for libraries. |
| .sp |
| First, we try to use \fBpkg\-config\fP to find the library. Note that we |
| cannot rely on this, as it may not be available, but it provides a good |
| starting point. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(PkgConfig) |
| pkg_check_modules(PC_Foo QUIET Foo) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This should define some variables starting \fBPC_Foo_\fP that contain the |
| information from the \fBFoo.pc\fP file. |
| .sp |
| Now we need to find the libraries and include files; we use the |
| information from \fBpkg\-config\fP to provide hints to CMake about where to |
| look. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_path(Foo_INCLUDE_DIR |
| NAMES foo.h |
| PATHS ${PC_Foo_INCLUDE_DIRS} |
| PATH_SUFFIXES Foo |
| ) |
| find_library(Foo_LIBRARY |
| NAMES foo |
| PATHS ${PC_Foo_LIBRARY_DIRS} |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Alternatively, if the library is available with multiple configurations, you can |
| use \fBSelectLibraryConfigurations\fP to automatically set the |
| \fBFoo_LIBRARY\fP variable instead: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_library(Foo_LIBRARY_RELEASE |
| NAMES foo |
| PATHS ${PC_Foo_LIBRARY_DIRS}/Release |
| ) |
| find_library(Foo_LIBRARY_DEBUG |
| NAMES foo |
| PATHS ${PC_Foo_LIBRARY_DIRS}/Debug |
| ) |
| |
| include(SelectLibraryConfigurations) |
| select_library_configurations(Foo) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If you have a good way of getting the version (from a header file, for |
| example), you can use that information to set \fBFoo_VERSION\fP (although |
| note that find modules have traditionally used \fBFoo_VERSION_STRING\fP, |
| so you may want to set both). Otherwise, attempt to use the information |
| from \fBpkg\-config\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(Foo_VERSION ${PC_Foo_VERSION}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Now we can use \fBFindPackageHandleStandardArgs\fP to do most of the |
| rest of the work for us |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(FindPackageHandleStandardArgs) |
| find_package_handle_standard_args(Foo |
| FOUND_VAR Foo_FOUND |
| REQUIRED_VARS |
| Foo_LIBRARY |
| Foo_INCLUDE_DIR |
| VERSION_VAR Foo_VERSION |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This will check that the \fBREQUIRED_VARS\fP contain values (that do not |
| end in \fB\-NOTFOUND\fP) and set \fBFoo_FOUND\fP appropriately. It will also |
| cache those values. If \fBFoo_VERSION\fP is set, and a required version |
| was passed to \fBfind_package()\fP, it will check the requested version |
| against the one in \fBFoo_VERSION\fP\&. It will also print messages as |
| appropriate; note that if the package was found, it will print the |
| contents of the first required variable to indicate where it was found. |
| .sp |
| At this point, we have to provide a way for users of the find module to |
| link to the library or libraries that were found. There are two |
| approaches, as discussed in the \fI\%Find Modules\fP section above. The |
| traditional variable approach looks like |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(Foo_FOUND) |
| set(Foo_LIBRARIES ${Foo_LIBRARY}) |
| set(Foo_INCLUDE_DIRS ${Foo_INCLUDE_DIR}) |
| set(Foo_DEFINITIONS ${PC_Foo_CFLAGS_OTHER}) |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If more than one library was found, all of them should be included in |
| these variables (see the \fI\%Standard Variable Names\fP section for more |
| information). |
| .sp |
| When providing imported targets, these should be namespaced (hence the |
| \fBFoo::\fP prefix); CMake will recognize that values passed to |
| \fBtarget_link_libraries()\fP that contain \fB::\fP in their name are |
| supposed to be imported targets (rather than just library names), and |
| will produce appropriate diagnostic messages if that target does not |
| exist (see policy \fBCMP0028\fP). |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(Foo_FOUND AND NOT TARGET Foo::Foo) |
| add_library(Foo::Foo UNKNOWN IMPORTED) |
| set_target_properties(Foo::Foo PROPERTIES |
| IMPORTED_LOCATION "${Foo_LIBRARY}" |
| INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}" |
| INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}" |
| ) |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| One thing to note about this is that the \fBINTERFACE_INCLUDE_DIRECTORIES\fP and |
| similar properties should only contain information about the target itself, and |
| not any of its dependencies. Instead, those dependencies should also be |
| targets, and CMake should be told that they are dependencies of this target. |
| CMake will then combine all the necessary information automatically. |
| .sp |
| The type of the \fBIMPORTED\fP target created in the |
| \fBadd_library()\fP command can always be specified as \fBUNKNOWN\fP |
| type. This simplifies the code in cases where static or shared variants may |
| be found, and CMake will determine the type by inspecting the files. |
| .sp |
| If the library is available with multiple configurations, the |
| \fBIMPORTED_CONFIGURATIONS\fP target property should also be |
| populated: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(Foo_FOUND) |
| if (NOT TARGET Foo::Foo) |
| add_library(Foo::Foo UNKNOWN IMPORTED) |
| endif() |
| if (Foo_LIBRARY_RELEASE) |
| set_property(TARGET Foo::Foo APPEND PROPERTY |
| IMPORTED_CONFIGURATIONS RELEASE |
| ) |
| set_target_properties(Foo::Foo PROPERTIES |
| IMPORTED_LOCATION_RELEASE "${Foo_LIBRARY_RELEASE}" |
| ) |
| endif() |
| if (Foo_LIBRARY_DEBUG) |
| set_property(TARGET Foo::Foo APPEND PROPERTY |
| IMPORTED_CONFIGURATIONS DEBUG |
| ) |
| set_target_properties(Foo::Foo PROPERTIES |
| IMPORTED_LOCATION_DEBUG "${Foo_LIBRARY_DEBUG}" |
| ) |
| endif() |
| set_target_properties(Foo::Foo PROPERTIES |
| INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}" |
| INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}" |
| ) |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBRELEASE\fP variant should be listed first in the property |
| so that the variant is chosen if the user uses a configuration which is |
| not an exact match for any listed \fBIMPORTED_CONFIGURATIONS\fP\&. |
| .sp |
| Most of the cache variables should be hidden in the \fBccmake\fP interface unless |
| the user explicitly asks to edit them. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| mark_as_advanced( |
| Foo_INCLUDE_DIR |
| Foo_LIBRARY |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If this module replaces an older version, you should set compatibility variables |
| to cause the least disruption possible. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # compatibility variables |
| set(Foo_VERSION_STRING ${Foo_VERSION}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SH COPYRIGHT |
| 2000-2022 Kitware, Inc. and Contributors |
| .\" Generated by docutils manpage writer. |
| . |