当前位置： 首页 > news >正文

CMake与catkin_make的find_package()命令使用说明

news 2025/7/22 10:02:43

在 CMake 中，find_package() 是一个核心函数，用于查找并加载外部依赖库的配置。它的主要作用是定位头文件、库文件，并设置相关变量，以便后续编译和链接。以下是详细解析：

1. 基本语法

find_package(<PackageName> [version] [REQUIRED] [COMPONENTS components...] [OPTIONAL_COMPONENTS components...] [NO_MODULE] [QUIET] [CONFIG])
  • <PackageName>：要查找的包名（如 Boost、Eigen3）。
  • version：可选，指定最低版本（如 3.3）。
  • REQUIRED：可选，如果找不到包，则报错并终止构建。
  • COMPONENTS：指定包的子组件（如 Boost 的 system、filesystem）。
  • NO_MODULE：跳过模块模式，直接使用配置模式（Config Mode）。
  • QUIET：静默模式，不输出警告信息。

find_package() 中的 REQUIRED 是可选的。如果不指定 REQUIRED，CMake 会尝试查找包，但即使找不到也不会报错，而是继续执行后续的 CMake 脚本。此时，你需要通过检查 <PackageName>_FOUND 变量来判断是否成功找到该包，并决定后续逻辑。

1.1 REQUIRED关键字

1.1.1 没有REQUIRED关键字的情况
find_package(<PackageName> [version] [COMPONENTS components...])
  • 如果找到包，CMake 会设置 <PackageName>_FOUND=TRUE 和相关变量（如 _INCLUDE_DIRS、_LIBRARIES）。
  • 如果未找到包，<PackageName>_FOUND=FALSE，但不会中断构建。
1.1.2 典型场景
1.1.2.1 可选依赖库

某些库可能是可选的（例如，用于增强功能但不影响核心功能）：

find_package(OpenCV)  # 不强制要求 OpenCVif(OpenCV_FOUND)message(STATUS "OpenCV found, enabling advanced features")add_definitions(-DUSE_OPENCV)target_link_libraries(my_app PRIVATE ${OpenCV_LIBRARIES})
else()message(WARNING "OpenCV not found, some features will be disabled")
endif()
1.1.2.2 多版本兼容

尝试查找高版本库，失败时回退到低版本或默认路径：

find_package(Python 3.8)  # 首选 Python 3.8
if(NOT Python_FOUND)find_package(Python 3.6)  # 回退到 Python 3.6
endif()
1.1.2.3 平台特定依赖

某些库仅在特定平台需要（如 Linux 的 libudev）：

if(UNIX AND NOT APPLE)find_package(UDEV)  # 仅在 Linux 下查找if(UDEV_FOUND)target_link_libraries(my_app PRIVATE udev)endif()
endif()
1.1.2.4 关键注意事项

1.1.2.4.1 必须检查 _FOUND 变量
如果不检查，后续使用未找到的库会导致编译或链接错误：

find_package(CURL)
# 错误：直接使用 ${CURL_LIBRARIES} 而不检查 CURL_FOUND

1.1.2.4.2 与 REQUIRED 的对比

行为REQUIRED 模式非 REQUIRED 模式
找不到包时报错并终止 CMake 配置继续执行，<PackageName>_FOUND=FALSE
适用场景核心依赖（如 ROS、Eigen）可选功能或平台特定依赖
代码复杂度无需额外判断需手动检查 _FOUND 变量

1.1.2.4.3 组件（COMPONENTS）的非必需性
即使包支持组件，也可以不标记 REQUIRED：

find_package(Boost COMPONENTS system)
if(Boost_FOUND AND Boost_SYSTEM_FOUND)target_link_libraries(my_app PRIVATE Boost::system)
endif()
1.1.3 实际案例
1.1.3.1 ROS 中的可选消息依赖
find_package(catkin COMPONENTSroscppsensor_msgs  # 可选依赖
)if(catkin_FOUND AND sensor_msgs_FOUND)add_definitions(-DUSE_SENSOR_MSGS)
endif()
1.1.3.2 多图形后端支持
find_package(OpenGL)
find_package(Vulkan)if(OpenGL_FOUND)target_link_libraries(my_engine PRIVATE OpenGL::GL)
elseif(Vulkan_FOUND)target_link_libraries(my_engine PRIVATE Vulkan::Vulkan)
else()message(FATAL_ERROR "No supported graphics API found!")
endif()

1.2 COMPONENTS：指定子组件

1.2.1 作用
  • 用于声明需要查找的包的子模块或组件（例如 Boost 的 system、filesystem，或 ROS 的 roscpp、tf）。
  • 如果某个组件未找到，且标记了 REQUIRED，CMake 会报错。
1.2.2 示例
find_package(Boost REQUIRED COMPONENTS system filesystem)
  • 查找 Boost 库，并明确要求 system 和 filesystem 两个组件。
  • 成功后，变量 Boost_SYSTEM_FOUND 和 Boost_FILESYSTEM_FOUND 会被设为 TRUE。
1.2.3 关键点
  • 需要包本身支持组件化（如 Boost、Qt、ROS）。
  • 每个组件可能有独立的变量（如 Boost_SYSTEM_LIBRARY）。

1.3 NO_MODULE：强制跳过模块模式

1.3.1 作用
  • 强制 CMake 跳过传统的 Find<Package>.cmake 模块模式，直接使用包的现代配置模式（即查找 <Package>Config.cmake 文件）。
  • 适用于明确知道包提供了 Config.cmake 文件的情况（如 Eigen3、现代 Qt）。
1.3.2 示例
find_package(Eigen3 3.3 REQUIRED NO_MODULE)
  • 跳过 FindEigen3.cmake，直接查找 Eigen3Config.cmake。
  • 避免因旧版模块文件与新版本库不兼容导致的问题。
1.3.3 关键点
  • 通常用于现代 CMake 兼容的库（如 Eigen3、VTK）。
  • 如果包没有提供 Config.cmake 文件，使用 NO_MODULE 会导致查找失败。
1.3.4 COMPONENTS与NO_MODULE两者关系总结
特性COMPONENTSNO_MODULE
用途指定包的子组件强制使用配置模式（跳过模块模式）
依赖包的支持包需支持组件化（如 Boost、Qt）包需提供 Config.cmake 文件
典型场景find_package(Boost COMPONENTS system)find_package(Eigen3 NO_MODULE)
是否互斥可与 NO_MODULE 同时使用可与 COMPONENTS 同时使用
1.3.5 同时使用的例子
find_package(Qt6 REQUIRED COMPONENTS Core Gui NO_MODULE)
  • 强制使用 Qt6Config.cmake（跳过 FindQt6.cmake），并指定需要 Core 和 Gui 组件。
1.3.6 为什么有些包需要同时用 COMPONENTS 和 NO_MODULE？
  • 例如 Qt6 既提供了 Config.cmake 文件，又将功能拆分为多个组件（Core、Gui、Widgets 等）。此时：
    find_package(Qt6 REQUIRED COMPONENTS Core NO_MODULE)
    • NO_MODULE：确保使用 Qt6Config.cmake（现代方式）。
    • COMPONENTS：明确要求 Core 组件。
1.3.7 如果包不支持组件，但用了 COMPONENTS 会怎样？
  • CMake 会报错，例如：
    find_package(Eigen3 COMPONENTS Core)  # Eigen3 无组件，会报错
    错误信息类似：
    Could not find a configuration file for package "Eigen3" that specifies component "Core".
1.3.8 如何知道一个包是否支持组件？
  • 查看官方文档或包的 Config.cmake 文件。
  • 例如 Boost 的组件列表见：Boost Libraries。
1.3.9 对比示例
案例 1：仅用 COMPONENTS
find_package(Boost REQUIRED COMPONENTS system)
  • 查找 Boost 的 system 组件，使用默认的模块模式（FindBoost.cmake）。
案例 2：仅用 NO_MODULE
find_package(Eigen3 NO_MODULE)
  • 跳过 FindEigen3.cmake，直接查找 Eigen3Config.cmake。
案例 3：同时使用
find_package(Qt5 COMPONENTS Widgets NO_MODULE)
  • 强制使用 Qt5Config.cmake，并指定 Widgets 组件。
1.3.10 总结
  • COMPONENTS：用于指定包的子模块，与包的功能拆分相关。
  • NO_MODULE：用于控制查找模式，与包的配置方式相关。
  • 两者可独立或组合使用，具体取决于包的支持情况。

2. 工作模式

find_package 有两种查找模式：

(1) 模块模式（Module Mode）

  • 查找 <PackageName>Config.cmake 或 Find<PackageName>.cmake 文件。
  • 通常用于传统库（如 FindBoost.cmake）。
  • 优先级低于配置模式。

(2) 配置模式（Config Mode）

  • 查找 <PackageName>Config.cmake 文件（通常由库的开发者提供）。
  • 现代库（如 Eigen3、Qt5）优先使用此模式。
  • 通过 NO_MODULE 强制启用。

3. 关键变量

成功调用 find_package 后，CMake 会设置以下变量（以 Eigen3 为例）：

变量名作用示例值
<PackageName>_FOUND是否找到包Eigen3_FOUND = TRUE
<PackageName>_INCLUDE_DIR头文件目录Eigen3_INCLUDE_DIRS = /usr/include/eigen3
<PackageName>_LIBRARIES库文件路径Boost_LIBRARIES = /usr/lib/libboost_system.so
<PackageName>_VERSION版本号Eigen3_VERSION = 3.4.0

4. 具体示例解析

(1) ROS 的 catkin 包

find_package(catkin REQUIRED COMPONENTSroscpp tf
)
  • 作用：查找 ROS 的 catkin 构建系统，并加载 roscpp 和 tf 的依赖。
  • 生成的变量：
    • catkin_INCLUDE_DIRS：ROS 包的头文件路径。
    • catkin_LIBRARIES：ROS 包的库文件路径。
  • 后续用法：
    include_directories(${catkin_INCLUDE_DIRS})
target_link_libraries(my_node ${catkin_LIBRARIES})

(2) Boost 库

find_package(Boost REQUIRED COMPONENTSsystem filesystem
)
  • 作用：查找 Boost 库，并指定需要 system 和 filesystem 组件。
  • 生成的变量：
    • Boost_INCLUDE_DIRS：Boost 头文件路径（如 /usr/include）。
    • Boost_LIBRARIES：组件库路径（如 boost_system、boost_filesystem）。
  • 后续用法：
    target_include_directories(my_app PRIVATE ${Boost_INCLUDE_DIRS})
target_link_libraries(my_app ${Boost_LIBRARIES})

(3) Eigen3 线性代数库

find_package(Eigen3 3.3 REQUIRED NO_MODULE)
  • 作用：查找 Eigen3 库，要求版本 ≥ 3.3，并强制使用配置模式（NO_MODULE）。
  • 生成的变量：
    • Eigen3_INCLUDE_DIRS：Eigen 头文件路径（如 /usr/include/eigen3）。
    • Eigen3_VERSION：版本号。
  • 后续用法：
    target_include_directories(my_app PRIVATE ${Eigen3_INCLUDE_DIRS})

(4) PkgConfig 工具

find_package(PkgConfig REQUIRED)
  • 作用：启用 pkg-config 支持（用于查找没有 CMake 配置文件的库）。
  • 后续用法：
    pkg_search_module(GLIB REQUIRED glib-2.0)
include_directories(${GLIB_INCLUDE_DIRS})
target_link_libraries(my_app ${GLIB_LIBRARIES})

5. 常见问题

(1) 为什么有些包需要 NO_MODULE？

  • 例如 Eigen3 只有 Eigen3Config.cmake，没有 FindEigen3.cmake，因此需强制使用配置模式。

(2) REQUIRED 的作用是什么？

  • 如果找不到包，CMake 会报错并停止构建。避免后续链接时出现未定义错误。

(3) 可以没有REQUIRED关键字吗

  • 是的，

5. 调试技巧

  • 查看查找结果：
    find_package(Foo)
message(STATUS "Foo_FOUND = ${Foo_FOUND}, Foo_INCLUDE_DIRS = ${Foo_INCLUDE_DIRS}")
  • 手动指定路径（用于调试）：
    set(Foo_DIR "/path/to/FooConfig.cmake")  # 提示 CMake 查找路径

总结

  • **省略 REQUIRED** 时，find_package()变为“尝试查找”，需配合_FOUND` 变量使用。
  • 适用场景：可选功能、多版本回退、平台特定依赖。
  • 优势：灵活控制构建流程，避免因非核心依赖缺失导致构建失败。

(4) 如何调试 find_package 失败？

  • 检查路径是否在 CMAKE_PREFIX_PATH 中：
    message(STATUS "CMAKE_PREFIX_PATH = ${CMAKE_PREFIX_PATH}")
  • 手动指定路径：
    set(Eigen3_DIR "/path/to/eigen3/share/eigen3/cmake")

6. 总结

场景示例命令关键变量
ROS 包依赖find_package(catkin REQUIRED COMPONENTS roscpp)catkin_INCLUDE_DIRS
Boost 组件find_package(Boost REQUIRED COMPONENTS system)Boost_LIBRARIES
强制配置模式find_package(Eigen3 NO_MODULE)Eigen3_INCLUDE_DIRS
使用 pkg-configfind_package(PkgConfig)PKG_CONFIG_FOUND

通过 find_package，CMake 可以灵活地集成第三方库，而 ROS 的 catkin 进一步扩展了这一机制，使其支持 ROS 特有的依赖管理。

http://www.dtcms.com/a/291031.html

相关文章：

  • 《使用Qt Quick从零构建AI螺丝瑕疵检测系统》——1. 启航：你的第一个工业视觉应用
  • C/C++ 详谈结构体大小计算(内存对齐)
  • 基于 HAProxy 搭建 EMQ X 集群
  • vscode创建vue项目报错
  • 如何判断自己的电脑或主机是否支持DDR5内存?
  • Android 默认图库播放视频没有自动循环功能，如何添加2
  • MVC模式
  • vcruntime140_1.dll文件丢失？终极修复指南：从错误分析到修复全流程
  • Ubuntu 22.04 使用 Docker 安装 Redis 5 （安装包形式）
  • linux定时器使用
  • AD域控制器虚拟化的安全加固最佳实践
  • 从IR到DS的转化过程中，如何确保各阶段需求不偏离用户原始场景？有哪些验证方法？
  • 吴恩达 机器学习cs229-学习笔记-更新中
  • 动静态库原理与实战详解
  • Linux 721 创建实现镜像的逻辑卷
  • 网站域名备案和服务器有关系吗
  • 《电⼦元器件零基础⼊⻔》
  • 汽车售后诊断仪DoIP和CANBus诊断指令分析
  • Linux的磁盘存储管理实操——（中）——逻辑卷管理实战
  • Ubuntu 22.04编译安装Nginx 1.28
  • Docker实践：使用Docker部署blog轻量级博客系统
  • 我的NAS进化史：用1Panel和内网穿透把零配件变成远程中枢
  • 超详细解析：Java装箱与拆箱（附完整数据类型清单）
  • 在 HTTP GET 请求中传递参数有两种标准方式
  • 【Java】Spring的依赖注入理解，@Autowired用法
  • 网络数据分层封装与解封过程的详细说明
  • STM32 开发的鼠标：技术详解与实现指南
  • RBAC（Role-Based Access Control，基于角色的访问控制）介绍（一种通过角色来管理用户权限的访问控制模型）
  • 深入解析 SymPy 中的符号计算：导数与变量替换的实践指南
  • 【未限制消息消费导致数据库CPU告警问题排查及解决方案】