CMake问题：全局HDF5库与ExternalProject_Add的冲突

问题场景 #

通过ExternalProject_Add引入特定版本HDF5库时，Windows机器上的全局HDF5（路径C:\Program Files\HDF_Group\HDF5\1.12.2\include）会被VS2019自动引入，导致头文件重定义错误，典型报错：

Error C2365 'H5_ITER_UNKNOWN': redefinition; previous definition was 'enumerator' C:\somePath C:<myCmakeBuildDir>\hdf5\src\H5public.h 296

同时伴随大量宏重定义警告，且未主动调用find_library/find_package触发全局搜索，修改ExternalProject名称也无法解决问题。

核心原因 #

这不是HDF5特有问题，属于CMake构建时系统默认路径优先级或VS编译器自动搜索全局库导致的冲突。Windows环境下VS可能会自动添加常见库的系统路径，或是项目中某个间接依赖隐式触发了HDF5的全局查找。

解决方法（无"find_library反向操作"，但可强制指定版本） #

1. 为ExternalProject构建的HDF5创建导入目标，明确路径 #

直接指定外部构建生成的HDF5头文件和库路径，完全绕过系统搜索：

# 定义ExternalProject，指定安装目录避免和全局路径混淆
ExternalProject_Add(hdf5_external
    URL "https://www.hdfgroup.org/package/hdf5-1.14.0.tar.gz" # 替换为目标版本
    CMAKE_ARGS
        -DBUILD_SHARED_LIBS=OFF
        -DHDF5_BUILD_EXAMPLES=OFF
        -DHDF5_BUILD_TOOLS=OFF
        -DCMAKE_INSTALL_PREFIX=${CMAKE_BINARY_DIR}/hdf5_install
)

# 创建导入目标，关联ExternalProject
add_library(hdf5 STATIC IMPORTED GLOBAL)
add_dependencies(hdf5 hdf5_external)

# 设置导入目标的属性，明确指定路径
set_target_properties(hdf5 PROPERTIES
    IMPORTED_LOCATION "${CMAKE_BINARY_DIR}/hdf5_install/lib/hdf5.lib" # Windows静态库后缀
    INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_BINARY_DIR}/hdf5_install/include"
)

# 链接项目目标时直接使用该导入目标
target_link_libraries(your_target PRIVATE hdf5)

2. 禁用CMake的系统路径自动搜索 #

在项目最开始添加配置，禁止CMake自动搜索系统环境变量和默认系统路径：

set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH OFF)
set(CMAKE_FIND_USE_CMAKE_SYSTEM_PATH OFF)

注意：这会影响所有find_package/find_library操作，若项目有其他依赖需要系统库，需单独为其指定路径或开启搜索。

3. 强制调整头文件包含路径优先级 #

如果是VS自动添加了全局路径，用BEFORE关键字让ExternalProject的头文件路径排在最前面：

target_include_directories(your_target
    BEFORE PRIVATE
    "${CMAKE_BINARY_DIR}/hdf5_install/include"
)

4. 排查间接依赖的隐式查找 #

开启CMake调试模式，查看是哪个模块触发了HDF5全局搜索：

set(CMAKE_FIND_DEBUG_MODE ON)

根据日志找到触发查找的模块后，针对性禁用其自动查找逻辑。

总结 #

不存在严格意义上的"find_library反向操作"，但通过明确指定导入目标路径、禁用系统路径搜索、调整包含路径优先级，可以强制CMake使用你通过ExternalProject_Add构建的特定版本HDF5，规避全局库冲突。

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