1CMAKE-DEVELOPER(7)                   CMake                  CMAKE-DEVELOPER(7)


6       cmake-developer - CMake Developer Reference


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.


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.
19       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.
24       When  adding the first supported feature to a particular CompilerId, it
25       is necessary to list support for  all  features  known  to  cmake  (See
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.
32       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.
38       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.
50       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.
55       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.


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.
65   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.
73       The command-line  help  processor  supports  the  following  constructs
74       defined by reStructuredText, Sphinx, and a CMake extension to Sphinx.
76       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.
81       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.
87       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.
93       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.
98       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.
105       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.
110       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.
116       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.
121       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.
126       |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.
132       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.
137       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.
142       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.
146       Note that nested indentation of blocks is not recognized  by  the  com‐
147       mand-line help processor.  Therefore:
149       · Explicit  markup  blocks are recognized only when not indented inside
150         other blocks.
152       · Literal blocks after paragraphs ending in  ::  but  not  at  the  top
153         indentation level may consume all indented lines following them.
155       Try to avoid these cases in practice.
157   CMake Domain
158       CMake  adds  a  Sphinx  Domain  called  cmake,  also  called the “CMake
159       Domain”.  It defines several “object” types for CMake documentation:
161       command
162              A CMake language command.
164       generator
165              A CMake native build system generator.  See  the  cmake(1)  com‐
166              mand-line tool’s -G option.
168       manual A CMake manual page, like this cmake-developer(7) manual.
170       module A  CMake  module.   See  the  cmake-modules(7)  manual  and  the
171              include() command.
173       policy A CMake  policy.   See  the  cmake-policies(7)  manual  and  the
174              cmake_policy() command.
176       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.
181       variable
182              A  CMake  language  variable.  See the cmake-variables(7) manual
183              and the set() command.
185       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:
191          <object-name>
192          -------------
194       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.
200       Second, the CMake Domain provides directives to define  objects  inside
201       other documents:
203          .. command:: <command-name>
205           This indented block documents <command-name>.
207          .. variable:: <variable-name>
209           This indented block documents <variable-name>.
211       Object  types for which no directive is available must be defined using
212       the first approach above.
214   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:
220          :type:`name`
221          :type:`text <name>`
223       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:
228          * 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.
235       produces:
237       · The list() command.
239       · The list(APPEND) sub-command.
241       · The list() command.
243       · The list(APPEND) sub-command.
245       · The CMAKE_VERSION variable.
247       · The OUTPUT_NAME_<CONFIG> target property.
249       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.
256   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:
262          Title Text
263          ----------
265       Capitalize the first letter of each non-minor word in the title.
267       The section header underline character hierarchy is
269       · #: Manual group (part) in the master document
271       · *: Manual (chapter) title
273       · =: Section within a manual
275       · -: Subsection or CMake Domain object document title
277       · ^: Subsubsection or CMake Domain object document section
279       · ": Paragraph or CMake Domain object document subsection
281   Style: Whitespace
282       Use  two  spaces  for indentation.  Use two spaces between sentences in
283       prose.
285   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.
291   Style: Prose
292       Use American English spellings in prose.
294   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.
300   Style: CMake Command Signatures
301       Command signatures should be marked up as plain literal blocks, not  as
302       cmake code-blocks.
304       Signatures  are  separated  from preceding content by a section header.
305       That is, use:
307          ... preceding paragraph.
309          Normal Libraries
310          ^^^^^^^^^^^^^^^^
312          ::
314            add_library(<lib> ...)
316          This signature is used for ...
318       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.
324   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.
331   Style: Inline Literals
332       Mark up references to keywords in signatures,  file  names,  and  other
333       technical terms with inline-literal syntax, for example:
335          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.
339   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.
345   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:
350          This command creates an :ref:`Imported Target <Imported Targets>`.
352       instead of:
354          This command creates an :prop_tgt:`IMPORTED` target.
356       The latter should be used only when referring specifically to the prop‐
357       erty.
359       References to manual sections are not automatically created by creating
360       a section, but code such as:
362          .. _`Imported Targets`:
364       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.
368       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).
372       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.
379   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:
384          Set the :prop_tgt:`AUTOMOC` target property to ``ON``.
386       Instead of
388          Set the target property :prop_tgt:`AUTOMOC` to ``ON``.
390       The  policy directive is an exception, and the type us usually referred
391       to before the link:
393          If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
395       However, markup self-references with inline-literal syntax.  For  exam‐
396       ple, within the add_executable() command documentation, use
398          ``add_executable``
400       not
402          :command:`add_executable`
404       which is used elsewhere.


407       The Modules directory contains CMake-language .cmake module files.
409   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:
414          /module/<module-name>
416       Then  add  the  module document file Help/module/<module-name>.rst con‐
417       taining just the line:
419          .. cmake-module:: ../../Modules/<module-name>.cmake
421       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:
426          # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
427          # file Copyright.txt or https://cmake.org/licensing for details.
429       After  this  notice, add a BLANK line.  Then, add documentation using a
430       Line Comment block of the form:
432          #.rst:
433          # <module-name>
434          # -------------
435          #
436          # <reStructuredText documentation of module>
438       or a Bracket Comment of the form:
440          #[[.rst:
441          <module-name>
442          -------------
444          <reStructuredText documentation of module>
445          #]]
447       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 #.
451       Additional such .rst: comments may appear anywhere in the module  file.
452       All such comments must start with # in the first column.
454       For example, a Modules/Findxxx.cmake module may contain:
456          # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
457          # file Copyright.txt or https://cmake.org/licensing for details.
459          #.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?
473          <code>
475          #[========================================[.rst:
476          .. command:: xxx_do_something
478           This command does something for Xxx::
480            xxx_do_something(some arguments)
481          #]========================================]
482          macro(xxx_do_something)
483            <code>
484          endmacro()
486       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.
494   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>.
498       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.
504       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.
509       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.
513       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.
517       A FindFoo.cmake module will typically be loaded by the command:
519          find_package(Foo [major[.minor[.patch[.tweak]]]]
520                       [EXACT] [QUIET] [REQUIRED]
521                       [[COMPONENTS] [components...]]
522                       [OPTIONAL_COMPONENTS components...]
523                       [NO_POLICY_SCOPE])
525       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.
529       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.
538       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.
545       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.
548       For internal implementation, it is a generally accepted convention that
549       variables starting with underscore are for temporary use only.
551       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.
555   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.
563       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.
567       Xxx_LIBRARIES
568              The  libraries  to link against to use Xxx. These should include
569              full paths.  This should not be a cache entry.
571       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>
577       Xxx_EXECUTABLE
578              Where to find the Xxx tool.
580       Xxx_Yyy_EXECUTABLE
581              Where to find the Yyy tool that comes with Xxx.
583       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.
588       Xxx_ROOT_DIR
589              Where to find the base directory of Xxx.
591       Xxx_VERSION_Yy
592              Expect  Version  Yy  if  true. Make sure at most one of these is
593              ever true.
595       Xxx_WRAP_Yy
596              If False, do not try to use the relevant CMake wrapping command.
598       Xxx_Yy_FOUND
599              If False, optional Yy part of Xxx system is not available.
601       Xxx_FOUND
602              Set to false, or undefined, if we haven’t found, or  don’t  want
603              to use Xxx.
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.
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.
617       Xxx_VERSION
618              The full version string of the package found, if any.  Note that
619              many existing modules provide Xxx_VERSION_STRING instead.
621       Xxx_VERSION_MAJOR
622              The major version of the package found, if any.
624       Xxx_VERSION_MINOR
625              The minor version of the package found, if any.
627       Xxx_VERSION_PATCH
628              The patch version of the package found, if any.
630       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)
634       Xxx_LIBRARY
635              The path of the Xxx library (as used  with  find_library(),  for
636              example).
638       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.
642       Xxx_INCLUDE_DIR
643              Where to find headers for using the Xxx library.
645       Xxx_Yy_INCLUDE_DIR
646              Where to find headers for using the Yy library of the  Xxx  sys‐
647              tem.
649       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.
658       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.
662   A Sample Find Module
663       We will describe how to create a simple find module for a library Foo.
665       The first thing that is needed is a license notice.
667          # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
668          # file Copyright.txt or https://cmake.org/licensing for details.
670       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.
675          #.rst:
676          # FindFoo
677          # -------
678          #
679          # Finds the Foo library
680          #
682       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
687          # 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
696       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.
700       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.
705       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.
709          find_package(PkgConfig)
710          pkg_check_modules(PC_Foo QUIET Foo)
712       This  should  define  some  variables starting PC_Foo_ that contain the
713       information from the Foo.pc file.
715       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.
718          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          )
728       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
734          set(Foo_VERSION ${PC_Foo_VERSION})
736       Now  we can use FindPackageHandleStandardArgs to do most of the rest of
737       the work for us
739          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          )
748       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.
756       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
761          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()
767       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).
771       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).
778          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}"
784            )
785          endif()
787       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.
794       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.
799       If  the  library  is  available  with  multiple   configurations,   the
800       IMPORTED_CONFIGURATIONS target property should also be populated:
802          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
809              )
810              set_target_properties(Foo::Foo PROPERTIES
812              )
813            endif()
814            if (Foo_LIBRARY_DEBUG)
815              set_property(TARGET Foo::Foo APPEND PROPERTY
817              )
818              set_target_properties(Foo::Foo PROPERTIES
820              )
821            endif()
822            set_target_properties(Foo::Foo PROPERTIES
825            )
826          endif()
828       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.
832       Most  of  the  cache variables should be hidden in the ccmake interface
833       unless the user explicitly asks to edit them.
835          mark_as_advanced(
836            Foo_INCLUDE_DIR
837            Foo_LIBRARY
838          )
840       If this module replaces an older version, you should set  compatibility
841       variables to cause the least disruption possible.
843          # compatibility variables
844          set(Foo_VERSION_STRING ${Foo_VERSION})
847       2000-2018 Kitware, Inc. and Contributors
8523.11.4                           May 13, 2019               CMAKE-DEVELOPER(7)