基于CMake的项目如何管理内部共享库的多版本适配问题

针对同仓库内不兼容版本内部库的共存需求，按维护成本从低到高推荐以下方案，优先选择第一种长期方案：

1. 版本化目录隔离（长期维护首选） #

直接将不同不兼容版本的库做物理目录隔离，从根源上避免接口、配置串扰，适合需要长期维护旧版库的场景。

调整后目录结构 #

RootFolder
├─ CMakeLists.txt
├─ Lib1
│  ├─ v1  # 旧兼容版，仅给App2提供依赖，仅做必要bug修复
│  │  ├─ lib1.cpp
│  │  ├─ lib1.h
│  │  └─ CMakeLists.txt
│  └─ v2  # 新版迭代主线，给App1提供依赖，所有新功能优先合入该版本
│     ├─ lib1.cpp
│     ├─ lib1.h
│     └─ CMakeLists.txt
├─ App1
│  ├─ app1.cpp
│  ├─ app1.h
│  └─ CMakeLists.txt
└─ App2
   ├─ app2.cpp
   ├─ app2.h
   └─ CMakeLists.txt

CMake配置要点 #

• 两个版本的库目标必须设置不同的命名，建议用带命名空间的别名目标避免冲突：
  • v1目录下的CMakeLists将目标导出为Lib1::v1
  • v2目录下的CMakeLists将目标导出为Lib1::v2
• 应用侧链接时直接指定对应版本目标即可：
  • App1的CMakeLists写target_link_libraries(App1 PRIVATE Lib1::v2)
  • App2的CMakeLists写target_link_libraries(App2 PRIVATE Lib1::v1)
• 头文件搜索路径、编译选项会跟随目标属性自动传递，不需要额外配置，不会出现头文件引用错误的问题。后续App2完成新版适配时，只需要把链接目标从Lib1::v1改成Lib1::v2即可完成迁移。

2. 编译宏开关隔离（短周期过渡可选） #

如果确定App2在很短时间内（比如1-2周）就能完成新版适配，不想调整目录结构，可以在原有Lib1代码中通过编译宏隔离新旧接口，构建两个不同配置的库目标。

配置示例 #

在Lib1的CMakeLists中构建两个独立目标，分别开启不同版本的宏开关：

# 旧版库目标
add_library(Lib1_v1 STATIC lib1.cpp)
target_include_directories(Lib1_v1 PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
set_target_properties(Lib1_v1 PROPERTIES OUTPUT_NAME "lib1_v1")

# 新版库目标
add_library(Lib1_v2 STATIC lib1.cpp)
target_include_directories(Lib1_v2 PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
target_compile_definitions(Lib1_v2 PUBLIC LIB1_ENABLE_V2_API)
set_target_properties(Lib1_v2 PROPERTIES OUTPUT_NAME "lib1_v2")

在头文件中用宏隔离接口声明：

#ifdef LIB1_ENABLE_V2_API
// 新版接口
int new_api(const char* param);
#else
// 旧版接口
int old_api(char* param);
#endif

两个App分别链接Lib1_v1和Lib1_v2即可。

注意：该方案长期维护成本极高，代码中会充斥大量版本判断宏，很容易出现改漏、逻辑冲突的问题，仅适合极短周期的过渡场景，禁止长期使用。

避坑提醒 #

• 两个版本的库目标名、输出文件名绝对不能重复，否则会出现CMake目标重名报错、链接时符号冲突、运行时加载错库等难以排查的问题
• 如果编译为动态库（.so/.dll），必须给两个版本设置不同的SOVERSION属性，避免运行时动态链接器加载错误版本
• 不要尝试用运行时动态加载、符号隐藏等奇技淫巧绕开编译期隔离，这类方案调试成本极高，内部依赖场景完全没有必要

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