Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       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  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 ex-
       ists  on	 the  system,  set the <PackageName>_FOUND variable to reflect
       this and	provide	any variables, macros and imported targets required to
       use  the	 package.   A find module is useful in cases where an upstream
       library does not	provide	a config file package.

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

       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]]]]
		       [[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 li-
       braries)	should search for the components listed	in Foo_FIND_COMPONENTS
       if it is	set , and only set Foo_FOUND to	true if	for each  searched-for
       component  <c>  that was	not found, Foo_FIND_REQUIRED_<c> is not	set to
       true.   The  HANDLE_COMPONENTS  argument	 of  find_package_handle_stan-
       dard_args() can be used to implement this.

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

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

   Standard Variable Names
       For a FindXxx.cmake module that takes the approach of setting variables
       (either instead of or in	addition to creating  imported	targets),  the
       following  variable  names should be used to keep things	consistent be-
       tween find modules.  Note that all variables start with	Xxx_  to  make
       sure they do not	interfere with other find modules; the same considera-
       tion applies to macros, functions and imported targets.

	      The final	set of include directories listed in one variable  for
	      use by client code.  This	should not be a	cache entry.

	      The  libraries  to link against to use Xxx. These	should include
	      full paths.  This	should not be a	cache entry.

	      Definitions to use when compiling	code that uses Xxx.  This  re-
	      ally  shouldn't include options such as -DHAS_JPEG that a	client
	      source-code file uses to decide whether to #include <jpeg.h>

	      Where to find the	Xxx tool.

	      Where to find the	Yyy tool that comes with Xxx.

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

	      Where to find the	base directory of Xxx.

	      Expect Version Yy	if true. Make sure at most  one	 of  these  is
	      ever true.

	      If False,	do not try to use the relevant CMake wrapping command.

	      If False,	optional Yy part of Xxx	system is not available.

	      Set  to  false, or undefined, if we haven't found, or don't want
	      to use Xxx.

	      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.

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

	      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,
       but are typically cache variables for users to edit and control the be-
       haviour of find modules (like entering the path to a library manually)

	      The  path	 of  the Xxx library (as used with find_library(), for

	      The path of the Yy library that is part of the  Xxx  system.  It
	      may or may not be	required to use	Xxx.

	      Where to find headers for	using the Xxx library.

	      Where  to	 find headers for using	the Yy library of the Xxx sys-

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

       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 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 in-
       formation 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
	    NAMES foo

       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


       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  re-
       quired 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  ap-
       proaches,  as  discussed	in the Find Modules section above.  The	tradi-
       tional variable approach	looks like

	    set(Foo_LIBRARIES ${Foo_LIBRARY})

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

       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 ap-
       propriate diagnostic messages if	that target does not exist (see	policy

	  if(Foo_FOUND AND NOT TARGET Foo::Foo)
	    add_library(Foo::Foo UNKNOWN IMPORTED)
	    set_target_properties(Foo::Foo PROPERTIES

       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 in-
       formation 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  de-
       termine the type	by inspecting the files.

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

	    if (NOT TARGET Foo::Foo)
	      add_library(Foo::Foo UNKNOWN IMPORTED)
	      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 ex-
       act 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

       2000-2020 Kitware, Inc. and Contributors

3.18.2				 Aug 27, 2020		    CMAKE-DEVELOPER(7)


Want to link to this manual page? Use this URL:

home | help