C / C++ / 系统课时
用 target_link_libraries 建依赖
用 target_link_libraries 建依赖
当可执行程序开始依赖内部库时,最容易出错的做法是手工拼接库文件路径和链接参数。本节用一个可运行的小项目演示 target_link_libraries:只声明“哪个目标依赖哪个目标”,让 CMake 根据目标关系生成正确的链接命令。
学习目标
- 会用
target_link_libraries连接可执行目标与内部库 - 理解目标依赖与实际链接命令之间的关系
- 能通过构建和运行结果验证链接是否生效
把“链接谁”写成目标关系
现代 CMake 更推荐围绕 target 建模,而不是直接维护一串 -L、-l 或库文件路径。假设项目有一个静态库 calc 和一个可执行程序 app,关系只需要写成“app 依赖 calc”。

target_link_libraries(app PRIVATE calc) 的重点不是“把某个 .a 文件塞进命令”,而是把 calc 这个 CMake 目标登记为 app 的链接依赖。CMake 因而知道目标之间的构建先后、实际库文件位置以及生成器需要采用的链接表达方式。
建立一个最小可运行项目
示例使用三个文件:include/calc.h 声明接口,src/calc.c 实现库,src/main.c 调用库。CMakeLists.txt 如下:
cmake_minimum_required(VERSION 3.20)
project(LinkDemo C)
# 公开头文件目录会作为 calc 的使用要求传给消费者。
add_library(calc STATIC src/calc.c)
target_include_directories(calc PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
# app 只声明对 calc 目标的链接依赖,不写库文件路径。
add_executable(app src/main.c)
target_link_libraries(app PRIVATE calc)include/calc.h:
#ifndef CALC_H
#define CALC_H
/* 这是 calc 暴露给调用方的公开函数声明。 */
int add(int a, int b);
#endifsrc/calc.c:
#include "calc.h"
/* 实现只属于 calc 库,调用方不需要看到源文件。 */
int add(int a, int b) {
return a + b;
}src/main.c:
#include <stdio.h>
#include "calc.h"
int main(void) {
/* app 只通过公开头文件调用 calc。 */
printf("sum=%d\n", add(2, 3));
return 0;
}这里没有给 app 手工配置头文件目录。因为 calc 把自己的公开头文件目录声明为 PUBLIC,app 在链接 calc 时会同时得到这项使用要求。
构建并验证链接结果
下面命令适用于使用单配置生成器的 Linux 或 macOS 环境;其他生成器的可执行文件位置可能不同。生成与编译日志被隐藏,只保留程序输出。
# 只观察最终程序结果,任一步失败都会停止后续命令。
cmake -S . -B build >/dev/null && cmake --build build >/dev/null && ./build/app预期输出:
sum=5如果删除 target_link_libraries(app PRIVATE calc),main.c 仍可能因为其他配置而完成编译,但链接阶段会找不到 add 的实现。不同编译器的错误文本不同,关键现象都是“声明可见、实现未被链接”。
为什么比手工写库路径更稳
直接写绝对路径会把构建目录、平台和库文件名绑定到当前机器;直接拼 -lcalc 又绕过了 CMake 的目标模型。使用目标名后,CMake 可以跟踪库是当前工程生成的还是外部导入的,并在依赖变化时重新安排构建。
因此,target_link_libraries 最核心的用法可以概括为:先创建清晰的 target,再声明 target 之间的链接边。依赖关系一旦进入 CMake 模型,构建顺序和链接输入就不再靠人工维护。