CMake與catkin_make的find_package()命令使用說明

在 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`兩者關系總結

特性	`COMPONENTS`	`NO_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-config`	`find_package(PkgConfig)`	`PKG_CONFIG_FOUND`