OXIESEC PANEL

	Name	Size	Modified	Perms
	📁 ..	-	04/04/2023 07:10:48 PM	rwxr-xr-x
	📄 index.html	54.8 KB	04/04/2023 07:05:08 PM	rw-r--r--

Editing: index.html

<!DOCTYPE html>

<title>Using Dependencies Guide &mdash; CMake 3.26.3 Documentation</title>

</head><body>

<div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../../genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li class="right" >
 <a href="../importing-exporting/index.html" title="Importing and Exporting Guide"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="../user-interaction/index.html" title="User Interaction Guide"
 accesskey="P">previous</a> |</li>
 <li>
 <img src="../../_static/cmake-logo-16.png" alt=""
 style="vertical-align: middle; margin-top: -2px" />
 </li>
 <li>
 <a href="https://cmake.org/">CMake</a> &#187;
 </li>
 <li>
 <a href="../../index.html">3.26.3 Documentation</a> &#187;
 </li>

<li class="nav-item nav-item-this"><a href="">Using Dependencies Guide</a></li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <section id="using-dependencies-guide">
<h1><a class="toc-backref" href="#id3" role="doc-backlink">Using Dependencies Guide</a><a class="headerlink" href="#using-dependencies-guide" title="Permalink to this heading">¶</a></h1>
<nav class="contents" id="contents">
Contents
<ul class="simple">
<li><a class="reference internal" href="#using-dependencies-guide" id="id3">Using Dependencies Guide</a>
<ul>
<li><a class="reference internal" href="#introduction" id="id4">Introduction</a></li>
<li><a class="reference internal" href="#using-pre-built-packages-with-find-package" id="id5">Using Pre-built Packages With <code class="docutils literal notranslate">find_package()</code></a>
<ul>
<li><a class="reference internal" href="#config-file-packages" id="id6">Config-file packages</a></li>
<li><a class="reference internal" href="#find-module-files" id="id7">Find Module Files</a></li>
<li><a class="reference internal" href="#imported-targets" id="id8">Imported Targets</a></li>
</ul>
</li>
<li><a class="reference internal" href="#downloading-and-building-from-source-with-fetchcontent" id="id9">Downloading And Building From Source With <code class="docutils literal notranslate">FetchContent</code></a></li>
<li><a class="reference internal" href="#fetchcontent-and-find-package-integration" id="id10"><code class="docutils literal notranslate">FetchContent</code> And <code class="docutils literal notranslate">find_package()</code> Integration</a></li>
<li><a class="reference internal" href="#dependency-providers" id="id11">Dependency Providers</a></li>
</ul>
</li>
</ul>
</nav>
<section id="introduction">
<h2><a class="toc-backref" href="#id4" role="doc-backlink">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this heading">¶</a></h2>
Projects will frequently depend on other projects, assets, and artifacts.
CMake provides a number of ways to incorporate such things into the build.
Projects and users have the flexibility to choose between methods that
best suit their needs.
The primary methods of bringing dependencies into the build are the
<a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> command and the <a class="reference internal" href="../../module/FetchContent.html#module:FetchContent" title="FetchContent"><code class="xref cmake cmake-module docutils literal notranslate">FetchContent</code></a> module.
The <a class="reference internal" href="../../module/FindPkgConfig.html#module:FindPkgConfig" title="FindPkgConfig"><code class="xref cmake cmake-module docutils literal notranslate">FindPkgConfig</code></a> module is also sometimes used, although it
lacks some of the integration of the other two and is not discussed any
further in this guide.
Dependencies can also be made available by a custom
<a class="reference internal" href="../../command/cmake_language.html#dependency-providers">dependency provider</a>.
This might be a third party package manager, or it might be custom code
implemented by the developer. Dependency providers co-operate with the
primary methods mentioned above to extend their flexibility.
</section>
<section id="using-pre-built-packages-with-find-package">
<h2><a class="toc-backref" href="#id5" role="doc-backlink">Using Pre-built Packages With <code class="docutils literal notranslate">find_package()</code></a><a class="headerlink" href="#using-pre-built-packages-with-find-package" title="Permalink to this heading">¶</a></h2>
A package needed by the project may already be built and available at some
location on the user's system. That package might have also been built by
CMake, or it could have used a different build system entirely. It might
even just be a collection of files that didn't need to be built at all.
CMake provides the <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> command for these scenarios.
It searches well-known locations, along with additional hints and paths
provided by the project or user. It also supports package components and
packages being optional. Result variables are provided to allow the project
to customize its own behavior according to whether the package or specific
components were found.
In most cases, projects should generally use the <a class="reference internal" href="../../command/find_package.html#basic-signature">Basic Signature</a>.
Most of the time, this will involve just the package name, maybe a version
constraint, and the <code class="docutils literal notranslate">REQUIRED</code> keyword if the dependency is not optional.
A set of package components may also be specified.
<div class="literal-block-wrapper docutils container" id="id1">
<div class="code-block-caption">Examples of <code class="docutils literal notranslate">find_package()</code> basic signature<a class="headerlink" href="#id1" title="Permalink to this code">¶</a></div>
<div class="highlight-cmake notranslate"><div class="highlight"><pre>find_package(Catch2)
find_package(GTest REQUIRED)
find_package(Boost 1.79 COMPONENTS date_time)
</pre></div>
</div>
</div>
The <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> command supports two main methods for carrying
out the search:
<dl class="simple">
<dt>Config mode</dt><dd>With this method, the command looks for files that are typically provided
by the package itself. This is the more reliable method of the two, since
the package details should always be in sync with the package.
</dd>
<dt>Module mode</dt><dd>Not all packages are CMake-aware. Many don't provide the files needed to
support config mode. For such cases, a Find module file can be provided
separately, either by the project or by CMake. A Find module is typically
a heuristic implementation which knows what the package normally provides
and how to present that package to the project. Since Find modules are
usually distributed separately from the package, they are not as reliable.
They are typically maintained separately, and they are likely to follow
different release schedules, so they can easily become out-of-date.
</dd>
</dl>
Depending on the arguments used, <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> may use one or both
of the above methods. By restricting the options to just the basic signature,
both config mode and module mode can be used to satisfy the dependency.
The presence of other options may restrict the call to using only one of the
two methods, potentially reducing the command's ability to find the dependency.
See the <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> documentation for full details about this
complex topic.
For both search methods, the user can also set cache variables on the
<a class="reference internal" href="../../manual/cmake.1.html#manual:cmake(1)" title="cmake(1)"><code class="xref cmake cmake-manual docutils literal notranslate">cmake(1)</code></a> command line or in the <a class="reference internal" href="../../manual/ccmake.1.html#manual:ccmake(1)" title="ccmake(1)"><code class="xref cmake cmake-manual docutils literal notranslate">ccmake(1)</code></a> or
<a class="reference internal" href="../../manual/cmake-gui.1.html#manual:cmake-gui(1)" title="cmake-gui(1)"><code class="xref cmake cmake-manual docutils literal notranslate">cmake-gui(1)</code></a> UI tools to influence and override where to find
packages. See the <a class="reference internal" href="../user-interaction/index.html#setting-build-variables">User Interaction Guide</a>
for more on how to set cache variables.
<section id="config-file-packages">
<h3><a class="toc-backref" href="#id6" role="doc-backlink">Config-file packages</a><a class="headerlink" href="#config-file-packages" title="Permalink to this heading">¶</a></h3>
The preferred way for a third party to provide executables, libraries,
headers, and other files for use with CMake is to provide
<a class="reference internal" href="../../manual/cmake-packages.7.html#config-file-packages">config files</a>. These are text files shipped
with the package, which define CMake targets, variables, commands, and so on.
The config file is an ordinary CMake script, which is read in by the
<a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> command.
The config files can usually be found in a directory whose name matches the
pattern <code class="docutils literal notranslate">lib/cmake/&lt;PackageName&gt;</code>, although they may be in other locations
instead (see <a class="reference internal" href="../../command/find_package.html#search-procedure">Config Mode Search Procedure</a>). The <code class="docutils literal notranslate">&lt;PackageName&gt;</code> is usually the
first argument to the <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> command, and it may even be the
only argument. Alternative names can also be specified with the <code class="docutils literal notranslate">NAMES</code>
option:
<div class="literal-block-wrapper docutils container" id="id2">
<div class="code-block-caption">Providing alternative names when finding a package<a class="headerlink" href="#id2" title="Permalink to this code">¶</a></div>
<div class="highlight-cmake notranslate"><div class="highlight"><pre>find_package(SomeThing
 NAMES
 SameThingOtherName # Another name for the package
 SomeThing # Also still look for its canonical name
)
</pre></div>
</div>
</div>
The config file must be named either <code class="docutils literal notranslate">&lt;PackageName&gt;Config.cmake</code> or
<code class="docutils literal notranslate">&lt;LowercasePackageName&gt;-config.cmake</code> (the former is used for the remainder
of this guide, but both are supported). This file is the entry point
to the package for CMake. A separate optional file named
<code class="docutils literal notranslate">&lt;PackageName&gt;ConfigVersion.cmake</code> or
<code class="docutils literal notranslate">&lt;LowercasePackageName&gt;-config-version.cmake</code> may also exist in the same
directory. This file is used by CMake to determine whether the version of
the package satisfies any version constraint included in the call to
<a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a>. It is optional to specify a version when calling
<a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a>, even if a <code class="docutils literal notranslate">&lt;PackageName&gt;ConfigVersion.cmake</code>
file is present.
If the <code class="docutils literal notranslate">&lt;PackageName&gt;Config.cmake</code> file is found and any version constraint
is satisfied, the <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> command considers the package to be
found, and the entire package is assumed to be complete as designed.
There may be additional files providing CMake commands or
<a class="reference internal" href="../../manual/cmake-buildsystem.7.html#imported-targets">Imported Targets</a> for you to use. CMake does not enforce any naming
convention for these files. They are related to the primary
<code class="docutils literal notranslate">&lt;PackageName&gt;Config.cmake</code> file by use of the CMake <a class="reference internal" href="../../command/include.html#command:include" title="include"><code class="xref cmake cmake-command docutils literal notranslate">include()</code></a>
command. The <code class="docutils literal notranslate">&lt;PackageName&gt;Config.cmake</code> file would typically include
these for you, so they won't usually require any additional step other than
the call to <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a>.
If the location of the package is in a
<a class="reference internal" href="../../command/find_package.html#search-procedure">directory known to CMake</a>, the
<a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> 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 <code class="docutils literal notranslate">/usr</code> prefix
automatically. Packages installed in <code class="docutils literal notranslate">Program Files</code> on Windows will
similarly be found automatically.
Packages will not be found automatically without help if they are in
locations not known to CMake, such as <code class="docutils literal notranslate">/opt/mylib</code> or <code class="docutils literal notranslate">$HOME/dev/prefix</code>.
This is a normal situation, and CMake provides several ways for users to
specify where to find such libraries.
The <a class="reference internal" href="../../variable/CMAKE_PREFIX_PATH.html#variable:CMAKE_PREFIX_PATH" title="CMAKE_PREFIX_PATH"><code class="xref cmake cmake-variable docutils literal notranslate">CMAKE_PREFIX_PATH</code></a> variable may be
<a class="reference internal" href="../user-interaction/index.html#setting-build-variables">set when invoking CMake</a>.
It is treated as a list of base paths in which to search for
<a class="reference internal" href="../../manual/cmake-packages.7.html#config-file-packages">config files</a>. A package installed in
<code class="docutils literal notranslate">/opt/somepackage</code> will typically install config files such as
<code class="docutils literal notranslate">/opt/somepackage/lib/cmake/somePackage/SomePackageConfig.cmake</code>.
In that case, <code class="docutils literal notranslate">/opt/somepackage</code> should be added to
<a class="reference internal" href="../../variable/CMAKE_PREFIX_PATH.html#variable:CMAKE_PREFIX_PATH" title="CMAKE_PREFIX_PATH"><code class="xref cmake cmake-variable docutils literal notranslate">CMAKE_PREFIX_PATH</code></a>.
The environment variable <code class="docutils literal notranslate">CMAKE_PREFIX_PATH</code> may also be populated with
prefixes to search for packages. Like the <code class="docutils literal notranslate">PATH</code> environment variable,
this is a list, but it needs to use the platform-specific environment variable
list item separator (<code class="docutils literal notranslate">:</code> on Unix and <code class="docutils literal notranslate">;</code> on Windows).
The <a class="reference internal" href="../../variable/CMAKE_PREFIX_PATH.html#variable:CMAKE_PREFIX_PATH" title="CMAKE_PREFIX_PATH"><code class="xref cmake cmake-variable docutils literal notranslate">CMAKE_PREFIX_PATH</code></a> variable provides convenience in cases
where multiple prefixes need to be specified, or when multiple packages
are available under the same prefix. Paths to packages may also be
specified by setting variables matching <code class="docutils literal notranslate">&lt;PackageName&gt;_DIR</code>, such as
<code class="docutils literal notranslate">SomePackage_DIR</code>. Note that this is not a prefix, but should be a full
path to a directory containing a config-style package file, such as
<code class="docutils literal notranslate">/opt/somepackage/lib/cmake/SomePackage</code> in the above example.
See the <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> documentation for other CMake variables and
environment variables that can affect the search.
</section>
<section id="find-module-files">
<h3><a class="toc-backref" href="#id7" role="doc-backlink">Find Module Files</a><a class="headerlink" href="#find-module-files" title="Permalink to this heading">¶</a></h3>
Packages which do not provide config files can still be found with the
<a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> command, if a <code class="docutils literal notranslate">FindSomePackage.cmake</code> file is
available. These Find module files are different to config files in that:
<ol class="arabic simple">
<li>Find module files should not be provided by the package itself.</li>
<li>The availability of a <code class="docutils literal notranslate">Find&lt;PackageName&gt;.cmake</code> file does not indicate
the availability of the package, or any particular part of the package.</li>
<li>CMake does not search the locations specified in the
<a class="reference internal" href="../../variable/CMAKE_PREFIX_PATH.html#variable:CMAKE_PREFIX_PATH" title="CMAKE_PREFIX_PATH"><code class="xref cmake cmake-variable docutils literal notranslate">CMAKE_PREFIX_PATH</code></a> variable for <code class="docutils literal notranslate">Find&lt;PackageName&gt;.cmake</code>
files. Instead, CMake searches for such files in the locations given
by the <a class="reference internal" href="../../variable/CMAKE_MODULE_PATH.html#variable:CMAKE_MODULE_PATH" title="CMAKE_MODULE_PATH"><code class="xref cmake cmake-variable docutils literal notranslate">CMAKE_MODULE_PATH</code></a> variable. It is common for users to
set the <a class="reference internal" href="../../variable/CMAKE_MODULE_PATH.html#variable:CMAKE_MODULE_PATH" title="CMAKE_MODULE_PATH"><code class="xref cmake cmake-variable docutils literal notranslate">CMAKE_MODULE_PATH</code></a> when running CMake, and it is common
for CMake projects to append to <a class="reference internal" href="../../variable/CMAKE_MODULE_PATH.html#variable:CMAKE_MODULE_PATH" title="CMAKE_MODULE_PATH"><code class="xref cmake cmake-variable docutils literal notranslate">CMAKE_MODULE_PATH</code></a> to allow use
of local Find module files.</li>
<li>CMake ships <code class="docutils literal notranslate">Find&lt;PackageName&gt;.cmake</code> files for some
<a class="reference internal" href="../../manual/cmake-modules.7.html#manual:cmake-modules(7)" title="cmake-modules(7)"><code class="xref cmake cmake-manual docutils literal notranslate">third party packages</code></a>. These files are a
maintenance burden for CMake, and it is not unusual for these to fall
behind the latest releases of the packages they are associated with.
In general, new Find modules are not added to CMake any more. Projects
should encourage the upstream packages to provide a config file where
possible. If that is unsuccessful, the project should provide its own
Find module for the package.</li>
</ol>
See <a class="reference internal" href="../../manual/cmake-developer.7.html#find-modules">Find Modules</a> for a detailed discussion of how to write a
Find module file.
</section>
<section id="imported-targets">
<h3><a class="toc-backref" href="#id8" role="doc-backlink">Imported Targets</a><a class="headerlink" href="#imported-targets" title="Permalink to this heading">¶</a></h3>
Both config files and Find module files can define <a class="reference internal" href="../../manual/cmake-buildsystem.7.html#imported-targets">Imported Targets</a>.
These will typically have names of the form <code class="docutils literal notranslate">SomePrefix::ThingName</code>.
Where these are available, the project should prefer to use them instead of
any CMake variables that may also be provided. Such targets typically carry
usage requirements and apply things like header search paths, compiler
definitions, etc. automatically to other targets that link to them (e.g. using
<a class="reference internal" href="../../command/target_link_libraries.html#command:target_link_libraries" title="target_link_libraries"><code class="xref cmake cmake-command docutils literal notranslate">target_link_libraries()</code></a>). This is both more robust and more
convenient than trying to apply the same things manually using variables.
Check the documentation for the package or Find module to see what imported
targets it defines, if any.
Imported targets should also encapsulate any configuration-specific paths.
This includes the location of binaries (libraries, executables), compiler
flags, and any other configuration-dependent quantities. Find modules may
be less reliable in providing these details than config files.
A complete example which finds a third party package and uses a library
from it might look like the following:
<div class="highlight-cmake notranslate"><div class="highlight"><pre>cmake_minimum_required(VERSION 3.10)
project(MyExeProject VERSION 1.0.0)

# Make project-provided Find modules available
list(APPEND CMAKE_MODULE_PATH &quot;${CMAKE_CURRENT_SOURCE_DIR}/cmake&quot;)

find_package(SomePackage REQUIRED)
add_executable(MyExe main.cpp)
target_link_libraries(MyExe PRIVATE SomePrefix::LibName)
</pre></div>
</div>
Note that the above call to <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> could be resolved by
a config file or a Find module. It uses only the basic arguments supported
by the <a class="reference internal" href="../../command/find_package.html#basic-signature">Basic Signature</a>. A <code class="docutils literal notranslate">FindSomePackage.cmake</code> file in the
<code class="docutils literal notranslate">${CMAKE_CURRENT_SOURCE_DIR}/cmake</code> directory would allow the
<a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> command to succeed using module mode, for example.
If no such module file is present, the system would be searched for a config
file.
</section>
</section>
<section id="downloading-and-building-from-source-with-fetchcontent">
<h2><a class="toc-backref" href="#id9" role="doc-backlink">Downloading And Building From Source With <code class="docutils literal notranslate">FetchContent</code></a><a class="headerlink" href="#downloading-and-building-from-source-with-fetchcontent" title="Permalink to this heading">¶</a></h2>
Dependencies do not necessarily have to be pre-built in order to use them
with CMake. They can be built from sources as part of the main project.
The <a class="reference internal" href="../../module/FetchContent.html#module:FetchContent" title="FetchContent"><code class="xref cmake cmake-module docutils literal notranslate">FetchContent</code></a> module provides functionality to download
content (typically sources, but can be anything) and add it to the main
project if the dependency also uses CMake. The dependency's sources will
be built along with the rest of the project, just as though the sources were
part of the project's own sources.
The general pattern is that the project should first declare all the
dependencies it wants to use, then ask for them to be made available.
The following demonstrates the principle (see <a class="reference internal" href="../../module/FetchContent.html#fetch-content-examples">Examples</a>
for more):
<div class="highlight-cmake notranslate"><div class="highlight"><pre>include(FetchContent)
FetchContent_Declare(
 googletest
 GIT_REPOSITORY https://github.com/google/googletest.git
 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
)
FetchContent_Declare(
 Catch2
 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
 GIT_TAG 605a34765aa5d5ecbf476b4598a862ada971b0cc # v3.0.1
)
FetchContent_MakeAvailable(googletest Catch2)
</pre></div>
</div>
Various download methods are supported, including downloading and extracting
archives from a URL (a range of archive formats are supported), and a number
of repository formats including Git, Subversion, and Mercurial.
Custom download, update, and patch commands can also be used to support
arbitrary use cases.
When a dependency is added to the project with <a class="reference internal" href="../../module/FetchContent.html#module:FetchContent" title="FetchContent"><code class="xref cmake cmake-module docutils literal notranslate">FetchContent</code></a>, the
project links to the dependency's targets just like any other target from the
project. If the dependency provides namespaced targets of the form
<code class="docutils literal notranslate">SomePrefix::ThingName</code>, the project should link to those rather than to
any non-namespaced targets. See the next section for why this is recommended.
Not all dependencies can be brought into the project this way. Some
dependencies define targets whose names clash with other targets from the
project or other dependencies. Concrete executable and library targets
created by <a class="reference internal" href="../../command/add_executable.html#command:add_executable" title="add_executable"><code class="xref cmake cmake-command docutils literal notranslate">add_executable()</code></a> and <a class="reference internal" href="../../command/add_library.html#command:add_library" title="add_library"><code class="xref cmake cmake-command docutils literal notranslate">add_library()</code></a> are global,
so each one must be unique across the whole build. If a dependency would
add a clashing target name, it cannot be brought directly into the build
with this method.
</section>
<section id="fetchcontent-and-find-package-integration">
<h2><a class="toc-backref" href="#id10" role="doc-backlink"><code class="docutils literal notranslate">FetchContent</code> And <code class="docutils literal notranslate">find_package()</code> Integration</a><a class="headerlink" href="#fetchcontent-and-find-package-integration" title="Permalink to this heading">¶</a></h2>
<div class="versionadded">
New in version 3.24.
</div>
Some dependencies support being added by either <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> or
<a class="reference internal" href="../../module/FetchContent.html#module:FetchContent" title="FetchContent"><code class="xref cmake cmake-module docutils literal notranslate">FetchContent</code></a>. Such dependencies must ensure they define the same
namespaced targets in both installed and built-from-source scenarios.
A consuming project then links to those namespaced targets and can handle
both scenarios transparently, as long as the project does not use anything
else that isn't provided by both methods.
The project can indicate it is happy to accept a dependency by either method
using the <code class="docutils literal notranslate">FIND_PACKAGE_ARGS</code> option to <a class="reference internal" href="../../module/FetchContent.html#command:fetchcontent_declare" title="fetchcontent_declare"><code class="xref cmake cmake-command docutils literal notranslate">FetchContent_Declare()</code></a>.
This allows <a class="reference internal" href="../../module/FetchContent.html#command:fetchcontent_makeavailable" title="fetchcontent_makeavailable"><code class="xref cmake cmake-command docutils literal notranslate">FetchContent_MakeAvailable()</code></a> to try satisfying the
dependency with a call to <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> first, using the arguments
after the <code class="docutils literal notranslate">FIND_PACKAGE_ARGS</code> keyword, if any. If that doesn't find the
dependency, it is built from source as described previously instead.
<div class="highlight-cmake notranslate"><div class="highlight"><pre>include(FetchContent)
FetchContent_Declare(
 googletest
 GIT_REPOSITORY https://github.com/google/googletest.git
 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
 FIND_PACKAGE_ARGS NAMES GTest
)
FetchContent_MakeAvailable(googletest)

add_executable(ThingUnitTest thing_ut.cpp)
target_link_libraries(ThingUnitTest GTest::gtest_main)
</pre></div>
</div>
The above example calls
<a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package(googletest NAMES GTest)</code></a> first.
CMake provides a <a class="reference internal" href="../../module/FindGTest.html#module:FindGTest" title="FindGTest"><code class="xref cmake cmake-module docutils literal notranslate">FindGTest</code></a> module, so if that finds a GTest package
installed somewhere, it will make it available, and the dependency will not be
built from source. If no GTest package is found, it will be built from
source. In either case, the <code class="docutils literal notranslate">GTest::gtest_main</code> target is expected to be
defined, so we link our unit test executable to that target.
High-level control is also available through the
<a class="reference internal" href="../../module/FetchContent.html#variable:FETCHCONTENT_TRY_FIND_PACKAGE_MODE" title="FETCHCONTENT_TRY_FIND_PACKAGE_MODE"><code class="xref cmake cmake-variable docutils literal notranslate">FETCHCONTENT_TRY_FIND_PACKAGE_MODE</code></a> variable. This can be set to
<code class="docutils literal notranslate">NEVER</code> to disable all redirection to <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a>. It can be
set to <code class="docutils literal notranslate">ALWAYS</code> to try <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> even if <code class="docutils literal notranslate">FIND_PACKAGE_ARGS</code>
was not specified (this should be used with caution).
The project might also decide that a particular dependency must be built from
source. This might be needed if a patched or unreleased version of the
dependency is required, or to satisfy some policy that requires all
dependencies to be built from source. The project can enforce this by adding
the <code class="docutils literal notranslate">OVERRIDE_FIND_PACKAGE</code> keyword to <a class="reference internal" href="../../module/FetchContent.html#command:fetchcontent_declare" title="fetchcontent_declare"><code class="xref cmake cmake-command docutils literal notranslate">FetchContent_Declare()</code></a>.
A call to <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> for that dependency will then be redirected
to <a class="reference internal" href="../../module/FetchContent.html#command:fetchcontent_makeavailable" title="fetchcontent_makeavailable"><code class="xref cmake cmake-command docutils literal notranslate">FetchContent_MakeAvailable()</code></a> instead.
<div class="highlight-cmake notranslate"><div class="highlight"><pre>include(FetchContent)
FetchContent_Declare(
 Catch2
 URL https://intranet.mycomp.com/vendored/Catch2_2.13.4_patched.tgz
 URL_HASH MD5=abc123...
 OVERRIDE_FIND_PACKAGE
)

# The following is automatically redirected to FetchContent_MakeAvailable(Catch2)
find_package(Catch2)
</pre></div>
</div>
For more advanced use cases, see the
<a class="reference internal" href="../../variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.html#variable:CMAKE_FIND_PACKAGE_REDIRECTS_DIR" title="CMAKE_FIND_PACKAGE_REDIRECTS_DIR"><code class="xref cmake cmake-variable docutils literal notranslate">CMAKE_FIND_PACKAGE_REDIRECTS_DIR</code></a> variable.
</section>
<section id="dependency-providers">
<h2><a class="toc-backref" href="#id11" role="doc-backlink">Dependency Providers</a><a class="headerlink" href="#dependency-providers" title="Permalink to this heading">¶</a></h2>
<div class="versionadded">
New in version 3.24.
</div>
The preceding section discussed techniques that projects can use to specify
their dependencies. Ideally, the project shouldn't really care where a
dependency comes from, as long as it provides the things it expects (often
just some imported targets). The project says what it needs and may also
specify where to get it from, in the absence of any other details, so that it
can still be built out-of-the-box.
The developer, on the other hand, may be much more interested in controlling
how a dependency is provided to the project. You might want to use a
particular version of a package that you built yourself. You might want
to use a third party package manager. You might want to redirect some
requests to a different URL on a system you control for security or
performance reasons. CMake supports these sort of scenarios through
<a class="reference internal" href="../../command/cmake_language.html#dependency-providers">Dependency Providers</a>.
A dependency provider can be set to intercept <a class="reference internal" href="../../command/find_package.html#command:find_package" title="find_package"><code class="xref cmake cmake-command docutils literal notranslate">find_package()</code></a> and
<a class="reference internal" href="../../module/FetchContent.html#command:fetchcontent_makeavailable" title="fetchcontent_makeavailable"><code class="xref cmake cmake-command docutils literal notranslate">FetchContent_MakeAvailable()</code></a> calls. The provider is given an
opportunity to satisfy such requests before falling back to the built-in
implementation if the provider doesn't fulfill it.
Only one dependency provider can be set, and it can only be set at a very
specific point early in the CMake run.
The <a class="reference internal" href="../../variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.html#variable:CMAKE_PROJECT_TOP_LEVEL_INCLUDES" title="CMAKE_PROJECT_TOP_LEVEL_INCLUDES"><code class="xref cmake cmake-variable docutils literal notranslate">CMAKE_PROJECT_TOP_LEVEL_INCLUDES</code></a> variable lists CMake files
that will be read while processing the first <a class="reference internal" href="../../command/project.html#command:project" title="project"><code class="xref cmake cmake-command docutils literal notranslate">project()</code></a> call (and
only that call). This is the only time a dependency provider may be set.
At most, one single provider is expected to be used throughout the whole
project.
For some scenarios, the user wouldn't need to know the details of how the
dependency provider is set. A third party may provide a file that can be
added to <a class="reference internal" href="../../variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.html#variable:CMAKE_PROJECT_TOP_LEVEL_INCLUDES" title="CMAKE_PROJECT_TOP_LEVEL_INCLUDES"><code class="xref cmake cmake-variable docutils literal notranslate">CMAKE_PROJECT_TOP_LEVEL_INCLUDES</code></a>, which will set up
the dependency provider on the user's behalf. This is the recommended
approach for package managers. The developer can use such a file like so:
<div class="highlight-none notranslate"><div class="highlight"><pre>cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/package_manager/setup.cmake ...
</pre></div>
</div>
For details on how to implement your own custom dependency provider, see the
<a class="reference internal" href="../../command/cmake_language.html#command:cmake_language" title="cmake_language"><code class="xref cmake cmake-command docutils literal notranslate">cmake_language(SET_DEPENDENCY_PROVIDER)</code></a> command.
</section>
</section>

<div class="clearer"></div>
 </div>
 </div>
 </div>
 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 <div class="sphinxsidebarwrapper">
 <div>
 <h3><a href="../../index.html">Table of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#">Using Dependencies Guide</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a></li>
<li><a class="reference internal" href="#using-pre-built-packages-with-find-package">Using Pre-built Packages With <code class="docutils literal notranslate">find_package()</code></a><ul>
<li><a class="reference internal" href="#config-file-packages">Config-file packages</a></li>
<li><a class="reference internal" href="#find-module-files">Find Module Files</a></li>
<li><a class="reference internal" href="#imported-targets">Imported Targets</a></li>
</ul>
</li>
<li><a class="reference internal" href="#downloading-and-building-from-source-with-fetchcontent">Downloading And Building From Source With <code class="docutils literal notranslate">FetchContent</code></a></li>
<li><a class="reference internal" href="#fetchcontent-and-find-package-integration"><code class="docutils literal notranslate">FetchContent</code> And <code class="docutils literal notranslate">find_package()</code> Integration</a></li>
<li><a class="reference internal" href="#dependency-providers">Dependency Providers</a></li>
</ul>
</li>
</ul>

</div>
 <div>
 <h4>Previous topic</h4>
 <a href="../user-interaction/index.html"
 title="previous chapter">User Interaction Guide</a>
 </div>
 <div>
 <h4>Next topic</h4>
 <a href="../importing-exporting/index.html"
 title="next chapter">Importing and Exporting Guide</a>
 </div>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../../_sources/guide/using-dependencies/index.rst.txt"
 rel="nofollow">Show Source</a></li>
 </ul>
 </div>
<div id="searchbox" style="display: none" role="search">
 <h3 id="searchlabel">Quick search</h3>
 <div class="searchformwrapper">
 <form class="search" action="../../search.html" method="get">
 <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
 <input type="submit" value="Go" />
 </form>
 </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
 </div>
 </div>
 <div class="clearer"></div>
 </div>
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../../genindex.html" title="General Index"
 >index</a></li>
 <li class="right" >
 <a href="../importing-exporting/index.html" title="Importing and Exporting Guide"
 >next</a> |</li>
 <li class="right" >
 <a href="../user-interaction/index.html" title="User Interaction Guide"
 >previous</a> |</li>
 <li>
 <img src="../../_static/cmake-logo-16.png" alt=""
 style="vertical-align: middle; margin-top: -2px" />
 </li>
 <li>
 <a href="https://cmake.org/">CMake</a> &#187;
 </li>
 <li>
 <a href="../../index.html">3.26.3 Documentation</a> &#187;
 </li>

<li class="nav-item nav-item-this"><a href="">Using Dependencies Guide</a></li> 
 </ul>
 </div>

<div class="footer" role="contentinfo">
 &#169; Copyright 2000-2023 Kitware, Inc. and Contributors.
 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.0.2.
 </div>
 </body>
</html>