全流程：在 Windows 上用 CMake 编译线程安全 HDF5 并解决符号错误

✅ 全流程：在 Windows 上用 CMake 编译线程安全 HDF5 并解决符号错误

---

🧰 环境准备

• ✅ 操作系统：Windows 10 / 11

• ✅ 工具链：

  • Visual Studio 2022（带 C++ 和 CMake 支持）
  • CMake ≥ 3.20
  • 可选：git, 7-zip, dumpbin（随 Visual Studio 安装）

---

📦 第一步：下载 HDF5 源码

方法 1：从 Git 克隆

git clone https://github.com/HDFGroup/hdf5.git
cd hdf5

默认会下载最新主分支，也可以指定分支/标签：

git checkout hdf5-1_14_3

---

🛠️ 第二步：使用 CMake 配置 HDF5

创建构建目录

mkdir build
cd build

使用 CMake 配置（线程安全 + DLL）

cmake .. -G "Visual Studio 17 2022" ^
  -A x64 ^
  -DBUILD_SHARED_LIBS=ON ^
  -DHDF5_ENABLE_THREADSAFE=ON ^
  -DHDF5_ENABLE_Z_LIB_SUPPORT=ON ^
  -DHDF5_BUILD_CPP_LIB=OFF ^
  -DCMAKE_INSTALL_PREFIX=C:\hdf5\install ^
  -DHDF5_BUILD_TOOLS=OFF ^
  -DHDF5_BUILD_EXAMPLES=OFF

参数说明

参数	说明
BUILD_SHARED_LIBS=ON	构建 DLL
HDF5_ENABLE_THREADSAFE=ON	打开线程安全支持
CMAKE_INSTALL_PREFIX	安装路径
HDF5_BUILD_CPP_LIB=OFF	不编译 C++ 接口
HDF5_BUILD_TOOLS=OFF	不编译命令行工具
HDF5_BUILD_EXAMPLES=OFF	不编译 demo 程序

---

🔨 第三步：编译并安装

cmake --build . --config Release --target INSTALL

构建完成后，你会看到安装路径下有：

C:\hdf5\install\include\     ← 头文件
C:\hdf5\install\lib\         ← .lib 文件
C:\hdf5\install\bin\         ← .dll 文件

---

📄 第四步：创建你的项目并链接 HDF5

你可以创建一个最小的项目结构如下：

my_project/
├── CMakeLists.txt
├── main.c

main.c 示例

#include <stdio.h>
#include "hdf5.h"

int main() {
    printf("HDF5 type ID: %ld\n", H5T_NATIVE_INT);
    return 0;
}

CMakeLists.txt

cmake_minimum_required(VERSION 3.20)
project(my_hdf5_test C)

# 引入 HDF5 安装目录
set(HDF5_ROOT "C:/hdf5/install")

# 查找 HDF5
find_package(HDF5 REQUIRED CONFIG PATHS "${HDF5_ROOT}/cmake")

# 创建你的可执行文件
add_executable(my_hdf5_test main.c)

# 添加 HDF5 宏（重点！）
target_compile_definitions(my_hdf5_test PRIVATE H5_BUILT_AS_DYNAMIC_LIB)

# 包含头文件
target_include_directories(my_hdf5_test PRIVATE ${HDF5_INCLUDE_DIRS})

# 链接 HDF5 的动态库
target_link_libraries(my_hdf5_test PRIVATE ${HDF5_LIBRARIES})

编译

mkdir build
cd build
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release

---

🚀 第五步：运行并测试

将以下 DLL 放到你的可执行程序所在目录（或添加到 PATH）：

• hdf5.dll
• 可能还有 zlib.dll（如果启用了压缩）

然后运行：

Release\my_hdf5_test.exe

---

🧪 第六步：使用 dumpbin 检查符号

dumpbin /all C:\hdf5\install\lib\hdf5.lib | findstr H5T_NATIVE_INT_g

你应该会看到：

__imp_H5T_NATIVE_INT_g

表示该符号是从 DLL 导入的。

---

🔍 错误排查指南

问题	原因	解决方法
❌ unresolved symbol H5T_NATIVE_INT_g	未定义 H5_BUILT_AS_DYNAMIC_LIB 宏	在 CMake 中添加宏定义
❌ 无法加载 DLL	没放到程序目录，或没加入 PATH	拷贝 DLL 到可执行程序目录
❌ 找不到 H5T_NATIVE_INT_g in .lib	构建的是 DLL，但你希望静态链接	改用 BUILD_SHARED_LIBS=OFF

---

✅ 最终效果回顾

你已经完成了：

1. ✅ 下载 HDF5 源码
2. ✅ 用 CMake 构建线程安全版本
3. ✅ 定义了正确的 dllimport 宏
4. ✅ 用自己的程序链接测试
5. ✅ 用 dumpbin 成功验证符号