【学习笔记】Mastering CMake （十）—— 查找包

已于 2024-10-27 12:03:24 修改
阅读量1.1k 收藏 12
点赞数 25
分类专栏： CMake 学习 文章标签： 学习 笔记
于 2024-10-27 11:44:57 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/cxsydzn/article/details/143266350
版权

前言：

学习笔记，随时更新。如有谬误，欢迎指正。

说明：

  1. 红色字体为较为重要部分。
  2. 绿色字体为个人理解部分。

10 查找包

许多软件项目提供工具和库作为其他项目和应用程序的构建模块。依赖外部包的 CMake 项目使用 find_package 命令来定位它们的依赖。典型的调用是这样的形式：

find_package(<Package> [version])

<package> 是要被查找的包的名称， [version] 是一个可选的版本要求（以 major[.minor.[patch]] 的形式）。一个包的命令的概念与 CPack 的命令的概念截然不同，它意味着创建源代码和二进制发行版以及安装器。

该命令有两种工作模式： Module 模式和 Config 模式。在 Module 模式中，该命令搜索一个查找模块：一个名为 Find<Package>.cmake 的文件。它首先在 CMAKE_MODULE_PATH 中查找，然后在 CMake 安装（目录）中查找。如果找到了查找模块，则加载它来搜索包的各个组件。查找模块包含特定于包的它们期望查找的库和其他文件的知识，并且在内部使用 find_library 之类的命令来定位它们。 CMake 为许多常用包提供查找模块。详见 cmake-modules 手册。

find_package 的 Config 模式通过与要查找的包的合作提供了一个强大的替代方案。在定位查找模块失败或调用者显式请求时，它将进入此模式。在 Config 模式下，该命令搜索一个包配置文件：一个名为 <Package>Config.camke 或 <package>-config.camke 的文件，该文件由要找的包提供的。给定一个包的名称， find_package 命令知道如何深入搜索安装前缀中的位置，比如：

<prefix>/lib/<package>/<package>-config.cmake

（有关位置的完整列表，请参阅 find_package 命令的文档）。 CMake 创建一个名为 <Package>_DIR 的缓存项来存储找到的位置或允许用户设置它。由于包配置文件附带其包的安装，它确切地知道在哪里可以找到安装所提供的所有内容。一旦 find_package 命令定位到文件，它将提供包组件的位置，而不需要进行任何额外的搜索。

[version] 选项要求 find_package 查找包的特定版本。在 Module 模式中，该命令将请求传递给查找模块。在 Config 模式下，该命令查看每个候选包配置文件旁边的包版本文件：一个名为 <Package>ConfigVersion.cmake 或 <package>-config-<version>.cmake 的文件。加载版本文件以测试包版本是否与请求的版本相匹配(有关版本文件 API 规范，请参阅 find_package 的文档)。如果版本文件声明兼容性，则接受配置文件，否则将忽略配置文件。这种方法允许每个项目为版本兼容性定义自己的规则。

10.1 内置查找模块

CMake 有许多预定义的模块，可以在 CMake 的 Modules 子目录中找到。这些模块可以找到许多常用的软件包。详细列表请参见 cmake-modules 手册 。

每个 Find<XX>.cmake 模块定义了一组变量，允许项目在找到软件包后使用该软件包。这些变量都以所找到的软件的名称 <XX> 开头。在 CMake 中，我们试图建立一个命名这些变量的约定，但是你应该阅读模块顶部的注释以获得更明确的答案。以下变量在需要时按照约定使用：

<XX>_INCLUDE_DIRS

  • 在哪里找到包的头文件，通常是 <XX>.h 等。

<XX>_LIBRARIES

  • 使用 <XX>要链接的库 。这包括完整路径。

<XX>_DEFINITIONS

  • 当编译使用 <XX> 的代码时要使用的预处理器定义。

<XX>_EXECUTABLE

  • 在哪里可以找到作为包一部分的 <XX> 工具。

<XX>_<YY>_EXECUTABLE

  • 哪里可以找到 <XX> 自带的 <YY> 工具。

<XX>_ROOT_DIR

  • 在哪里可以找到 <XX> 安装基础目录。这对于大型包非常有用，其中你可能希望引用许多相对于公共基础（或根）目录的文件。

<XX>VERSION<YY>

  • 如果为 true ，表明查找到包的 <YY> 版本。查找模块的作者应该确保其中最多有一个是正确的。例如 TCL_VERSION_84 。

<XX>_<YY>_FOUND

  • 如果为 false ，则包 <XX> 的可选部分 <YY> 不可用。

<XX>_FOUND

  • 如果我们没有找到或不想使用 <XX> ，则设置为 false 或未定义。

并非所有变量都出现在每个 FindXX.cmake 文件。但是， <XX>_FOUND 在大多数情况下都应该存在。如果 <XX> 是一个库，那么还应该定义 <XX>_LIBRARIES ，并且通常也应该定义 <XX>_INCLUDE_DIR 。

可以使用 include 命令或 find_package 命令将模块包含到项目中。

find_package(OpenGL)

include(${CMAKE_ROOT}/Modules/FindOpenGL.cmake)

include(FindOpenGL)

上述三者是等价的。

如果项目转换为其构建系统的 CMake ，如果包提供 <XX>Config.cmake 文件，则 find_package 仍将工作。如何创建 CMake 包将在后面章节介绍。

10.2 创建 CMake 包配置文件

项目必须提供包配置文件，以便外部应用程序能够找到它们。考虑一个简单的项目“ Gromit ”，它提供一个可执行文件来生成源代码和一个库，生成的代码必须链接到这个库。 CMakeLists.txt 文件可以这样开始：

cmake_minimum_required(VERSION 3.20)
project(Gromit C)
set(version 1.0)

# 创建库和可执行文件
add_library(gromit STATIC gromit.c gromit.h)
add_executable(gromit-gen gromit-gen.c)

为了安装 Gromit 并导出它的目标以供外部项目使用，添加以下代码：

# 安装并导出目标
install(FILES gromit.h DESTINATION include/gromit-${version})
install(TARGETS gromit gromit-gen
        DESTINATION lib/gromit-${version}
        EXPORT gromit-targets)
install(EXPORT gromit-targets
        DESTINATION lib/gromit-${version})

最后， Gromit 必须在它的安装树中提供一个包配置文件，以便外部项目可以通过 find_package 找到它：

# 创建并安装包配置文件和版本文件
configure_file(
   ${Gromit_SOURCE_DIR}/pkg/gromit-config.cmake.in
   ${Gromit_BINARY_DIR}/pkg/gromit-config.cmake @ONLY)

configure_file(
   ${Gromit_SOURCE_DIR}/gromit-config-version.cmake.in
   ${Gromit_BINARY_DIR}/gromit-config-version.cmake @ONLY)

install(FILES ${Gromit_BINARY_DIR}/pkg/gromit-config.cmake
         ${Gromit_BINARY_DIR}/gromit-config-version.cmake
         DESTINATION lib/gromit-${version})

这段代码配置和安装包配置文件和相应的包版本文件。包配置输入文件 gromit-config.cmake.in 中有代码：

# 计算相对于此文件的安装前缀
get_filename_component(_dir "${CMAKE_CURRENT_LIST_FILE}" PATH)
get_filename_component(_prefix "${_dir}/../.." ABSOLUTE)

# 导入目标
include("${_prefix}/lib/gromit-@version@/gromit-targets.cmake")

# 输出其他信息
set(gromit_INCLUDE_DIRS "${_prefix}/include/gromit-@version@")

安装完成后，配置的包配置文件 gromit-config.cmake 知道其他已安装文件相对于自己的位置。从它的输入文件 gromit-config-version.cmake.in 配置相应的包版本文件，其中包含如下代码：

set(PACKAGE_VERSION "@version@")
if(NOT "${PACKAGE_FIND_VERSION}" VERSION_GREATER "@version@")
  set(PACKAGE_VERSION_COMPATIBLE 1) # 兼容旧版本
  if("${PACKAGE_FIND_VERSION}" VERSION_EQUAL "@version@")
    set(PACKAGE_VERSION_EXACT 1) # 正好匹配此版本
  endif()
endif()

使用 Gromit 包的应用程序可能会创建一个类似这样的 CMake 文件：

cmake_minimum_required(VERSION 3.20)
project(MyProject C)

find_package(gromit 1.0 REQUIRED)
include_directories(${gromit_INCLUDE_DIRS})
# 运行导入的可执行文件
add_custom_command(OUTPUT generated.c
                   COMMAND gromit-gen generated.c)
add_executable(myexe generated.c)
target_link_libraries(myexe gromit) # 链接导入的库

对 find_package 的调用会定位 Gromit 的安装，如果没有找到则终止并显示错误消息（由于 REQUIRED ）。命令执行成功后， Gromit 包配置文件 gromit-config.cmake 已经加载，因此已经导入 Gromit 目标，并定义了 gromit_INCLUDE_DIRS 等变量。

上面的示例创建一个包配置文件，并将其放在 install 树中。还可以在 build 树中创建包配置文件，以允许应用程序在不安装的情况下使用项目。为了做到这一点，我们扩展 Gromit 的 CMake 文件，代码如下：

# 使项目从构建树中可用
export(TARGETS gromit gromit-gen FILE gromit-targets.cmake)
configure_file(${Gromit_SOURCE_DIR}/gromit-config.cmake.in
               ${Gromit_BINARY_DIR}/gromit-config.cmake @ONLY)

这个 configure_file 调用使用了一个不同的输入文件， gromit-config.cmake.in 包含:

# 导入目标
include("@Gromit_BINARY_DIR@/gromit-targets.cmake")

# 输出其他信息
set(gromit_INCLUDE_DIRS "@Gromit_SOURCE_DIR@")

包配置文件 gromit-config.cmake 位于构建树中，向外部项目提供与安装树中相同的信息，但指向源文件和构建树中的文件。它共享一个相同的包版本文件 gromit-config-version.cmake ，它位于安装树中。

10.3 CMake 包注册表

CMake 提供了两个主要位置来注册已经在系统上构建或安装的包：一个用户包注册表和一个系统包注册表。 find_package 命令搜索两个包注册表，作为其文档中指定的两个搜索步骤。注册表对于帮助项目在非标准安装位置或直接在包构建树中查找包特别有用。项目可以填充用户或系统注册表（使用自己的方法）来引指向其位置。在任何一种情况下，包都应该在注册位置存储一个包配置文件和本章前面提到的可选的包版本文件。

用户包注册表存储在特定于平台的每个用户位置。在 Windows 上，它存储在 Windows 注册表中的 HKEY_CURRENT_USER 键下。 <package> 可能作为 REG_SZ 值出现在注册表项

HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>

下，该值可以具有任意名称（即其 key 可以是任意的），指定包含包配置文件的目录。在 UNIX 平台上，用户包注册表存储在 ~/.cmake/packages 下的用户主目录中。 <package> 可能出现在

~/.cmake/packages/<package>

目录下，是一个任意名称的文件，其内容指定包含包配置文件的目录。可以使用 export(PACKAGE) 命令在用户包注册表中注册一个项目构建树。 CMake 目前没有提供将安装树添加到用户包注册表的接口，如果需要，必须由安装程序自己来注册他们的软件包。

系统包注册表存储在特定于平台的、系统级别的位置。在 Windows 上，它存储在 Windows 注册表中的 HKEY_LOCAL_MACHINE 键下。 <package> 可能作为 REG_SZ 值出现在注册表项

HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>

下，该值可以具有任意名称（即其 key 可以是任意的），指定包含包配置文件的目录。在非 Windows 平台上没有系统包注册表。 CMake 不提供添加到系统包注册表的接口。如果需要，必须由安装程序自己来注册他们的软件包。

包注册表项由它们所指向的项目安装单独拥有。包安装程序负责添加自己的项，相应的卸载程序负责删除它。但是，为了保持注册表干净，如果 find_package 命令有足够的权限，它会自动删除遇到的过时的包注册表项。如果项指向的目录不存在或不包含匹配的包配置文件，则该项被认为是过时的。这对于由 export(PACKAGE) 命令为构建树创建的用户包注册表项特别有用，这些构建树没有卸载事件，开发人员可以简单地删除它们。

包注册表项可以是任意名称。命名它们的一个简单约定是使用内容哈希，因为它们是确定性的，不太可能发生冲突。 export(PACKAGE) 命令使用这种方法。指向特定目录的项的名称只是目录路径本身的内容散列。例如，项目可以创建包注册表项，例如在 Window 上

> reg query HKCU\Software\Kitware\CMake\Packages\MyPackage
HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\MyPackage
 45e7d55f13b87179bb12f907c8de6fc4
                          REG_SZ    c:/Users/Me/Work/lib/cmake/MyPackage
 7b4a9844f681c80ce93190d4e3185db9
                          REG_SZ    c:/Users/Me/Work/MyPackage-build

或者在 Unix 上

$ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd
/home/me/work/lib/cmake/MyPackage
$ cat ~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07
/home/me/work/MyPackage-build

find_package(MyPackage) 命令将搜索包配置文件的注册位置。单个包的包注册表项之间的搜索顺序未指定。注册位置可能包含包版本文件，以告诉 find_package 特定位置（的文件）是否适合请求的版本。

CMake介绍（七）--CMake 查找库和包
MHD0815的博客
09-21 1117
CMake 提供了多种命令来查找库和包，包括find_path和find_file。合理使用这些命令可以帮助你在 CMake 项目中有效地管理依赖关系和外部资源。通过上述示例，你可以了解到如何使用 CMake 来查找和引用外部库和包，并在构建过程中正确地使用它们。
CMakeLists学习一、find_package查找包
qq_41035283的博客
01-13 1万+
CMakeLists学习一、find_package查找包前言引例环境变量find_package查询路径设定查询路径默认路径链接库问题find_package()命令 前言 很久之前就想写关于CMakeLists相关的学习记录，但当时的重点在数学基础内容上，这一块就搁置了，现在重新记录一下。 首先就是cmake中查找第三方包指令find_package()的原理 引例 图像相关的工程中，最常用的第三方包OpenCV需要通过CMakeLists来配置，常见写法如下： find_package(OpenCV
CMakeLists中find_package()的原理，多版本依赖并存方法
最新发布
DDS_____的博客
03-14 751
有时候会遇到明明安装了某个库，但是find_package()找不到的情况，这里总结一下find_package 的基本流程和自定义搜索的方法。也经常遇到两个C++项目依赖存在冲突的情况，除了用docker外，还可以手动定义依赖的安装路径，避免冲突。
find_package深度解析及实例应用
qq_39466755的博客
05-28 2442
默认情况下，包括两个端点。如果传递了NO_PACKAGE_ROOT_PATH，或者将CMAKE_FIND_USE_PACKAGE_ROOT_PATH设置为FALSE，则可以跳过此操作。/*/(lib/|lib*|share)/cmake/*/就表示可能在/lib/cmake/或者/lib*/cmake/或者/share/cmake/目录下.可以通过NO_CMAKE_PATH选项或将CMAKE_FIND_USE_CMAKE_PATH设置为FALSE来跳过。
cmakelists中确定find_package()库的名字
weixin_51021488的博客
05-29 448
cmakelists
CMake: find_package
吕爽
09-21 2167
CMake: find_package基本标志与模块模式全部标志与配置模式版本选择查找过程包文件接口变量参考 ***查找外部项目， 并记载它的设置。 *** 基本标志与模块模式 find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] [REQUIRED] [[COMPONENTS] [components...]] [OPTIONAL_COMPONENTS components
mastering cmake - 高清完整带书签 Cmake PDF 权威学习CMake参考手册
05-14
"Mastering CMake"这本书是CMake学习者的权威指南，旨在帮助读者深入理解和熟练运用CMake来构建复杂项目。 **CMake基础** CMake使用简单的语句（称为CMakeLists.txt文件）来定义项目结构、依赖关系和构建选项。...
mastering cmake.pdf
10-12
《Mastering CMake》这本书是CMake学习者的宝贵资源，它深入探讨了CMake这一跨平台构建系统的高级用法和技巧。CMake是一种用于管理软件构建过程的开源工具，能够生成针对不同编译器和操作系统的目标项目文件。下面将...
Mastering Cmake书籍英文文字版, 可以复制,做笔记
08-31
Mastering Cmake书籍英文文字版, 可以复制,做笔记. 支持文字搜索,便于查找内容. CMake is an open source build manager for software projects that allows developers to specify build parameters in a simple ...
mastering cmake.zip
06-15
《Mastering CMake》这本书是CMake工具的权威指南，它旨在帮助开发者深入理解和熟练运用CMake来简化项目的构建流程。 CMake的基本概念包括CMakeLists.txt文件，这是每个CMake项目的核心，它包含了构建过程的指令和...
mastering cmake
12-11
总之，《Mastering CMake》是学习CMake不可或缺的资源，无论你是初学者还是经验丰富的开发者，都能从中受益匪浅，提升你的构建系统管理和项目开发能力。通过深入学习和实践，你将能够更高效地利用CMake简化项目构建...
cmake(7)：find_package命令详解
翔底的博客
10-20 1万+
1. 说明 cmake的find_package命令对于构建软件提供了极大的便利，虽然知道怎么使用已经能解决大部分问题，但是cmake支持哪些包？为什么它能找到需要的包？如果是自己编写的库，需要如何做才能使用该命令进行构建等原理性问题却始终困扰着我。 这篇文章参考cmake官方文档和网上前辈的文章记录自己对find_package命令的学习和分析。 1.1 cmake支持哪些包 理论上只要符合find_package命令的查找条件，能让该命令识别的包或者库都会被支持。在实际使用时，我们可以把这些包分成三类：
CMakeLists.txt ----find_package
人面不知何处去
04-24 6690
在linux平台下编译程序的时候通常都会使用到CMakeLists.txt来制定编译规则, 在查找需要链接的lib时候, 通常会使用到find_package, 记录一下我之前用到的地方. find_package 之后, 最好到FindXXX.cmake中看一下,这个库是怎样使用的. 如果没有特殊指定这个文件的路径, 路径通常是"/usr/share/cmake-XXX/Modules/Fi...
CMakeLists.txt：打印find_package变量；判断库文件路径设定是否正确；install文件设置
qq_41035283的博客
11-23 2603
安装目标文件：通过TARGETS关键字指定要安装的目标文件，并通过DESTINATION关键字指定目标文件的安装路径。这样，当我们使用make install命令时，构建生成的myapp可执行文件将被安装到bin目录下，myheader.h头文件将被安装到include目录下，而mydir目录及其下的文件将被安装到share/myapp目录下。在上面的示例中，install()命令指定了要安装的目标（即${EXECUTABLE_NAME}）和目标的安装路径（即/usr/local/bin）。
find_package与CMake如何查找链接库详解
热门推荐
bytxl的专栏
02-05 7万+
如果编译软件使用了外部库，事先并不知道它的头文件和链接库的位置。得在编译命令中加上包含它们的查找路径。CMake使用 find_package 命令来解决这个问题。本文讨论了如何在CMake项目中使用外部库，以及如何给没有查找模块的库写一个。 1 使用外部库 为了能支持各种常见的库和包，CMake自带了很多模块。可以通过命令 cmake --help-module-list （输入cm
Cmake之深入理解find_package()的用法
木牛的博客
01-24 73
刚刚接触Cmake的时候，对于find_package的用法以及背后的原理经常一头雾水，官方文档比较晦涩难懂，网上的博客也都讲解的比较片面。这里通过实战代码案例进行一下详细的总结讲解。帮助自己加深理解的同时，也希望帮到更多的初学者。此处所有代码均可在我的github项目中找到，欢迎star。后续内容我也会持续更新。话不多说进入正题。
“轻松搞定CMake”系列之find_package用法详解
木牛的博客
01-23 250
在我们实际开发过程中，经常不可避免会使用到第三方开源库，这些开源库可能是通过命令自动安装到系统目录中，也可能是由我们自己下载库的源码然后通过编译安装到指令目录下的。不管哪种方式安装的库文件，如果我们需要自己的项目中使用这些库，首先面临的第一个问题就是如何找到这些库。所谓“找到”这些库，其实是根据我们的需要找到指定版本的库头文件包含路径、链接库路径等，从而能够满足我们开发项目的编译链接需要。在没有CMake的时代，这种库查找链接的工作都需要借助MakeFile。
cmake 使用find_package, 增加查找路径（ CMAKE_PREFIX_PATH）
百冰千岚的博客
11-13 1035
cmake 使用 find_package
CMake中find_package的使用
网络资源是无限的
10-23 1万+
CMake中find_package的使用
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值