1CMAKE-DEVELOPER(7) CMake CMAKE-DEVELOPER(7)
2
6 cmake-developer - CMake Developer Reference
7
9 This manual is intended for reference by developers modifying the CMake
10 source tree itself, and by those authoring externally-maintained mod‐
11 ules.
12
14 CMake reports an error if a compiler whose features are known does not
15 report support for a particular requested feature. A compiler is con‐
16 sidered to have known features if it reports support for at least one
17 feature.
18 When adding a new compile feature to CMake, it is therefore necessary
20 to list support for the feature for all CompilerIds which already have
21 one or more feature supported, if the new feature is available for any
22 version of the compiler.
23 When adding the first supported feature to a particular CompilerId, it
25 is necessary to list support for all features known to cmake (See
26 CMAKE_C_COMPILE_FEATURES and CMAKE_CXX_COMPILE_FEATURES as appropri‐
27 ate), where available for the compiler. Ensure that the
28 CMAKE_<LANG>_STANDARD_DEFAULT is set to the computed internal variable
29 CMAKE_<LANG>_STANDARD_COMPUTED_DEFAULT for compiler versions which
30 should be supported.
31 It is sensible to record the features for the most recent version of a
33 particular CompilerId first, and then work backwards. It is sensible
34 to try to create a continuous range of versions of feature releases of
35 the compiler. Gaps in the range indicate incorrect features recorded
36 for intermediate releases.
37 Generally, features are made available for a particular version if the
39 compiler vendor documents availability of the feature with that ver‐
40 sion. Note that sometimes partially implemented features appear to be
41 functional in previous releases (such as cxx_constexpr in GNU 4.6,
42 though availability is documented in GNU 4.7), and sometimes compiler
43 vendors document availability of features, though supporting infra‐
44 structure is not available (such as __has_feature(cxx_generic_lambdas)
45 indicating non-availability in Clang 3.4, though it is documented as
46 available, and fixed in Clang 3.5). Similar cases for other compilers
47 and versions need to be investigated when extending CMake to support
48 them.
49 When a vendor releases a new version of a known compiler which supports
51 a previously unsupported feature, and there are already known features
52 for that compiler, the feature should be listed as supported in CMake
53 for that version of the compiler as soon as reasonably possible.
54 Standard-specific/compiler-specific variables such CMAKE_CXX98_COM‐
56 PILE_FEATURES are deliberately not documented. They only exist for the
57 compiler-specific implementation of adding the -std compile flag for
58 compilers which need that.
59
61 The Help directory contains CMake help manual source files. They are
62 written using the reStructuredText markup syntax and processed by
63 Sphinx to generate the CMake help manuals.
64 Markup Constructs
66 In addition to using Sphinx to generate the CMake help manuals, we also
67 use a C++-implemented document processor to print documents for the
68 --help-* command-line help options. It supports a subset of reStruc‐
69 turedText markup. When authoring or modifying documents, please verify
70 that the command-line help looks good in addition to the Sphinx-gener‐
71 ated html and man pages.
72 The command-line help processor supports the following constructs
74 defined by reStructuredText, Sphinx, and a CMake extension to Sphinx.
75 CMake Domain directives
77 Directives defined in the CMake Domain for defining CMake docu‐
78 mentation objects are printed in command-line help output as if
79 the lines were normal paragraph text with interpretation.
80 CMake Domain interpreted text roles
82 Interpreted text roles defined in the CMake Domain for
83 cross-referencing CMake documentation objects are replaced by
84 their link text in command-line help output. Other roles are
85 printed literally and not processed.
86 code-block directive
88 Add a literal code block without interpretation. The com‐
89 mand-line help processor prints the block content without the
90 leading directive line and with common indentation replaced by
91 one space.
92 include directive
94 Include another document source file. The command-line help
95 processor prints the included document inline with the referenc‐
96 ing document.
97 literal block after ::
99 A paragraph ending in :: followed by a blank line treats the
100 following indented block as literal text without interpretation.
101 The command-line help processor prints the :: literally and
102 prints the block content with common indentation replaced by one
103 space.
104 note directive
106 Call out a side note. The command-line help processor prints
107 the block content as if the lines were normal paragraph text
108 with interpretation.
109 parsed-literal directive
111 Add a literal block with markup interpretation. The com‐
112 mand-line help processor prints the block content without the
113 leading directive line and with common indentation replaced by
114 one space.
115 productionlist directive
117 Render context-free grammar productions. The command-line help
118 processor prints the block content as if the lines were normal
119 paragraph text with interpretation.
120 replace directive
122 Define a |substitution| replacement. The command-line help pro‐
123 cessor requires a substitution replacement to be defined before
124 it is referenced.
125 |substitution| reference
127 Reference a substitution replacement previously defined by the
128 replace directive. The command-line help processor performs the
129 substitution and replaces all newlines in the replacement text
130 with spaces.
131 toctree directive
133 Include other document sources in the Table-of-Contents document
134 tree. The command-line help processor prints the referenced
135 documents inline as part of the referencing document.
136 Inline markup constructs not listed above are printed literally in the
138 command-line help output. We prefer to use inline markup constructs
139 that look correct in source form, so avoid use of -escapes in favor of
140 inline literals when possible.
141 Explicit markup blocks not matching directives listed above are removed
143 from command-line help output. Do not use them, except for plain ..
144 comments that are removed by Sphinx too.
145 Note that nested indentation of blocks is not recognized by the com‐
147 mand-line help processor. Therefore:
148 · Explicit markup blocks are recognized only when not indented inside
150 other blocks.
151 · Literal blocks after paragraphs ending in :: but not at the top
153 indentation level may consume all indented lines following them.
154 Try to avoid these cases in practice.
156 CMake Domain
158 CMake adds a Sphinx Domain called cmake, also called the “CMake
159 Domain”. It defines several “object” types for CMake documentation:
160 command
162 A CMake language command.
163 generator
165 A CMake native build system generator. See the cmake(1) com‐
166 mand-line tool’s -G option.
167 manual A CMake manual page, like this cmake-developer(7) manual.
169 module A CMake module. See the cmake-modules(7) manual and the
171 include() command.
172 policy A CMake policy. See the cmake-policies(7) manual and the
174 cmake_policy() command.
175 prop_cache, prop_dir, prop_gbl, prop_sf, prop_inst, prop_test, prop_tgt
177 A CMake cache, directory, global, source file, installed file,
178 test, or target property, respectively. See the cmake-proper‐
179 ties(7) manual and the set_property() command.
180 variable
182 A CMake language variable. See the cmake-variables(7) manual
183 and the set() command.
184 Documentation objects in the CMake Domain come from two sources.
186 First, the CMake extension to Sphinx transforms every document named
187 with the form Help/<type>/<file-name>.rst to a domain object with type
188 <type>. The object name is extracted from the document title, which is
189 expected to be of the form:
190 <object-name>
192 -------------
193 and to appear at or near the top of the .rst file before any other
195 lines starting in a letter, digit, or <. If no such title appears lit‐
196 erally in the .rst file, the object name is the <file-name>. If a
197 title does appear, it is expected that <file-name> is equal to
198 <object-name> with any < and > characters removed.
199 Second, the CMake Domain provides directives to define objects inside
201 other documents:
202 .. command:: <command-name>
204 This indented block documents <command-name>.
206 .. variable:: <variable-name>
208 This indented block documents <variable-name>.
210 Object types for which no directive is available must be defined using
212 the first approach above.
213 Cross-References
215 Sphinx uses reStructuredText interpreted text roles to provide
216 cross-reference syntax. The CMake Domain provides for each domain
217 object type a role of the same name to cross-reference it. CMake
218 Domain roles are inline markup of the forms:
219 :type:`name`
221 :type:`text <name>`
222 where type is the domain object type and name is the domain object
224 name. In the first form the link text will be name (or name() if the
225 type is command) and in the second form the link text will be the
226 explicit text. For example, the code:
227 * The :command:`list` command.
229 * The :command:`list(APPEND)` sub-command.
230 * The :command:`list() command <list>`.
231 * The :command:`list(APPEND) sub-command <list>`.
232 * The :variable:`CMAKE_VERSION` variable.
233 * The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property.
234 produces:
236 · The list() command.
238 · The list(APPEND) sub-command.
240 · The list() command.
242 · The list(APPEND) sub-command.
244 · The CMAKE_VERSION variable.
246 · The OUTPUT_NAME_<CONFIG> target property.
248 Note that CMake Domain roles differ from Sphinx and reStructuredText
250 convention in that the form a<b>, without a space preceding <, is
251 interpreted as a name instead of link text with an explicit target.
252 This is necessary because we use <placeholders> frequently in object
253 names like OUTPUT_NAME_<CONFIG>. The form a <b>, with a space preced‐
254 ing <, is still interpreted as a link text with an explicit target.
255 Style
257 Style: Section Headers
258 When marking section titles, make the section decoration line as long
259 as the title text. Use only a line below the title, not above. For
260 example:
261 Title Text
263 ----------
264 Capitalize the first letter of each non-minor word in the title.
266 The section header underline character hierarchy is
268 · #: Manual group (part) in the master document
270 · *: Manual (chapter) title
272 · =: Section within a manual
274 · -: Subsection or CMake Domain object document title
276 · ^: Subsubsection or CMake Domain object document section
278 · ": Paragraph or CMake Domain object document subsection
280 Style: Whitespace
282 Use two spaces for indentation. Use two spaces between sentences in
283 prose.
284 Style: Line Length
286 Prefer to restrict the width of lines to 75-80 columns. This is not a
287 hard restriction, but writing new paragraphs wrapped at 75 columns
288 allows space for adding minor content without significant re-wrapping
289 of content.
290 Style: Prose
292 Use American English spellings in prose.
293 Style: Starting Literal Blocks
295 Prefer to mark the start of literal blocks with :: at the end of the
296 preceding paragraph. In cases where the following block gets a
297 code-block marker, put a single : at the end of the preceding para‐
298 graph.
299 Style: CMake Command Signatures
301 Command signatures should be marked up as plain literal blocks, not as
302 cmake code-blocks.
303 Signatures are separated from preceding content by a section header.
305 That is, use:
306 ... preceding paragraph.
308 Normal Libraries
310 ^^^^^^^^^^^^^^^^
311 ::
313 add_library(<lib> ...)
315 This signature is used for ...
317 Signatures of commands should wrap optional parts with square brackets,
319 and should mark list of optional arguments with an ellipsis (...).
320 Elements of the signature which are specified by the user should be
321 specified with angle brackets, and may be referred to in prose using
322 inline-literal syntax.
323 Style: Boolean Constants
325 Use “OFF” and “ON” for boolean values which can be modified by the
326 user, such as POSITION_INDEPENDENT_CODE. Such properties may be
327 “enabled” and “disabled”. Use “True” and “False” for inherent values
328 which can’t be modified after being set, such as the IMPORTED property
329 of a build target.
330 Style: Inline Literals
332 Mark up references to keywords in signatures, file names, and other
333 technical terms with inline-literal syntax, for example:
334 If ``WIN32`` is used with :command:`add_executable`, the
336 :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
337 creates the file ``<name>.exe`` on Windows.
338 Style: Cross-References
340 Mark up linkable references as links, including repeats. An alterna‐
341 tive, which is used by wikipedia (‐
342 http://en.wikipedia.org/wiki/WP:REPEATLINK), is to link to a reference
343 only once per article. That style is not used in CMake documentation.
344 Style: Referencing CMake Concepts
346 If referring to a concept which corresponds to a property, and that
347 concept is described in a high-level manual, prefer to link to the man‐
348 ual section instead of the property. For example:
349 This command creates an :ref:`Imported Target <Imported Targets>`.
351 instead of:
353 This command creates an :prop_tgt:`IMPORTED` target.
355 The latter should be used only when referring specifically to the prop‐
357 erty.
358 References to manual sections are not automatically created by creating
360 a section, but code such as:
361 .. _`Imported Targets`:
363 creates a suitable anchor. Use an anchor name which matches the name
365 of the corresponding section. Refer to the anchor using a cross-refer‐
366 ence with specified text.
367 Imported Targets need the IMPORTED term marked up with care in particu‐
369 lar because the term may refer to a command keyword (IMPORTED), a tar‐
370 get property (IMPORTED), or a concept (Imported Targets).
371 Where a property, command or variable is related conceptually to oth‐
373 ers, by for example, being related to the buildsystem description, gen‐
374 erator expressions or Qt, each relevant property, command or variable
375 should link to the primary manual, which provides high-level informa‐
376 tion. Only particular information relating to the command should be in
377 the documentation of the command.
378 Style: Referencing CMake Domain Objects
380 When referring to CMake Domain objects such as properties, variables,
381 commands etc, prefer to link to the target object and follow that with
382 the type of object it is. For example:
383 Set the :prop_tgt:`AUTOMOC` target property to ``ON``.
385 Instead of
387 Set the target property :prop_tgt:`AUTOMOC` to ``ON``.
389 The policy directive is an exception, and the type us usually referred
391 to before the link:
392 If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
394 However, markup self-references with inline-literal syntax. For exam‐
396 ple, within the add_executable() command documentation, use
397 ``add_executable``
399 not
401 :command:`add_executable`
403 which is used elsewhere.
405
407 The Modules directory contains CMake-language .cmake module files.
408 Module Documentation
410 To document CMake module Modules/<module-name>.cmake, modify Help/man‐
411 ual/cmake-modules.7.rst to reference the module in the toctree direc‐
412 tive, in sorted order, as:
413 /module/<module-name>
415 Then add the module document file Help/module/<module-name>.rst con‐
417 taining just the line:
418 .. cmake-module:: ../../Modules/<module-name>.cmake
420 The cmake-module directive will scan the module file to extract
422 reStructuredText markup from comment blocks that start in .rst:. At
423 the top of Modules/<module-name>.cmake, begin with the following
424 license notice:
425 # Distributed under the OSI-approved BSD 3-Clause License. See accompanying
427 # file Copyright.txt or https://cmake.org/licensing for details.
428 After this notice, add a BLANK line. Then, add documentation using a
430 Line Comment block of the form:
431 #.rst:
433 # <module-name>
434 # -------------
435 #
436 # <reStructuredText documentation of module>
437 or a Bracket Comment of the form:
439 #[[.rst:
441 <module-name>
442 -------------
443 <reStructuredText documentation of module>
445 #]]
446 Any number of = may be used in the opening and closing brackets as long
448 as they match. Content on the line containing the closing bracket is
449 excluded if and only if the line starts in #.
450 Additional such .rst: comments may appear anywhere in the module file.
452 All such comments must start with # in the first column.
453 For example, a Modules/Findxxx.cmake module may contain:
455 # Distributed under the OSI-approved BSD 3-Clause License. See accompanying
457 # file Copyright.txt or https://cmake.org/licensing for details.
458 #.rst:
460 # FindXxx
461 # -------
462 #
463 # This is a cool module.
464 # This module does really cool stuff.
465 # It can do even more than you think.
466 #
467 # It even needs two paragraphs to tell you about it.
468 # And it defines the following variables:
469 #
470 # * VAR_COOL: this is great isn't it?
471 # * VAR_REALLY_COOL: cool right?
472 <code>
474 #[========================================[.rst:
476 .. command:: xxx_do_something
477 This command does something for Xxx::
479 xxx_do_something(some arguments)
481 #]========================================]
482 macro(xxx_do_something)
483 <code>
484 endmacro()
485 Test the documentation formatting by running cmake --help-module <mod‐
487 ule-name>, and also by enabling the SPHINX_HTML and SPHINX_MAN options
488 to build the documentation. Edit the comments until generated documen‐
489 tation looks satisfactory. To have a .cmake file in this directory NOT
490 show up in the modules documentation, simply leave out the Help/mod‐
491 ule/<module-name>.rst file and the Help/manual/cmake-modules.7.rst toc‐
492 tree entry.
493 Find Modules
495 A “find module” is a Modules/Find<package>.cmake file to be loaded by
496 the find_package() command when invoked for <package>.
497 The primary task of a find module is to determine whether a package
499 exists on the system, set the <package>_FOUND variable to reflect this
500 and provide any variables, macros and imported targets required to use
501 the package. A find module is useful in cases where an upstream
502 library does not provide a config file package.
503 The traditional approach is to use variables for everything, including
505 libraries and executables: see the Standard Variable Names section
506 below. This is what most of the existing find modules provided by
507 CMake do.
508 The more modern approach is to behave as much like config file packages
510 files as possible, by providing imported target. This has the advan‐
511 tage of propagating Target Usage Requirements to consumers.
512 In either case (or even when providing both variables and imported tar‐
514 gets), find modules should provide backwards compatibility with old
515 versions that had the same name.
516 A FindFoo.cmake module will typically be loaded by the command:
518 find_package(Foo [major[.minor[.patch[.tweak]]]]
520 [EXACT] [QUIET] [REQUIRED]
521 [[COMPONENTS] [components...]]
522 [OPTIONAL_COMPONENTS components...]
523 [NO_POLICY_SCOPE])
524 See the find_package() documentation for details on what variables are
526 set for the find module. Most of these are dealt with by using Find‐
527 PackageHandleStandardArgs.
528 Briefly, the module should only locate versions of the package compati‐
530 ble with the requested version, as described by the Foo_FIND_VERSION
531 family of variables. If Foo_FIND_QUIETLY is set to true, it should
532 avoid printing messages, including anything complaining about the pack‐
533 age not being found. If Foo_FIND_REQUIRED is set to true, the module
534 should issue a FATAL_ERROR if the package cannot be found. If neither
535 are set to true, it should print a non-fatal message if it cannot find
536 the package.
537 Packages that find multiple semi-independent parts (like bundles of
539 libraries) should search for the components listed in Foo_FIND_COMPO‐
540 NENTS if it is set , and only set Foo_FOUND to true if for each
541 searched-for component <c> that was not found, Foo_FIND_REQUIRED_<c> is
542 not set to true. The HANDLE_COMPONENTS argument of find_package_han‐
543 dle_standard_args() can be used to implement this.
544 If Foo_FIND_COMPONENTS is not set, which modules are searched for and
546 required is up to the find module, but should be documented.
547 For internal implementation, it is a generally accepted convention that
549 variables starting with underscore are for temporary use only.
550 Like all modules, find modules should be properly documented. To add a
552 module to the CMake documentation, follow the steps in the Module Docu‐
553 mentation section above.
554 Standard Variable Names
556 For a FindXxx.cmake module that takes the approach of setting variables
557 (either instead of or in addition to creating imported targets), the
558 following variable names should be used to keep things consistent
559 between find modules. Note that all variables start with Xxx_ to make
560 sure they do not interfere with other find modules; the same considera‐
561 tion applies to macros, functions and imported targets.
562 Xxx_INCLUDE_DIRS
564 The final set of include directories listed in one variable for
565 use by client code. This should not be a cache entry.
566 Xxx_LIBRARIES
568 The libraries to link against to use Xxx. These should include
569 full paths. This should not be a cache entry.
570 Xxx_DEFINITIONS
572 Definitions to use when compiling code that uses Xxx. This
573 really shouldn’t include options such as -DHAS_JPEG that a
574 client source-code file uses to decide whether to #include
575 <jpeg.h>
576 Xxx_EXECUTABLE
578 Where to find the Xxx tool.
579 Xxx_Yyy_EXECUTABLE
581 Where to find the Yyy tool that comes with Xxx.
582 Xxx_LIBRARY_DIRS
584 Optionally, the final set of library directories listed in one
585 variable for use by client code. This should not be a cache
586 entry.
587 Xxx_ROOT_DIR
589 Where to find the base directory of Xxx.
590 Xxx_VERSION_Yy
592 Expect Version Yy if true. Make sure at most one of these is
593 ever true.
594 Xxx_WRAP_Yy
596 If False, do not try to use the relevant CMake wrapping command.
597 Xxx_Yy_FOUND
599 If False, optional Yy part of Xxx system is not available.
600 Xxx_FOUND
602 Set to false, or undefined, if we haven’t found, or don’t want
603 to use Xxx.
604 Xxx_NOT_FOUND_MESSAGE
606 Should be set by config-files in the case that it has set
607 Xxx_FOUND to FALSE. The contained message will be printed by
608 the find_package() command and by find_package_handle_stan‐
609 dard_args() to inform the user about the problem.
610 Xxx_RUNTIME_LIBRARY_DIRS
612 Optionally, the runtime library search path for use when running
613 an executable linked to shared libraries. The list should be
614 used by user code to create the PATH on windows or
615 LD_LIBRARY_PATH on UNIX. This should not be a cache entry.
616 Xxx_VERSION
618 The full version string of the package found, if any. Note that
619 many existing modules provide Xxx_VERSION_STRING instead.
620 Xxx_VERSION_MAJOR
622 The major version of the package found, if any.
623 Xxx_VERSION_MINOR
625 The minor version of the package found, if any.
626 Xxx_VERSION_PATCH
628 The patch version of the package found, if any.
629 The following names should not usually be used in CMakeLists.txt files,
631 but are typically cache variables for users to edit and control the be‐
632 haviour of find modules (like entering the path to a library manually)
633 Xxx_LIBRARY
635 The path of the Xxx library (as used with find_library(), for
636 example).
637 Xxx_Yy_LIBRARY
639 The path of the Yy library that is part of the Xxx system. It
640 may or may not be required to use Xxx.
641 Xxx_INCLUDE_DIR
643 Where to find headers for using the Xxx library.
644 Xxx_Yy_INCLUDE_DIR
646 Where to find headers for using the Yy library of the Xxx sys‐
647 tem.
648 To prevent users being overwhelmed with settings to configure, try to
650 keep as many options as possible out of the cache, leaving at least one
651 option which can be used to disable use of the module, or locate a
652 not-found library (e.g. Xxx_ROOT_DIR). For the same reason, mark most
653 cache options as advanced. For packages which provide both debug and
654 release binaries, it is common to create cache variables with a
655 _LIBRARY_<CONFIG> suffix, such as Foo_LIBRARY_RELEASE and
656 Foo_LIBRARY_DEBUG.
657 While these are the standard variable names, you should provide back‐
659 wards compatibility for any old names that were actually in use. Make
660 sure you comment them as deprecated, so that no-one starts using them.
661 A Sample Find Module
663 We will describe how to create a simple find module for a library Foo.
664 The first thing that is needed is a license notice.
666 # Distributed under the OSI-approved BSD 3-Clause License. See accompanying
668 # file Copyright.txt or https://cmake.org/licensing for details.
669 Next we need module documentation. CMake’s documentation system
671 requires you to follow the license notice with a blank line and then
672 with a documentation marker and the name of the module. You should
673 follow this with a simple statement of what the module does.
674 #.rst:
676 # FindFoo
677 # -------
678 #
679 # Finds the Foo library
680 #
681 More description may be required for some packages. If there are
683 caveats or other details users of the module should be aware of, you
684 can add further paragraphs below this. Then you need to document what
685 variables and imported targets are set by the module, such as
686 # This will define the following variables::
688 #
689 # Foo_FOUND - True if the system has the Foo library
690 # Foo_VERSION - The version of the Foo library which was found
691 #
692 # and the following imported targets::
693 #
694 # Foo::Foo - The Foo library
695 If the package provides any macros, they should be listed here, but can
697 be documented where they are defined. See the Module Documentation
698 section above for more details.
699 Now the actual libraries and so on have to be found. The code here
701 will obviously vary from module to module (dealing with that, after
702 all, is the point of find modules), but there tends to be a common pat‐
703 tern for libraries.
704 First, we try to use pkg-config to find the library. Note that we can‐
706 not rely on this, as it may not be available, but it provides a good
707 starting point.
708 find_package(PkgConfig)
710 pkg_check_modules(PC_Foo QUIET Foo)
711 This should define some variables starting PC_Foo_ that contain the
713 information from the Foo.pc file.
714 Now we need to find the libraries and include files; we use the infor‐
716 mation from pkg-config to provide hints to CMake about where to look.
717 find_path(Foo_INCLUDE_DIR
719 NAMES foo.h
720 PATHS ${PC_Foo_INCLUDE_DIRS}
721 PATH_SUFFIXES Foo
722 )
723 find_library(Foo_LIBRARY
724 NAMES foo
725 PATHS ${PC_Foo_LIBRARY_DIRS}
726 )
727 If you have a good way of getting the version (from a header file, for
729 example), you can use that information to set Foo_VERSION (although
730 note that find modules have traditionally used Foo_VERSION_STRING, so
731 you may want to set both). Otherwise, attempt to use the information
732 from pkg-config
733 set(Foo_VERSION ${PC_Foo_VERSION})
735 Now we can use FindPackageHandleStandardArgs to do most of the rest of
737 the work for us
738 include(FindPackageHandleStandardArgs)
740 find_package_handle_standard_args(Foo
741 FOUND_VAR Foo_FOUND
742 REQUIRED_VARS
743 Foo_LIBRARY
744 Foo_INCLUDE_DIR
745 VERSION_VAR Foo_VERSION
746 )
747 This will check that the REQUIRED_VARS contain values (that do not end
749 in -NOTFOUND) and set Foo_FOUND appropriately. It will also cache
750 those values. If Foo_VERSION is set, and a required version was passed
751 to find_package(), it will check the requested version against the one
752 in Foo_VERSION. It will also print messages as appropriate; note that
753 if the package was found, it will print the contents of the first
754 required variable to indicate where it was found.
755 At this point, we have to provide a way for users of the find module to
757 link to the library or libraries that were found. There are two
758 approaches, as discussed in the Find Modules section above. The tradi‐
759 tional variable approach looks like
760 if(Foo_FOUND)
762 set(Foo_LIBRARIES ${Foo_LIBRARY})
763 set(Foo_INCLUDE_DIRS ${Foo_INCLUDE_DIR})
764 set(Foo_DEFINITIONS ${PC_Foo_CFLAGS_OTHER})
765 endif()
766 If more than one library was found, all of them should be included in
768 these variables (see the Standard Variable Names section for more
769 information).
770 When providing imported targets, these should be namespaced (hence the
772 Foo:: prefix); CMake will recognize that values passed to tar‐
773 get_link_libraries() that contain :: in their name are supposed to be
774 imported targets (rather than just library names), and will produce
775 appropriate diagnostic messages if that target does not exist (see pol‐
776 icy CMP0028).
777 if(Foo_FOUND AND NOT TARGET Foo::Foo)
779 add_library(Foo::Foo UNKNOWN IMPORTED)
780 set_target_properties(Foo::Foo PROPERTIES
781 IMPORTED_LOCATION "${Foo_LIBRARY}"
782 INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}"
783 INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"
784 )
785 endif()
786 One thing to note about this is that the INTERFACE_INCLUDE_DIRECTORIES
788 and similar properties should only contain information about the target
789 itself, and not any of its dependencies. Instead, those dependencies
790 should also be targets, and CMake should be told that they are depen‐
791 dencies of this target. CMake will then combine all the necessary
792 information automatically.
793 The type of the IMPORTED target created in the add_library() command
795 can always be specified as UNKNOWN type. This simplifies the code in
796 cases where static or shared variants may be found, and CMake will
797 determine the type by inspecting the files.
798 If the library is available with multiple configurations, the
800 IMPORTED_CONFIGURATIONS target property should also be populated:
801 if(Foo_FOUND)
803 if (NOT TARGET Foo::Foo)
804 add_library(Foo::Foo UNKNOWN IMPORTED)
805 endif()
806 if (Foo_LIBRARY_RELEASE)
807 set_property(TARGET Foo::Foo APPEND PROPERTY
808 IMPORTED_CONFIGURATIONS RELEASE
809 )
810 set_target_properties(Foo::Foo PROPERTIES
811 IMPORTED_LOCATION_RELEASE "${Foo_LIBRARY_RELEASE}"
812 )
813 endif()
814 if (Foo_LIBRARY_DEBUG)
815 set_property(TARGET Foo::Foo APPEND PROPERTY
816 IMPORTED_CONFIGURATIONS DEBUG
817 )
818 set_target_properties(Foo::Foo PROPERTIES
819 IMPORTED_LOCATION_DEBUG "${Foo_LIBRARY_DEBUG}"
820 )
821 endif()
822 set_target_properties(Foo::Foo PROPERTIES
823 INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}"
824 INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"
825 )
826 endif()
827 The RELEASE variant should be listed first in the property so that that
829 variant is chosen if the user uses a configuration which is not an
830 exact match for any listed IMPORTED_CONFIGURATIONS.
831 Most of the cache variables should be hidden in the ccmake interface
833 unless the user explicitly asks to edit them.
834 mark_as_advanced(
836 Foo_INCLUDE_DIR
837 Foo_LIBRARY
838 )
839 If this module replaces an older version, you should set compatibility
841 variables to cause the least disruption possible.
842 # compatibility variables
844 set(Foo_VERSION_STRING ${Foo_VERSION})
845
847 2000-2018 Kitware, Inc. and Contributors
8483.11.4 May 13, 2019 CMAKE-DEVELOPER(7)