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

FreeBSD Manual Pages

  
 
  

home | help
CMAKE-DEVELOPER(7)		     CMake		    CMAKE-DEVELOPER(7)

NAME
       cmake-developer - CMake Developer Reference

INTRODUCTION
       This manual is intended for reference by	developers modifying the CMake
       source tree itself, and by those	authoring  externally-maintained  mod-
       ules.

PERMITTED C++ SUBSET
       CMake  is required to build with	ancient	C++ compilers and standard li-
       brary implementations.  Some common C++ constructs may not be  used  in
       CMake in	order to build with such toolchains.

   std::auto_ptr
       The  std::auto_ptr  template is deprecated in C++11.  We	want to	use it
       so we can build on C++98	compilers but we do not	want to	turn off  com-
       piler  warnings	about  deprecated  interfaces  in  general.   Use  the
       CM_AUTO_PTR macro instead.

   size_t
       Various implementations have differing implementation of	size_t.	  When
       assigning  the result of	.size()	on a container for example, the	result
       should be assigned to size_t not	to std::size_t,	unsigned int or	 simi-
       lar types.

ADDING COMPILE FEATURES
       CMake  reports an error if a compiler whose features are	known does not
       report support for a particular requested feature.  A compiler is  con-
       sidered	to  have known features	if it reports support for at least one
       feature.

       When adding a new compile feature to CMake, it is  therefore  necessary
       to  list	support	for the	feature	for all	CompilerIds which already have
       one or more feature supported, if the new feature is available for  any
       version of the compiler.

       When  adding the	first supported	feature	to a particular	CompilerId, it
       is necessary to list support for	 all  features	known  to  cmake  (See
       CMAKE_C_COMPILE_FEATURES	 and  CMAKE_CXX_COMPILE_FEATURES  as appropri-
       ate),  where   available	  for	the   compiler.	   Ensure   that   the
       CMAKE_<LANG>_STANDARD_DEFAULT  is set to	the computed internal variable
       CMAKE_<LANG>_STANDARD_COMPUTED_DEFAULT  for  compiler  versions	 which
       should be supported.

       It  is sensible to record the features for the most recent version of a
       particular CompilerId first, and	then work backwards.  It  is  sensible
       to  try to create a continuous range of versions	of feature releases of
       the compiler.  Gaps in the range	indicate incorrect  features  recorded
       for intermediate	releases.

       Generally,  features are	made available for a particular	version	if the
       compiler	vendor documents availability of the feature  with  that  ver-
       sion.   Note that sometimes partially implemented features appear to be
       functional in previous releases (such  as  cxx_constexpr	 in  GNU  4.6,
       though  availability  is	documented in GNU 4.7),	and sometimes compiler
       vendors document	availability of	 features,  though  supporting	infra-
       structure  is not available (such as __has_feature(cxx_generic_lambdas)
       indicating non-availability in Clang 3.4, though	it  is	documented  as
       available,  and fixed in	Clang 3.5).  Similar cases for other compilers
       and versions need to be investigated when extending  CMake  to  support
       them.

       When a vendor releases a	new version of a known compiler	which supports
       a previously unsupported	feature, and there are already known  features
       for  that  compiler, the	feature	should be listed as supported in CMake
       for that	version	of the compiler	as soon	as reasonably possible.

       Standard-specific/compiler-specific  variables  such   CMAKE_CXX98_COM-
       PILE_FEATURES are deliberately not documented.  They only exist for the
       compiler-specific implementation	of adding the -std  compile  flag  for
       compilers which need that.

HELP
       The  Help  directory contains CMake help	manual source files.  They are
       written using the  reStructuredText  markup  syntax  and	 processed  by
       Sphinx to generate the CMake help manuals.

   Markup Constructs
       In addition to using Sphinx to generate the CMake help manuals, we also
       use a C++-implemented document processor	to  print  documents  for  the
       --help-*	 command-line  help options.  It supports a subset of reStruc-
       turedText markup.  When authoring or modifying documents, please	verify
       that  the command-line help looks good in addition to the Sphinx-gener-
       ated html and man pages.

       The command-line	help processor supports	the following  constructs  de-
       fined by	reStructuredText, Sphinx, and a	CMake extension	to Sphinx.

       CMake Domain directives
	      Directives  defined in the CMake Domain for defining CMake docu-
	      mentation	objects	are printed in command-line help output	as  if
	      the lines	were normal paragraph text with	interpretation.

       CMake Domain interpreted	text roles
	      Interpreted   text   roles  defined  in  the  CMake  Domain  for
	      cross-referencing	CMake documentation objects  are  replaced  by
	      their  link  text	 in command-line help output.  Other roles are
	      printed literally	and not	processed.

       code-block directive
	      Add a literal  code  block  without  interpretation.   The  com-
	      mand-line	 help  processor  prints the block content without the
	      leading directive	line and with common indentation  replaced  by
	      one space.

       include directive
	      Include  another	document  source  file.	 The command-line help
	      processor	prints the included document inline with the referenc-
	      ing document.

       literal block after ::
	      A	 paragraph  ending  in	:: followed by a blank line treats the
	      following	indented block as literal text without interpretation.
	      The  command-line	 help  processor  prints  the :: literally and
	      prints the block content with common indentation replaced	by one
	      space.

       note directive
	      Call  out	 a  side note.	The command-line help processor	prints
	      the block	content	as if the lines	 were  normal  paragraph  text
	      with interpretation.

       parsed-literal directive
	      Add  a  literal  block  with  markup  interpretation.   The com-
	      mand-line	help processor prints the block	 content  without  the
	      leading  directive  line and with	common indentation replaced by
	      one space.

       productionlist directive
	      Render context-free grammar productions.	The command-line  help
	      processor	 prints	 the block content as if the lines were	normal
	      paragraph	text with interpretation.

       replace directive
	      Define a |substitution| replacement.  The	command-line help pro-
	      cessor  requires a substitution replacement to be	defined	before
	      it is referenced.

       |substitution| reference
	      Reference	a substitution replacement previously defined  by  the
	      replace directive.  The command-line help	processor performs the
	      substitution and replaces	all newlines in	the  replacement  text
	      with spaces.

       toctree directive
	      Include other document sources in	the Table-of-Contents document
	      tree.  The command-line help  processor  prints  the  referenced
	      documents	inline as part of the referencing document.

       Inline  markup constructs not listed above are printed literally	in the
       command-line help output.  We prefer to use  inline  markup  constructs
       that look correct in source form, so avoid use of \-escapes in favor of
       inline literals when possible.

       Explicit	markup blocks not matching directives listed above are removed
       from  command-line  help	 output.  Do not use them, except for plain ..
       comments	that are removed by Sphinx too.

       Note that nested	indentation of blocks is not recognized	 by  the  com-
       mand-line help processor.  Therefore:

       o Explicit  markup  blocks are recognized only when not indented	inside
	 other blocks.

       o Literal blocks	after paragraphs ending	in :: but not at the  top  in-
	 dentation level may consume all indented lines	following them.

       Try to avoid these cases	in practice.

   CMake Domain
       CMake  adds  a  Sphinx  Domain called cmake, also called	the "CMake Do-
       main".  It defines several "object" types for CMake documentation:

       command
	      A	CMake language command.

       generator
	      A	CMake native build system generator.  See  the	cmake(1)  com-
	      mand-line	tool's -G option.

       manual A	CMake manual page, like	this cmake-developer(7)	manual.

       module A	 CMake	module.	  See  the cmake-modules(7) manual and the in-
	      clude() command.

       policy A	CMake  policy.	 See  the  cmake-policies(7)  manual  and  the
	      cmake_policy() command.

       prop_cache, prop_dir, prop_gbl, prop_sf,	prop_inst, prop_test, prop_tgt
	      A	 CMake	cache, directory, global, source file, installed file,
	      test, or target property,	respectively.  See  the	 cmake-proper-
	      ties(7) manual and the set_property() command.

       variable
	      A	 CMake	language  variable.  See the cmake-variables(7)	manual
	      and the set() command.

       Documentation objects in	 the  CMake  Domain  come  from	 two  sources.
       First,  the  CMake  extension to	Sphinx transforms every	document named
       with the	form Help/<type>/<file-name>.rst to a domain object with  type
       <type>.	The object name	is extracted from the document title, which is
       expected	to be of the form:

	  <object-name>
	  -------------

       and to appear at	or near	the top	of the	.rst  file  before  any	 other
       lines starting in a letter, digit, or <.	 If no such title appears lit-
       erally in the .rst file,	the object name	is the <file-name>.  If	a  ti-
       tle  does  appear,  it  is  expected  that <file-name> is equal to <ob-
       ject-name> with any < and > characters removed.

       Second, the CMake Domain	provides directives to define  objects	inside
       other documents:

	  .. command:: <command-name>

	   This	indented block documents <command-name>.

	  .. variable::	<variable-name>

	   This	indented block documents <variable-name>.

       Object  types for which no directive is available must be defined using
       the first approach above.

   Cross-References
       Sphinx  uses  reStructuredText  interpreted  text  roles	  to   provide
       cross-reference	syntax.	 The CMake Domain provides for each domain ob-
       ject type a role	of the same name to cross-reference it.	 CMake	Domain
       roles are inline	markup of the forms:

	  :type:`name`
	  :type:`text <name>`

       where  type  is	the  domain  object type and name is the domain	object
       name.  In the first form	the link text will be name (or name()  if  the
       type  is	 command) and in the second form the link text will be the ex-
       plicit text.  For example, the code:

	  * The	:command:`list`	command.
	  * The	:command:`list(APPEND)`	sub-command.
	  * The	:command:`list() command <list>`.
	  * The	:command:`list(APPEND) sub-command <list>`.
	  * The	:variable:`CMAKE_VERSION` variable.
	  * The	:prop_tgt:`OUTPUT_NAME_<CONFIG>` target	property.

       produces:

       o The list() command.

       o The list(APPEND) sub-command.

       o The list() command.

       o The list(APPEND) sub-command.

       o The CMAKE_VERSION variable.

       o The OUTPUT_NAME_<CONFIG> target property.

       Note that CMake Domain roles differ from	 Sphinx	 and  reStructuredText
       convention  in  that the	form a<b>, without a space preceding <,	is in-
       terpreted as a name instead of link text	with an	explicit target.  This
       is  necessary  because we use <placeholders> frequently in object names
       like OUTPUT_NAME_<CONFIG>.  The form a <b>, with	a space	 preceding  <,
       is still	interpreted as a link text with	an explicit target.

   Style
   Style: Section Headers
       When  marking  section titles, make the section decoration line as long
       as the title text.  Use only a line below the title, not	above. For ex-
       ample:

	  Title	Text
	  ----------

       Capitalize the first letter of each non-minor word in the title.

       The section header underline character hierarchy	is

       o #: Manual group (part)	in the master document

       o *: Manual (chapter) title

       o =: Section within a manual

       o -: Subsection or CMake	Domain object document title

       o ^: Subsubsection or CMake Domain object document section

       o ": Paragraph or CMake Domain object document subsection

   Style: Whitespace
       Use  two	 spaces	 for indentation.  Use two spaces between sentences in
       prose.

   Style: Line Length
       Prefer to restrict the width of lines to	75-80 columns.	This is	not  a
       hard  restriction, but writing new paragraphs wrapped at	75 columns al-
       lows space for adding minor content without significant re-wrapping  of
       content.

   Style: Prose
       Use American English spellings in prose.

   Style: Starting Literal Blocks
       Prefer  to  mark	 the start of literal blocks with :: at	the end	of the
       preceding  paragraph.  In  cases	 where	the  following	block  gets  a
       code-block  marker,  put	 a  single : at	the end	of the preceding para-
       graph.

   Style: CMake	Command	Signatures
       Command signatures should be marked up as plain literal blocks, not  as
       cmake code-blocks.

       Signatures  are	separated  from	preceding content by a section header.
       That is,	use:

	  ... preceding	paragraph.

	  Normal Libraries
	  ^^^^^^^^^^^^^^^^

	  ::

	    add_library(<lib> ...)

	  This signature is used for ...

       Signatures of commands should wrap optional parts with square brackets,
       and should mark list of optional	arguments with an ellipsis (...).  El-
       ements of the signature which are specified by the user should be spec-
       ified  with  angle  brackets, and may be	referred to in prose using in-
       line-literal syntax.

   Style: Boolean Constants
       Use "OFF" and "ON" for boolean values which  can	 be  modified  by  the
       user,  such  as	POSITION_INDEPENDENT_CODE. Such	properties may be "en-
       abled" and "disabled". Use "True" and "False" for inherent values which
       can't  be  modified after being set, such as the	IMPORTED property of a
       build target.

   Style: Inline Literals
       Mark up references to keywords in signatures,  file  names,  and	 other
       technical terms with inline-literal syntax, for example:

	  If ``WIN32`` is used with :command:`add_executable`, the
	  :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That	command
	  creates the file ``<name>.exe`` on Windows.

   Style: Cross-References
       Mark  up	 linkable references as	links, including repeats.  An alterna-
       tive,	   which       is	used	   by	    wikipedia	    (-
       http://en.wikipedia.org/wiki/WP:REPEATLINK),  is	to link	to a reference
       only once per article. That style is not	used in	CMake documentation.

   Style: Referencing CMake Concepts
       If referring to a concept which corresponds to  a  property,  and  that
       concept is described in a high-level manual, prefer to link to the man-
       ual section instead of the property. For	example:

	  This command creates an :ref:`Imported Target	<Imported Targets>`.

       instead of:

	  This command creates an :prop_tgt:`IMPORTED` target.

       The latter should be used only when referring specifically to the prop-
       erty.

       References to manual sections are not automatically created by creating
       a section, but code such	as:

	  .. _`Imported	Targets`:

       creates a suitable anchor.  Use an anchor name which matches  the  name
       of the corresponding section.  Refer to the anchor using	a cross-refer-
       ence with specified text.

       Imported	Targets	need the IMPORTED term marked up with care in particu-
       lar  because the	term may refer to a command keyword (IMPORTED),	a tar-
       get property (IMPORTED),	or a concept (Imported Targets).

       Where a property, command or variable is	related	conceptually  to  oth-
       ers, by for example, being related to the buildsystem description, gen-
       erator expressions or Qt, each relevant property, command  or  variable
       should  link  to	the primary manual, which provides high-level informa-
       tion.  Only particular information relating to the command should be in
       the documentation of the	command.

   Style: Referencing CMake Domain Objects
       When  referring	to CMake Domain	objects	such as	properties, variables,
       commands	etc, prefer to link to the target object and follow that  with
       the type	of object it is.  For example:

	  Set the :prop_tgt:`AUTOMOC` target property to ``ON``.

       Instead of

	  Set the target property :prop_tgt:`AUTOMOC` to ``ON``.

       The  policy directive is	an exception, and the type us usually referred
       to before the link:

	  If policy :prop_tgt:`CMP0022`	is set to ``NEW`` the behavior is ...

       However,	markup self-references with inline-literal syntax.  For	 exam-
       ple, within the add_executable()	command	documentation, use

	  ``add_executable``

       not

	  :command:`add_executable`

       which is	used elsewhere.

MODULES
       The Modules directory contains CMake-language .cmake module files.

   Module Documentation
       To  document CMake module Modules/<module-name>.cmake, modify Help/man-
       ual/cmake-modules.7.rst to reference the	module in the  toctree	direc-
       tive, in	sorted order, as:

	  /module/<module-name>

       Then  add  the  module document file Help/module/<module-name>.rst con-
       taining just the	line:

	  .. cmake-module:: ../../Modules/<module-name>.cmake

       The cmake-module	directive will scan the	module	file  to  extract  re-
       StructuredText  markup from comment blocks that start in	.rst:.	At the
       top of Modules/<module-name>.cmake, begin with  the  following  license
       notice:

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

       After  this  notice, add	a BLANK	line.  Then, add documentation using a
       Line Comment block of the form:

	  #.rst:
	  # <module-name>
	  # -------------
	  #
	  # <reStructuredText documentation of module>

       or a Bracket Comment of the form:

	  #[[.rst:
	  <module-name>
	  -------------

	  <reStructuredText documentation of module>
	  #]]

       Any number of = may be used in the opening and closing brackets as long
       as  they	 match.	 Content on the	line containing	the closing bracket is
       excluded	if and only if the line	starts in #.

       Additional such .rst: comments may appear anywhere in the module	 file.
       All such	comments must start with # in the first	column.

       For example, a Modules/Findxxx.cmake module may contain:

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

	  #.rst:
	  # FindXxx
	  # -------
	  #
	  # This is a cool module.
	  # This module	does really cool stuff.
	  # It can do even more	than you think.
	  #
	  # It even needs two paragraphs to tell you about it.
	  # And	it defines the following variables:
	  #
	  # * VAR_COOL:	this is	great isn't it?
	  # * VAR_REALLY_COOL: cool right?

	  <code>

	  #[========================================[.rst:
	  .. command:: xxx_do_something

	   This	command	does something for Xxx::

	    xxx_do_something(some arguments)
	  #]========================================]
	  macro(xxx_do_something)
	    <code>
	  endmacro()

       Test  the documentation formatting by running cmake --help-module <mod-
       ule-name>, and also by enabling the SPHINX_HTML and SPHINX_MAN  options
       to build	the documentation.  Edit the comments until generated documen-
       tation looks satisfactory.  To have a .cmake file in this directory NOT
       show  up	 in  the modules documentation,	simply leave out the Help/mod-
       ule/<module-name>.rst file and the Help/manual/cmake-modules.7.rst toc-
       tree entry.

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

       The primary task	of a find module is to determine whether a package ex-
       ists  on	 the  system, set the <package>_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 li-
       brary 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
       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...]
		       [NO_POLICY_SCOPE])

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

       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.

       Like all	modules, find modules should be	properly documented.  To add a
       module to the CMake documentation, follow the steps in the Module Docu-
       mentation section above.

   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.

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

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

       Xxx_DEFINITIONS
	      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>

       Xxx_EXECUTABLE
	      Where to find the	Xxx tool.

       Xxx_Yyy_EXECUTABLE
	      Where to find the	Yyy tool that comes with Xxx.

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

       Xxx_ROOT_DIR
	      Where to find the	base directory of Xxx.

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

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

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

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

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

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

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

       Xxx_VERSION_MAJOR
	      The major	version	of the package found, if any.

       Xxx_VERSION_MINOR
	      The minor	version	of the package found, if any.

       Xxx_VERSION_PATCH
	      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)

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

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

       Xxx_INCLUDE_DIR
	      Where to find headers for	using the Xxx library.

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

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

       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 first thing that is needed is a license notice.

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

       Next  we	 need  module documentation.  CMake's documentation system re-
       quires you to follow the	license	notice with a blank line and then with
       a  documentation	 marker	and the	name of	the module.  You should	follow
       this with a simple statement of what the	module does.

	  #.rst:
	  # FindFoo
	  # -------
	  #
	  # Finds the Foo library
	  #

       More description	may be required	 for  some  packages.	If  there  are
       caveats	or  other  details users of the	module should be aware of, you
       can add further paragraphs below	this.  Then you	need to	document  what
       variables and imported targets are set by the module, such as

	  # This will define the following variables::
	  #
	  #   Foo_FOUND	   - True if the system	has the	Foo library
	  #   Foo_VERSION  - The version of the	Foo library which was found
	  #
	  # and	the following imported targets::
	  #
	  #   Foo::Foo	 - The Foo library

       If the package provides any macros, they	should be listed here, but can
       be documented where they	are defined.   See  the	 Module	 Documentation
       section above for more details.

       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.

	  find_package(PkgConfig)
	  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.

	  find_path(Foo_INCLUDE_DIR
	    NAMES foo.h
	    PATHS ${PC_Foo_INCLUDE_DIRS}
	    PATH_SUFFIXES Foo
	  )
	  find_library(Foo_LIBRARY
	    NAMES foo
	    PATHS ${PC_Foo_LIBRARY_DIRS}
	  )

       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

	  include(FindPackageHandleStandardArgs)
	  find_package_handle_standard_args(Foo
	    FOUND_VAR Foo_FOUND
	    REQUIRED_VARS
	      Foo_LIBRARY
	      Foo_INCLUDE_DIR
	    VERSION_VAR	Foo_VERSION
	  )

       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

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

       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-
       formation).

       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
       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}"
	      INTERFACE_COMPILE_OPTIONS	"${PC_Foo_CFLAGS_OTHER}"
	      INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"
	    )
	  endif()

       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(Foo_FOUND)
	    if (NOT TARGET Foo::Foo)
	      add_library(Foo::Foo UNKNOWN IMPORTED)
	    endif()
	    if (Foo_LIBRARY_RELEASE)
	      set_property(TARGET Foo::Foo APPEND PROPERTY
		IMPORTED_CONFIGURATIONS	RELEASE
	      )
	      set_target_properties(Foo::Foo PROPERTIES
		IMPORTED_LOCATION_RELEASE "${Foo_LIBRARY_RELEASE}"
	      )
	    endif()
	    if (Foo_LIBRARY_DEBUG)
	      set_property(TARGET Foo::Foo APPEND PROPERTY
		IMPORTED_CONFIGURATIONS	DEBUG
	      )
	      set_target_properties(Foo::Foo PROPERTIES
		IMPORTED_LOCATION_DEBUG	"${Foo_LIBRARY_DEBUG}"
	      )
	    endif()
	    set_target_properties(Foo::Foo PROPERTIES
	      INTERFACE_COMPILE_OPTIONS	"${PC_Foo_CFLAGS_OTHER}"
	      INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"
	    )
	  endif()

       The RELEASE variant should be listed first in the property so that that
       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.

	  mark_as_advanced(
	    Foo_INCLUDE_DIR
	    Foo_LIBRARY
	  )

       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})

COPYRIGHT
       2000-2017 Kitware, Inc. and Contributors

3.8.2				 Jul 02, 2017		    CMAKE-DEVELOPER(7)

NAME | INTRODUCTION | PERMITTED C++ SUBSET | ADDING COMPILE FEATURES | HELP | MODULES | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cmake-developer&sektion=7&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help