CMake静态构建链接libcurl出现未定义引用错误的原因及解决

• 静态库（.a）本质是编译生成的目标文件（.o）的归档压缩包，和动态库（.so）逻辑完全不同：动态库会在文件内记录自身依赖关系，运行时自动加载依赖；静态库既不存储任何依赖信息，也不会把依赖库的代码打包进自身。
• 编译libcurl.a时添加的--with-openssl参数，作用仅为让编译过程找到openssl头文件、完成libcurl自身编译，不会把openssl、libidn2这类第三方依赖的代码合并到libcurl.a中。
• 用ldd /usr/local/lib/libcurl.a得到not a dynamic executable属于正常现象：ldd仅用于检查动态可执行文件、动态库的依赖，本身不支持识别静态库依赖，该结果不能证明libcurl无外部依赖。
• 原有CMake配置仅链接了libcurl.a本身，未提供libcurl依赖的其他静态库，链接器找不到对应函数符号，就会触发undefined reference报错。

静态链接最终可执行文件时，必须把整条依赖链上的所有静态库全部提供给链接器，没有捷径。具体操作步骤如下：

1. 安装全量依赖的静态库版本
   当前报错对应的依赖包括：
   • idn2_free对应libidn2的静态库，安装对应开发包后即可获得libidn2.a
   • MD5_Init、SSL_set_ex_data对应openssl的静态库，需要libssl.a和libcrypto.a，安装openssl开发包即可获得
     除此之外libcurl通常还依赖zlib、libpsl、libunistring等库，需要确保这些库的静态版本也都安装在系统中。
2. 自动获取全量链接参数
   不要手动枚举依赖，直接用pkg-config工具查询静态链接libcurl所需的完整链接参数，执行命令：

   pkg-config --static --libs libcurl
   

   命令输出的内容就是静态链接时需要的所有库链接参数，包含全量依赖，还会自动处理库的链接顺序（静态链接对库的先后顺序有严格要求，被依赖的库需要放在靠后的位置）。
3. 修正CMake配置
   静态链接场景下不建议直接用默认的find_package(CURL)，它通常不会自动带上所有间接依赖。推荐直接用pkg-config导入libcurl的静态链接目标，修正后的CMake配置如下：

   cmake_minimum_required(VERSION 3.17)
   project(static-build-test)
   
   set(CMAKE_FIND_LIBRARY_SUFFIXES ".a")
   set(BUILD_SHARED_LIBS OFF)
   set(CMAKE_EXE_LINKER_FLAGS "-static")
   
   # 导入pkg-config工具，自动获取静态链接的全量依赖
   find_package(PkgConfig REQUIRED)
   pkg_check_modules(CURL_STATIC REQUIRED IMPORTED_TARGET libcurl)
   
   add_executable(static-test main.cpp)
   # 链接pkg-config导出的目标，会自动携带所有依赖库、处理链接顺序
   target_link_libraries(static-test PRIVATE PkgConfig::CURL_STATIC)
   

4. 重新构建即可，只要所有依赖的静态库都安装齐全，就不会再出现未定义引用错误。

• 构建前必须确认所有依赖都存在对应的.a静态库文件，如果某个依赖只有动态.so版本，添加-static参数后链接仍会失败。
• 自行编译依赖库时，需要和编译libcurl一样添加--disable-shared参数，确保生成静态库版本。

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