使用custom_target创建的CMake目标构建失败问题排查

架构老林

2026-5-20

排查CMake自定义ELF转HEX目标异常的常见原因

我在嵌入式开发里经常碰到这类问题——直接跑转换脚本没问题，但集成到CMake构建流程里就出状况，结合你的描述，大概率是CMake上下文和直接运行脚本的环境差异导致的，给你列几个最容易踩的坑：

路径解析的上下文差异
你直接跑脚本时，是在自己熟悉的工作目录下，相对路径指向的文件位置很明确，但CMake的构建是基于**构建目录（build dir）**的，默认和源码目录分离。如果你在自定义目标里写死了相对路径（比如arm-none-eabi-objcopy -O ihex my_project.elf my_project.hex），CMake可能会在构建目录下去找这个ELF文件，而不是源码目录或者你预期的输出目录。
正确的做法是用CMake的生成器表达式来动态获取目标文件的路径，比如：
```
add_custom_target(
    gen_hex ALL
    COMMAND ${CMAKE_OBJCOPY} -O ihex $<TARGET_FILE:your_executable_target> $<TARGET_FILE_DIR:your_executable_target>/your_executable.hex
    DEPENDS your_executable_target
    COMMENT "Converting ELF to HEX..."
)
```
这里$<TARGET_FILE:xxx>会自动替换成目标ELF的绝对路径，完全避免路径问题。
工具链环境未在CMake中正确配置
直接运行脚本时，你的终端已经加载了交叉编译工具链的环境变量（比如arm-none-eabi-objcopy已经在PATH里），但CMake构建进程可能是在一个干净的环境中启动的（比如IDE自带的CMake进程，或者CI环境），导致找不到转换工具。
解决办法有两个：一是在CMake工具链文件里显式指定CMAKE_OBJCOPY的路径，比如：
```
set(CMAKE_OBJCOPY "/opt/arm-gnu-toolchain/bin/arm-none-eabi-objcopy" CACHE PATH "Objcopy utility")
```
二是确保启动CMake的环境已经加载了工具链的环境变量（比如先source工具链的setup脚本，再运行cmake ..）。
自定义目标的依赖关系缺失
手动跑脚本时，你肯定是等ELF文件编译完成后才执行转换，但CMake是并行构建的，如果你的HEX目标没有明确依赖ELF目标，CMake可能会在ELF还没生成时就尝试执行转换命令，自然会报错找不到文件。
一定要在add_custom_target里加上DEPENDS your_executable_target，让CMake知道必须先完成ELF目标的构建，再处理HEX转换。
输出目录的权限问题
直接跑脚本时用的是当前用户，对输出目录有写入权限，但CMake构建时可能用了不同的用户身份（比如IDE以管理员权限运行，或者CI环境的专用用户），导致无法写入HEX文件到指定目录。可以查看CMake构建日志里有没有Permission denied相关的错误信息，针对性调整目录权限。
CMake变量替换时机错误
如果你用了普通的CMake变量（比如${ELF_FILE_PATH}）来指定ELF路径，而不是生成器表达式，这个变量在CMake配置阶段就会被替换，但目标文件的实际路径是在构建阶段才确定的，会导致路径错误。生成器表达式（$<...>）是专门用于构建阶段的变量替换，必须用它来引用目标文件路径。

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