Help/guide/using-dependencies/index.rst - third_party/cmake - Git at Google

 Using Dependencies Guide
 ************************

 .. only:: html

    .. contents::

 Introduction
 ============

 For developers wishing to use CMake to consume a third
 party binary package, there are multiple possibilities
 regarding how to optimally do so, depending on how
 CMake-aware the third-party library is.

 CMake files provided with a software package contain
 instructions for finding each build dependency.  Some
 build dependencies are optional in that the build may
 succeed with a different feature set if the dependency
 is missing, and some dependencies are required.  CMake
 searches well-known locations for each dependency, and
 the provided software may supply additional hints or
 locations to CMake to find each dependency.

 If a required dependency is not found by
 :manual:`cmake(1)`, the cache is populated with an entry
 which contains a ``NOTFOUND`` value.  This value can be
 replaced by specifying it on the command line, or in
 the :manual:`ccmake(1)` or :manual:`cmake-gui(1)` tool.
 See the :guide:`User Interaction Guide` for
 more about setting cache entries.

 Libraries providing Config-file packages
 ----------------------------------------

 The most convenient way for a third-party to provide library
 binaries for use with CMake is to provide
 :ref:`Config File Packages`.  These packages are text files
 shipped with the library which instruct CMake how to use the
 library binaries and associated headers, helper tools and
 CMake macros provided by the library.

 The config files can usually be found in a directory whose
 name matches the pattern ``lib/cmake/<PackageName>``, though
 they may be in other locations instead.  The
 ``<PackageName>`` corresponds to use in CMake code with the
 :command:`find_package` command such as
 ``find_package(PackageName REQUIRED)``.

 The ``lib/cmake/<PackageName>`` directory will contain a
 file which is either named ``<PackageName>Config.cmake``
 or ``<PackageName>-config.cmake``.  This is the entry point
 to the package for CMake.  A separate optional file named
 ``<PackageName>ConfigVersion.cmake`` may also exist in the
 directory.  This file is used by CMake to determine whether
 the version of the third party package satisfies uses of the
 :command:`find_package` command which specify version
 constraints.  It is optional to specify a version when using
 :command:`find_package`, even if a ``ConfigVersion`` file is
 present.

 If the ``Config.cmake`` file is found and the
 optionally-specified version is satisfied, then the CMake
 :command:`find_package` command considers the package to be
 found and the entire library package is assumed to be
 complete as designed.

 There may be additional files providing CMake macros or
 :ref:`imported targets` for you to use.  CMake does not
 enforce any naming convention for these
 files.  They are related to the primary ``Config`` file by
 use of the CMake :command:`include` command.

 :guide:`Invoking CMake <User Interaction Guide>` with the
 intent of using a package of third party binaries requires
 that cmake :command:`find_package` commands succeed in finding
 the package.  If the location of the package is in a directory
 known to CMake, the :command:`find_package` call should
 succeed.  The directories known to cmake are platform-specific.
 For example, packages installed on Linux with a standard
 system package manager will be found in the ``/usr`` prefix
 automatically.  Packages installed in ``Program Files`` on
 Windows will similarly be found automatically.

 Packages which are not found automatically are in locations
 not predictable to CMake such as ``/opt/mylib`` or
 ``$HOME/dev/prefix``.  This is a normal situation and CMake
 provides several ways for users to specify where to find
 such libraries.

 The :variable:`CMAKE_PREFIX_PATH` variable may be
 :ref:`set when invoking CMake <Setting Build Variables>`.
 It is treated as a list of paths to search for
 :ref:`Config File Packages`.  A package installed in
 ``/opt/somepackage`` will typically install config files
 such as
 ``/opt/somepackage/lib/cmake/somePackage/SomePackageConfig.cmake``.
 In that case, ``/opt/somepackage`` should be added to
 :variable:`CMAKE_PREFIX_PATH`.

 The environment variable ``CMAKE_PREFIX_PATH`` may also be
 populated with prefixes to search for packages.  Like the
 ``PATH`` environment variable, this is a list and needs to use
 the platform-specific environment variable list item separator
 (``:`` on Unix and ``;`` on Windows).

 The :variable:`CMAKE_PREFIX_PATH` variable provides convenience
 in cases where multiple prefixes need to be specified, or when
 multiple different package binaries are available in the same
 prefix.  Paths to packages may also be specified by setting
 variables matching ``<PackageName>_DIR``, such as
 ``SomePackage_DIR``.  Note that this is not a prefix but should
 be a full path to a directory containing a config-style package
 file, such as ``/opt/somepackage/lib/cmake/SomePackage/`` in
 the above example.

 Imported Targets from Packages
 ------------------------------

 A third-party package which provides config-file packages may
 also provide :ref:`Imported targets`. These will be
 specified in files containing configuration-specific file
 paths relevant to the package, such as debug and release
 versions of libraries.

 Often the third-party package documentation will point out the
 names of imported targets available after a successful
 ``find_package`` for a library.  Those imported target names
 can be used with the :command:`target_link_libraries` command.

 A complete example which makes a simple use of a third party
 library might look like:

 .. code-block:: cmake

     cmake_minimum_required(VERSION 3.10)
     project(MyExeProject VERSION 1.0.0)

     find_package(SomePackage REQUIRED)
     add_executable(MyExe main.cpp)
     target_link_libraries(MyExe PRIVATE SomePrefix::LibName)

 See :manual:`cmake-buildsystem(7)` for further information
 about developing a CMake buildsystem.

 Libraries not Providing Config-file Packages
 --------------------------------------------

 Third-party libraries which do not provide config-file packages
 can still be found with the :command:`find_package` command, if
 a ``FindSomePackage.cmake`` file is available.

 These module-file packages are different to config-file packages
 in that:

 #. They should not be provided by the third party, except
    perhaps in the form of documentation
 #. The availability of a ``Find<PackageName>.cmake`` file does
    not indicate the availability of the binaries themselves.
 #. CMake does not search the :variable:`CMAKE_PREFIX_PATH` for
    ``Find<PackageName>.cmake`` files.  Instead CMake searches
    for such files in the :variable:`CMAKE_MODULE_PATH`
    variable. It is common for users to set the
    :variable:`CMAKE_MODULE_PATH` when running CMake, and it is
    common for CMake projects to append to
    :variable:`CMAKE_MODULE_PATH` to allow use of local
    module-file packages.
 #. CMake ships ``Find<PackageName>.cmake`` files for some
    :manual:`third party packages <cmake-modules(7)>`
    for convenience in cases where the third party does
    not provide config-file packages directly.  These files are
    a maintenance burden for CMake, so new Find modules are
    generally not added to CMake anymore.  Third-parties should
    provide config file packages instead of relying on a Find
    module to be provided by CMake.

 Module-file packages may also provide :ref:`Imported targets`.
 A complete example which finds such a package might look
 like:

 .. code-block:: cmake

     cmake_minimum_required(VERSION 3.10)
     project(MyExeProject VERSION 1.0.0)

     find_package(PNG REQUIRED)

     # Add path to a FindSomePackage.cmake file
     list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
     find_package(SomePackage REQUIRED)

     add_executable(MyExe main.cpp)
     target_link_libraries(MyExe PRIVATE
         PNG::PNG
         SomePrefix::LibName
     )

 The :variable:`<PackageName>_ROOT` variable is also
 searched as a prefix for :command:`find_package` calls using
 module-file packages such as ``FindSomePackage``.
	Using Dependencies Guide
	************************

	.. only:: html

	.. contents::

	Introduction
	============

	For developers wishing to use CMake to consume a third
	party binary package, there are multiple possibilities
	regarding how to optimally do so, depending on how
	CMake-aware the third-party library is.

	CMake files provided with a software package contain
	instructions for finding each build dependency. Some
	build dependencies are optional in that the build may
	succeed with a different feature set if the dependency
	is missing, and some dependencies are required. CMake
	searches well-known locations for each dependency, and
	the provided software may supply additional hints or
	locations to CMake to find each dependency.

	If a required dependency is not found by
	:manual:`cmake(1)`, the cache is populated with an entry
	which contains a ``NOTFOUND`` value. This value can be
	replaced by specifying it on the command line, or in
	the :manual:`ccmake(1)` or :manual:`cmake-gui(1)` tool.
	See the :guide:`User Interaction Guide` for
	more about setting cache entries.

	Libraries providing Config-file packages
	----------------------------------------

	The most convenient way for a third-party to provide library
	binaries for use with CMake is to provide
	:ref:`Config File Packages`. These packages are text files
	shipped with the library which instruct CMake how to use the
	library binaries and associated headers, helper tools and
	CMake macros provided by the library.

	The config files can usually be found in a directory whose
	name matches the pattern ``lib/cmake/<PackageName>``, though
	they may be in other locations instead. The
	``<PackageName>`` corresponds to use in CMake code with the
	:command:`find_package` command such as
	``find_package(PackageName REQUIRED)``.

	The ``lib/cmake/<PackageName>`` directory will contain a
	file which is either named ``<PackageName>Config.cmake``
	or ``<PackageName>-config.cmake``. This is the entry point
	to the package for CMake. A separate optional file named
	``<PackageName>ConfigVersion.cmake`` may also exist in the
	directory. This file is used by CMake to determine whether
	the version of the third party package satisfies uses of the
	:command:`find_package` command which specify version
	constraints. It is optional to specify a version when using
	:command:`find_package`, even if a ``ConfigVersion`` file is
	present.

	If the ``Config.cmake`` file is found and the
	optionally-specified version is satisfied, then the CMake
	:command:`find_package` command considers the package to be
	found and the entire library package is assumed to be
	complete as designed.

	There may be additional files providing CMake macros or
	:ref:`imported targets` for you to use. CMake does not
	enforce any naming convention for these
	files. They are related to the primary ``Config`` file by
	use of the CMake :command:`include` command.

	:guide:`Invoking CMake <User Interaction Guide>` with the
	intent of using a package of third party binaries requires
	that cmake :command:`find_package` commands succeed in finding
	the package. If the location of the package is in a directory
	known to CMake, the :command:`find_package` call should
	succeed. The directories known to cmake are platform-specific.
	For example, packages installed on Linux with a standard
	system package manager will be found in the ``/usr`` prefix
	automatically. Packages installed in ``Program Files`` on
	Windows will similarly be found automatically.

	Packages which are not found automatically are in locations
	not predictable to CMake such as ``/opt/mylib`` or
	``$HOME/dev/prefix``. This is a normal situation and CMake
	provides several ways for users to specify where to find
	such libraries.

	The :variable:`CMAKE_PREFIX_PATH` variable may be
	:ref:`set when invoking CMake <Setting Build Variables>`.
	It is treated as a list of paths to search for
	:ref:`Config File Packages`. A package installed in
	``/opt/somepackage`` will typically install config files
	such as
	``/opt/somepackage/lib/cmake/somePackage/SomePackageConfig.cmake``.
	In that case, ``/opt/somepackage`` should be added to
	:variable:`CMAKE_PREFIX_PATH`.

	The environment variable ``CMAKE_PREFIX_PATH`` may also be
	populated with prefixes to search for packages. Like the
	``PATH`` environment variable, this is a list and needs to use
	the platform-specific environment variable list item separator
	(``:`` on Unix and ``;`` on Windows).

	The :variable:`CMAKE_PREFIX_PATH` variable provides convenience
	in cases where multiple prefixes need to be specified, or when
	multiple different package binaries are available in the same
	prefix. Paths to packages may also be specified by setting
	variables matching ``<PackageName>_DIR``, such as
	``SomePackage_DIR``. Note that this is not a prefix but should
	be a full path to a directory containing a config-style package
	file, such as ``/opt/somepackage/lib/cmake/SomePackage/`` in
	the above example.

	Imported Targets from Packages
	------------------------------

	A third-party package which provides config-file packages may
	also provide :ref:`Imported targets`. These will be
	specified in files containing configuration-specific file
	paths relevant to the package, such as debug and release
	versions of libraries.

	Often the third-party package documentation will point out the
	names of imported targets available after a successful
	``find_package`` for a library. Those imported target names
	can be used with the :command:`target_link_libraries` command.

	A complete example which makes a simple use of a third party
	library might look like:

	.. code-block:: cmake

	cmake_minimum_required(VERSION 3.10)
	project(MyExeProject VERSION 1.0.0)

	find_package(SomePackage REQUIRED)
	add_executable(MyExe main.cpp)
	target_link_libraries(MyExe PRIVATE SomePrefix::LibName)

	See :manual:`cmake-buildsystem(7)` for further information
	about developing a CMake buildsystem.

	Libraries not Providing Config-file Packages
	--------------------------------------------

	Third-party libraries which do not provide config-file packages
	can still be found with the :command:`find_package` command, if
	a ``FindSomePackage.cmake`` file is available.

	These module-file packages are different to config-file packages
	in that:

	#. They should not be provided by the third party, except
	perhaps in the form of documentation
	#. The availability of a ``Find<PackageName>.cmake`` file does
	not indicate the availability of the binaries themselves.
	#. CMake does not search the :variable:`CMAKE_PREFIX_PATH` for
	``Find<PackageName>.cmake`` files. Instead CMake searches
	for such files in the :variable:`CMAKE_MODULE_PATH`
	variable. It is common for users to set the
	:variable:`CMAKE_MODULE_PATH` when running CMake, and it is
	common for CMake projects to append to
	:variable:`CMAKE_MODULE_PATH` to allow use of local
	module-file packages.
	#. CMake ships ``Find<PackageName>.cmake`` files for some
	:manual:`third party packages <cmake-modules(7)>`
	for convenience in cases where the third party does
	not provide config-file packages directly. These files are
	a maintenance burden for CMake, so new Find modules are
	generally not added to CMake anymore. Third-parties should
	provide config file packages instead of relying on a Find
	module to be provided by CMake.

	Module-file packages may also provide :ref:`Imported targets`.
	A complete example which finds such a package might look
	like:

	.. code-block:: cmake

	cmake_minimum_required(VERSION 3.10)
	project(MyExeProject VERSION 1.0.0)

	find_package(PNG REQUIRED)

	# Add path to a FindSomePackage.cmake file
	list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
	find_package(SomePackage REQUIRED)

	add_executable(MyExe main.cpp)
	target_link_libraries(MyExe PRIVATE
	PNG::PNG
	SomePrefix::LibName
	)

	The :variable:`<PackageName>_ROOT` variable is also
	searched as a prefix for :command:`find_package` calls using
	module-file packages such as ``FindSomePackage``.