CMake 教程：查找库与包 5.4 自定义查找模块

在 CMake 中，查找库与包是一个重要的功能，尤其是在处理大型项目或依赖于多个外部库时。CMake 提供了一些内置的查找模块，但在某些情况下，您可能需要创建自定义查找模块以满足特定需求。本文将详细介绍如何创建和使用自定义查找模块，包括优缺点和注意事项。

1. 自定义查找模块的概述

自定义查找模块是 CMake 脚本文件，通常以 Find<PackageName>.cmake 的形式命名。它们的主要目的是帮助 CMake 查找特定的库或包，并设置相应的变量以供后续使用。

优点

灵活性：可以根据项目的特定需求自定义查找逻辑。
可重用性：可以在多个项目中重用相同的查找模块。
简化配置：通过封装查找逻辑，简化了 CMakeLists.txt 的复杂性。

缺点

维护成本：需要手动维护查找模块，可能会增加工作量。
学习曲线：对于初学者来说，理解和编写查找模块可能比较困难。

注意事项

确保查找模块的命名与 CMake 的命名约定一致。
在查找模块中使用适当的错误处理，以便在找不到库时提供清晰的反馈。

2. 创建自定义查找模块

2.1 文件结构

首先，您需要创建一个新的 CMake 查找模块文件。假设我们要查找一个名为 MyLibrary 的库，我们可以创建一个名为 FindMyLibrary.cmake 的文件。

project/
├── CMakeLists.txt
└── cmake/
    └── FindMyLibrary.cmake

2.2 编写查找模块

在 FindMyLibrary.cmake 文件中，您需要定义查找逻辑。以下是一个简单的示例：

# FindMyLibrary.cmake
# 查找 MyLibrary 库

# 设置要查找的库名称
set(MYLIBRARY_NAME "MyLibrary")

# 查找库的路径
find_path(MYLIBRARY_INCLUDE_DIR
  NAMES MyLibrary.h
  PATHS /usr/local/include /usr/include
)

find_library(MYLIBRARY_LIBRARY
  NAMES ${MYLIBRARY_NAME}
  PATHS /usr/local/lib /usr/lib
)

# 检查是否找到库
if(NOT MYLIBRARY_INCLUDE_DIR OR NOT MYLIBRARY_LIBRARY)
  message(FATAL_ERROR "Could not find ${MYLIBRARY_NAME}")
endif()

# 设置库的使用变量
set(MYLIBRARY_FOUND TRUE)

# 导出变量
set(MYLIBRARY_INCLUDE_DIRS ${MYLIBRARY_INCLUDE_DIR} CACHE PATH "Include directory for MyLibrary")
set(MYLIBRARY_LIBRARIES ${MYLIBRARY_LIBRARY} CACHE PATH "Library for MyLibrary")

2.3 解释代码

find_path：用于查找头文件的路径。它会在指定的路径中查找 MyLibrary.h 文件。
find_library：用于查找库文件的路径。它会在指定的路径中查找 libMyLibrary.so 或 libMyLibrary.a。
if(NOT ...)：检查是否成功找到库和头文件。如果没有找到，使用 message(FATAL_ERROR ...) 报告错误并终止配置过程。
set(... CACHE ...)：将找到的路径存储在 CMake 的缓存中，以便在其他地方使用。

3. 在 CMakeLists.txt 中使用自定义查找模块

在项目的 CMakeLists.txt 文件中，您可以使用 find_package 来调用自定义查找模块：

cmake_minimum_required(VERSION 3.10)
project(MyProject)

# 添加查找模块的路径
list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")

# 查找 MyLibrary
find_package(MyLibrary REQUIRED)

# 使用找到的库
add_executable(MyExecutable main.cpp)
target_include_directories(MyExecutable PRIVATE ${MYLIBRARY_INCLUDE_DIRS})
target_link_libraries(MyExecutable PRIVATE ${MYLIBRARY_LIBRARIES})

3.1 解释代码

list(APPEND CMAKE_MODULE_PATH ...)：将自定义查找模块的路径添加到 CMake 的模块搜索路径中。
find_package(MyLibrary REQUIRED)：调用自定义查找模块。如果未找到库，将会终止配置过程。
target_include_directories 和 target_link_libraries：将找到的库和头文件路径链接到可执行文件。

4. 进阶功能

4.1 支持多个版本

如果您的库有多个版本，您可以在查找模块中添加版本支持。例如：

find_package(MyLibrary 1.0 REQUIRED)

在 FindMyLibrary.cmake 中，您可以使用 find_package_handle_standard_args 来处理版本：

include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(MyLibrary DEFAULT_MSG MYLIBRARY_LIBRARY MYLIBRARY_INCLUDE_DIR)

4.2 查找多个库

如果您需要查找多个库，可以在查找模块中使用循环。例如：

foreach(lib_name MyLibrary1 MyLibrary2)
  find_library(${lib_name}_LIBRARY NAMES ${lib_name} PATHS /usr/local/lib /usr/lib)
  if(NOT ${lib_name}_LIBRARY)
    message(FATAL_ERROR "Could not find ${lib_name}")
  endif()
endforeach()

5. 总结

自定义查找模块是 CMake 中一个强大的功能，能够帮助开发者灵活地管理项目依赖。通过创建和使用自定义查找模块，您可以提高项目的可维护性和可重用性。尽管自定义查找模块的维护成本较高，但它们为复杂项目提供了必要的灵活性。

在创建自定义查找模块时，请务必遵循 CMake 的最佳实践，确保模块的可读性和可维护性。通过合理的错误处理和清晰的变量命名，您可以使查找模块更加健壮和易于使用。

希望本教程能帮助您更好地理解和使用 CMake 的自定义查找模块功能！