CMake中find_package失败时配置FetchContent作为fallback的惯用方法

在CMake 3.24及以上版本中，利用FetchContent_declare()的OVERRIDE_FIND_PACKAGE参数是实现这种"优先查找系统包，失败则回退到自定义构建"需求的标准做法，既保留了find_package()的简洁性，又能灵活控制后备逻辑。

完整实现示例 #

# 引入FetchContent模块
include(FetchContent)

# 优先检查本地是否存在预打包的foo压缩包
set(foo_LOCAL_ARCHIVE "${CMAKE_CURRENT_SOURCE_DIR}/third_party/foo-1.2.3.tar.gz")

# 声明FetchContent配置，开启OVERRIDE_FIND_PACKAGE作为find_package的后备
if(EXISTS "${foo_LOCAL_ARCHIVE}")
    FetchContent_declare(
        foo
        OVERRIDE_FIND_PACKAGE
        URL "${foo_LOCAL_ARCHIVE}"
        # 校验本地包的哈希值，确保完整性
        URL_HASH SHA256=abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789
    )
else()
    # 本地无包时，回退到从Git仓库拉取指定版本
    FetchContent_declare(
        foo
        OVERRIDE_FIND_PACKAGE
        GIT_REPOSITORY "https://github.com/example/foo.git"
        GIT_TAG "v1.2.3"
        # 可选：启用浅克隆加快下载速度
        GIT_SHALLOW ON
    )
endif()

# 尝试查找系统中符合版本范围的foo包（>=1.2.3且<2.0.0）
# 使用QUIET避免查找失败时直接终止构建
find_package(foo 1.2.3...<2.0.0 QUIET)

# 若系统查找失败，触发FetchContent构建foo包
if(NOT foo_FOUND)
    FetchContent_MakeAvailable(foo)
endif()

# 后续正常使用foo包的目标（假设foo导出了命名空间目标foo::foo）
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE foo::foo)

关键细节说明 #

• OVERRIDE_FIND_PACKAGE参数：这个参数告诉CMake，当find_package(foo)查找失败时，自动将当前FetchContent的定义作为该包的来源，实现了查找逻辑和后备逻辑的无缝衔接。
• 版本范围写法：CMake 3.19+支持...语法表示版本区间，1.2.3...<2.0.0等价于要求包版本大于等于1.2.3且小于2.0.0。
• 本地包优先逻辑：通过EXISTS检查本地预打包文件，优先使用本地资源，避免不必要的网络下载，符合你的需求。
• QUIET选项：如果不添加QUIET，find_package查找失败会直接抛出错误终止构建，无法触发后续的回退逻辑。

这种方式完全遵循CMake的现代最佳实践，既保证了构建的灵活性，又保持了配置的简洁性。

内容的提问来源于stack exchange，提问作者einpoklum