Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, July 27, 2022

cmake-developer (7)


cmake-developer - CMake Developer Reference


Please see following description for synopsis


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

       cmake-developer - CMake Developer Reference

       This  manual  is  intended  for  reference  by  developers working with
       cmake-language(7) code, whether writing their  own  modules,  authoring
       their own build systems, or working on CMake itself.

       See  https://cmake.org/get-involved/  to get involved in development of
       CMake upstream.  It includes links to contribution instructions,  which
       in turn link to developer guides for CMake itself.

       A  "find  module" is a Find<PackageName>.cmake file to be loaded by the
       find_package() command when invoked for <PackageName>.

       The primary task of a find module is to determine whether a package  is
       available,  set  the  <PackageName>_FOUND  variable to reflect this and
       provide any variables, macros and imported targets required to use  the
       package.   A  find  module is useful in cases where an upstream library
       does not provide a config file package.

       The traditional approach is to use variables for everything,  including
       libraries  and  executables:  see  the  Standard Variable Names section
       below.  This is what most of the  existing  find  modules  provided  by
       CMake do.

       The more modern approach is to behave as much like config file packages
       files as possible, by providing imported target.  This has  the  advan-
       tage of propagating Target Usage Requirements to consumers.

       In either case (or even when providing both variables and imported tar-
       gets), find modules should provide  backwards  compatibility  with  old
       versions that had the same name.

       A FindFoo.cmake module will typically be loaded by the command:

          find_package(Foo [major[.minor[.patch[.tweak]]]]
                       [EXACT] [QUIET] [REQUIRED]
                       [[COMPONENTS] [components...]]
                       [OPTIONAL_COMPONENTS components...]

       See  the find_package() documentation for details on what variables are
       set for the find module.  Most of these are dealt with by  using  Find-

       Briefly, the module should only locate versions of the package compati-
       ble with the requested version, as described  by  the  Foo_FIND_VERSION
       family  of  variables.   If  Foo_FIND_QUIETLY is set to true, it should
       avoid printing messages, including anything complaining about the pack-
       age  not  being found.  If Foo_FIND_REQUIRED is set to true, the module
       should issue a FATAL_ERROR if the package cannot be found.  If  neither
       are  set to true, it should print a non-fatal message if it cannot find
       the package.

       Packages that find multiple semi-independent  parts  (like  bundles  of
       libraries)  should  search for the components listed in Foo_FIND_COMPO-
       NENTS if it is set , and  only  set  Foo_FOUND  to  true  if  for  each
       searched-for component <c> that was not found, Foo_FIND_REQUIRED_<c> is
       not set to true.  The HANDLE_COMPONENTS argument  of  find_package_han-
       dle_standard_args() can be used to implement this.

       If  Foo_FIND_COMPONENTS  is not set, which modules are searched for and
       required is up to the find module, but should be documented.

       For internal implementation, it is a generally accepted convention that
       variables starting with underscore are for temporary use only.

   Standard Variable Names
       For a FindXxx.cmake module that takes the approach of setting variables
       (either instead of or in addition to creating  imported  targets),  the
       following  variable  names  should  be  used  to keep things consistent
       between Find modules.  Note that all variables start with  Xxx_,  which
       (unless  otherwise  noted)  must  match  exactly  the name of the Find-
       Xxx.cmake 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.

              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 find_path() command -  see  Xxx_INCLUDE_DIR  below
              for that).

              The  libraries  to use with the module.  These may be CMake tar-
              gets, 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
              find_library() command - see Xxx_LIBRARY below for that).

              The compile definitions to use when compiling code that uses the
              module.    This   really   shouldn't  include  options  such  as
              -DHAS_JPEG that a client source-code file uses to decide whether
              to #include <jpeg.h>

              The  full  absolute  path  to  an executable.  In this case, Xxx
              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 find_program() command.

              Similar to Xxx_EXECUTABLE except here the Xxx is always the mod-
              ule  name  and YYY is the tool name (again, usually fully upper-
              case).  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  pro-
              vides more than one executable.

              Optionally,  the  final set of library directories listed in one
              variable for use by client code. This  should  not  be  a  cache

              Where to find the base directory of the module.

              Variables of this form specify whether the Xxx module being pro-
              vided is version VV 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 Barry might have evolved over  many  years
              and  gone through a number of different major versions.  Version
              3 of the Barry module might set the variable Barry_VERSION_3  to
              true,   whereas  an  older  version  of  the  module  might  set
              Barry_VERSION_2 to true instead.  It would be an error for  both
              Barry_VERSION_3 and Barry_VERSION_2 to both be set to true.

              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 YY part of the variable.

              For variables of this form, Yy 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 find_package() command  for  the
              module.   If  a  variable of this form is set to false, it means
              that the Yy component of module Xxx 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.

              When  the  find_package()  command  returns  to the caller, this
              variable will be set to true if the module was  deemed  to  have
              been found successfully.

              Should  be  set  by  config-files  in  the  case that it has set
              Xxx_FOUND to FALSE.  The contained message will  be  printed  by
              the  find_package()  command  and  by  find_package_handle_stan-
              dard_args() to inform the user  about  the  problem.   Use  this
              instead  of  calling  message()  directly to report a reason for
              failing to find the module or package.

              Optionally, the runtime library search path for use when running
              an  executable  linked  to shared libraries.  The list should be
              used  by  user  code  to  create  the   PATH   on   windows   or
              LD_LIBRARY_PATH on UNIX.  This should not be a cache entry.

              The full version string of the package found, if any.  Note that
              many existing modules provide Xxx_VERSION_STRING instead.

              The major version of the package found, if any.

              The minor version of the package found, if any.

              The patch version of the package found, if any.

       The following names should not usually be used in CMakeLists.txt 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):

              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 find_library() command.

              The path of library Yy provided by the  module  Xxx.   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
              find_library() command.

              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  find_path()

              If the module provides more than one library or where other mod-
              ules may also provide a library of the same name, this  form  is
              recommended  for  specifying  where  to  find  headers for using
              library Yy provided by the module.  Again, it would be appropri-
              ate to use this as the result variable in a find_path() command.

       To  prevent  users being overwhelmed with settings to configure, try to
       keep as many options as possible out of the cache, leaving at least one
       option  which  can  be  used  to disable use of the module, or locate a
       not-found library (e.g. Xxx_ROOT_DIR).  For the same reason, mark  most
       cache  options  as advanced.  For packages which provide both debug and
       release binaries, it  is  common  to  create  cache  variables  with  a
       _LIBRARY_<CONFIG>    suffix,    such    as    Foo_LIBRARY_RELEASE   and
       Foo_LIBRARY_DEBUG.  The SelectLibraryConfigurations module can be help-
       ful for such cases.

       While  these  are the standard variable names, you should provide back-
       wards compatibility for any old names that were actually in use.   Make
       sure you comment them as deprecated, so that no-one starts using them.

   A Sample Find Module
       We will describe how to create a simple find module for a library Foo.

       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  .rst: to indicate that the rest of its content is reStruc-
       turedText-format documentation.  For example:

          # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
          # file Copyright.txt or https://cmake.org/licensing for details.


          Finds the Foo library.

          Imported Targets

          This module provides the following imported targets, if found:

            The Foo library

          Result Variables

          This will define the following variables:

            True if the system has the Foo library.
            The version of the Foo library which was found.
            Include directories needed to use Foo.
            Libraries needed to link to Foo.

          Cache Variables

          The following cache variables may also be set:

            The directory containing ``foo.h``.
            The path to the Foo library.


       The module documentation consists of:

       o An underlined heading specifying the module name.

       o 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.

       o A section listing imported targets provided by the module, if any.

       o A section listing result variables provided by the module.

       o Optionally a section listing cache variables used by the  module,  if

       If  the package provides any macros or functions, they should be listed
       in an additional section, but can be  documented  by  additional  .rst:
       comment  blocks  immediately  above where those macros or functions are

       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 pat-
       tern for libraries.

       First, we try to use pkg-config to find the library.  Note that we can-
       not  rely  on  this, as it may not be available, but it provides a good
       starting point.

          pkg_check_modules(PC_Foo QUIET Foo)

       This should define some variables starting  PC_Foo_  that  contain  the
       information from the Foo.pc file.

       Now  we need to find the libraries and include files; we use the infor-
       mation from pkg-config to provide hints to CMake about where to look.

            NAMES foo.h
            PATHS ${PC_Foo_INCLUDE_DIRS}
            PATH_SUFFIXES Foo
            NAMES foo
            PATHS ${PC_Foo_LIBRARY_DIRS}

       Alternatively, if the library is  available  with  multiple  configura-
       tions, you can use SelectLibraryConfigurations to automatically set the
       Foo_LIBRARY variable instead:

            NAMES foo
            PATHS ${PC_Foo_LIBRARY_DIRS}/Release
            NAMES foo
            PATHS ${PC_Foo_LIBRARY_DIRS}/Debug


       If you have a good way of getting the version (from a header file,  for
       example),  you  can  use  that information to set Foo_VERSION (although
       note that find modules have traditionally used  Foo_VERSION_STRING,  so
       you  may  want to set both).  Otherwise, attempt to use the information
       from pkg-config

          set(Foo_VERSION ${PC_Foo_VERSION})

       Now we can use FindPackageHandleStandardArgs to do most of the rest  of
       the work for us

            FOUND_VAR Foo_FOUND

       This  will check that the REQUIRED_VARS contain values (that do not end
       in -NOTFOUND) and set Foo_FOUND  appropriately.   It  will  also  cache
       those values.  If Foo_VERSION is set, and a required version was passed
       to find_package(), it will check the requested version against the  one
       in  Foo_VERSION.  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.

       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 Find Modules section above.  The tradi-
       tional variable approach looks like

            set(Foo_LIBRARIES ${Foo_LIBRARY})
            set(Foo_INCLUDE_DIRS ${Foo_INCLUDE_DIR})
            set(Foo_DEFINITIONS ${PC_Foo_CFLAGS_OTHER})

       If more than one library was found, all of them should be  included  in
       these  variables  (see  the  Standard  Variable  Names section for more

       When providing imported targets, these should be namespaced (hence  the
       Foo::  prefix);  CMake  will  recognize  that  values  passed  to  tar-
       get_link_libraries() that contain :: 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 pol-
       icy CMP0028).

          if(Foo_FOUND AND NOT TARGET Foo::Foo)
            add_library(Foo::Foo UNKNOWN IMPORTED)
            set_target_properties(Foo::Foo PROPERTIES
              IMPORTED_LOCATION "${Foo_LIBRARY}"

       One  thing to note about this is that the INTERFACE_INCLUDE_DIRECTORIES
       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  depen-
       dencies  of  this  target.   CMake  will then combine all the necessary
       information automatically.

       The type of the IMPORTED target created in  the  add_library()  command
       can  always  be specified as UNKNOWN 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.

       If   the   library  is  available  with  multiple  configurations,  the
       IMPORTED_CONFIGURATIONS target property should also be populated:

            if (NOT TARGET Foo::Foo)
              add_library(Foo::Foo UNKNOWN IMPORTED)
            if (Foo_LIBRARY_RELEASE)
              set_property(TARGET Foo::Foo APPEND PROPERTY
              set_target_properties(Foo::Foo PROPERTIES
            if (Foo_LIBRARY_DEBUG)
              set_property(TARGET Foo::Foo APPEND PROPERTY
              set_target_properties(Foo::Foo PROPERTIES
            set_target_properties(Foo::Foo PROPERTIES

       The RELEASE 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 IMPORTED_CONFIGURATIONS.

       Most of the cache variables should be hidden in  the  ccmake  interface
       unless the user explicitly asks to edit them.


       If  this module replaces an older version, you should set compatibility
       variables to cause the least disruption possible.

          # compatibility variables
          set(Foo_VERSION_STRING ${Foo_VERSION})

       2000-2021 Kitware, Inc. and Contributors

       See attributes(7) for descriptions of the following attributes:

       |Availability   | developer/build/cmake |
       |Stability      | Uncommitted           |

       Source code for open source software components in Oracle  Solaris  can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-

       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source                was                downloaded                from

       Further information about this software can be found on the open source
       community website at http://www.cmake.org/.

3.21.0                           Jun 27, 2022               CMAKE-DEVELOPER(7)