CMake自定义目标add_custom_target如何配置命令参数与依赖关系以避免构建失败

if(NOT GENERATE_VERSION_SCRIPT)
message(FATAL_ERROR “generate_version.sh not found”)
endif()

# 定义自定义目标
add_custom_target(generate_version
COMMAND ${GENERATE_VERSION_SCRIPT} ${CMAKE_SOURCE_DIR} ${CMAKE_BINARY_DIR}/version.h
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
COMMENT “Generating version.h”
VERBATIM
)
解释
：
使用
find_program
查找脚本，确保路径正确。
传递源目录和输出文件路径作为参数。
VERBATIM
确保参数如
-D
等不被shell拆分。
如果不使用
VERBATIM
，在Windows上可能因路径中的反斜杠而失败。
避免构建失败的提示
：
测试命令：在命令行中手动运行命令，确保它在所有平台上工作。
使用
COMMAND_EXPAND_LISTS
如果参数是列表：例如，如果参数是
-I include1 -I include2
，可以将其存储在列表中并展开。
2.2 处理多命令和条件执行
如果需要执行多个命令，可以链式使用
COMMAND
。但要注意，如果一个命令失败，整个目标会失败。使用
||
或
&&
在shell中处理条件，但最好避免，因为
VERBATIM
会禁用shell解释。
示例：编译并运行代码生成器
# 假设我们有一个代码生成器，需要先编译再运行
add_custom_target(generate_code
COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/generated
COMMAND ${CMAKE_COMMAND} -E echo “Running generator…”
COMMAND generator_app –input ${CMAKE_SOURCE_DIR}/input.txt –output ${CMAKE_BINARY_DIR}/generated/output.cpp
DEPENDS generator_app ${CMAKE_SOURCE_DIR}/input.txt
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
COMMENT “Generating code”
VERBATIM
)
解释
：
第一个命令创建目录，第二个打印消息，第三个运行生成器。
如果目录已存在，
make_directory
不会失败。
使用
DEPENDS
确保
generator_app
已构建。
避免构建失败的提示
：
对于复杂逻辑，考虑使用单独的CMake脚本（
.cmake
文件）并通过
cmake -P
运行它。
避免在
COMMAND
中使用shell特性如管道
|
或重定向
>
；使用CMake的
-E
工具（如
cmake -E copy
）代替。
2.3 处理跨平台兼容性
Windows、Linux和macOS的命令行为不同。使用CMake的内置变量如
${CMAKE_COMMAND} -E
来执行跨平台操作。
示例：跨平台文件复制
add_custom_target(copy_assets
COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/assets ${CMAKE_BINARY_DIR}/assets
DEPENDS ${CMAKE_SOURCE_DIR}/assets
COMMENT “Copying assets”
VERBATIM
)
解释
：
cmake -E copy_directory
在所有平台上工作，避免使用
cp
或
xcopy
。
如果必须使用原生命令，使用条件判断：
if(WIN32)
set(COPY_COMMAND xcopy /E /I ${CMAKE_SOURCE_DIR}/assets ${CMAKE_BINARY_DIR}/assets)
else()
set(COPY_COMMAND cp -r ${CMAKE_SOURCE_DIR}/assets ${CMAKE_BINARY_DIR}/assets)
endif()

add_custom_target(copy_assets
COMMAND ${COPY_COMMAND}
VERBATIM
)
避免构建失败的提示
：
在CI/CD中测试所有平台。
使用
BYPRODUCTS
指定输出文件，以支持Ninja等生成器的正确依赖跟踪。
3. 配置依赖关系以避免构建失败
依赖关系是确保构建顺序的关键。如果依赖未正确指定，自定义目标可能在依赖未构建时运行，导致失败。
DEPENDS
可以接受文件路径或目标名称。
3.1 文件依赖 vs 目标依赖
文件依赖
：确保文件存在或已更新。
目标依赖
：确保另一个目标（如可执行文件或库）已构建。
示例：依赖另一个目标的自定义目标
假设我们有一个工具
tool_app
，需要先构建它，然后用它生成文件。
# 定义工具可执行文件
add_executable(tool_app tool_app.cpp)

# 自定义目标依赖tool_app
add_custom_target(generate_docs
COMMAND tool_app –generate-docs ${CMAKE_SOURCE_DIR}/src ${CMAKE_BINARY_DIR}/docs
DEPENDS tool_app ${CMAKE_SOURCE_DIR}/src
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
COMMENT “Generating documentation”
VERBATIM
)
解释
：
DEPENDS tool_app
确保
tool_app
在
generate_docs
之前构建。
如果
tool_app
未构建，CMake会先构建它。
文件依赖
${CMAKE_SOURCE_DIR}/src
确保如果源文件变化，重新生成文档。
避免构建失败的提示
：
如果依赖是目标，确保目标名称正确，且目标是可构建的（如
add_executable
或
add_library
）。
对于间接依赖，使用
add_dependencies
显式链接：
add_dependencies(generate_docs tool_app)
。
3.2 处理循环依赖和并行构建
循环依赖会导致死锁。CMake会检测并报错，但最好避免。并行构建（
make -j
）可能暴露依赖问题。
示例：避免循环依赖
假设目标A依赖B，B依赖A。重构为单向依赖。
# 错误：循环依赖
# add_custom_target(A COMMAND … DEPENDS B)
# add_custom_target(B COMMAND … DEPENDS A)

# 正确：使用中间目标
add_custom_target(prepare DEPENDS some_file)

add_custom_target(A
COMMAND …
DEPENDS prepare
)

add_custom_target(B
COMMAND …
DEPENDS A # 现在是单向
)
解释
：
prepare
目标作为中介，确保文件准备就绪。
对于并行构建，使用
BYPRODUCTS
指定所有输出文件，让CMake正确跟踪。
示例：使用BYPRODUCTS处理并行构建
add_custom_target(generate_sources
COMMAND python ${CMAKE_SOURCE_DIR}/gen.py –out ${CMAKE_BINARY_DIR}/generated
BYPRODUCTS ${CMAKE_BINARY_DIR}/generated/file1.cpp ${CMAKE_BINARY_DIR}/generated/file2.cpp
DEPENDS ${CMAKE_SOURCE_DIR}/gen.py
COMMENT “Generating sources”
VERBATIM
)
解释
：
BYPRODUCTS
告诉CMake这些文件将被生成，避免在并行构建中重复执行。
如果不指定，CMake可能认为目标总是需要重新构建，导致无限循环或失败。
3.3 使用add_dependencies增强依赖
有时
DEPENDS
不足以表达复杂依赖，使用
add_dependencies
。
示例：库依赖自定义目标
add_library(mylib mylib.cpp)

add_custom_target(run_tests
COMMAND test_runner –lib mylib
DEPENDS mylib
COMMENT “Running tests”
)

# 显式添加依赖，确保mylib在run_tests前构建
add_dependencies(run_tests mylib)
解释
：
DEPENDS
确保文件依赖，
add_dependencies
确保目标依赖。
这在自定义目标不直接链接库时有用。
4. 高级配置：处理常见构建失败场景
4.1 错误处理和日志
默认情况下，命令失败会停止构建。使用
COMMAND
的返回值检查，或在脚本中处理错误。
示例：使用CMake脚本处理错误
创建
error_handler.cmake
：
# error_handler.cmake
execute_process(
COMMAND ${CMD_TO_RUN}
RESULT_VARIABLE result
OUTPUT_VARIABLE output
ERROR_VARIABLE error
)
if(NOT result EQUAL 0)
message(FATAL_ERROR “Command failed: ${error}”)
endif()
在CMakeLists.txt中：
add_custom_target(safe_run
COMMAND ${CMAKE_COMMAND} -DCMD_TO_RUN=”your_command” -P ${CMAKE_SOURCE_DIR}/error_handler.cmake
VERBATIM
)
解释
：
execute_process
捕获输出和错误。
如果失败，使用
message(FATAL_ERROR)
报告，但不中断整个CMake配置。
4.2 条件依赖和变量
使用CMake变量动态配置依赖。
示例：条件依赖
option(ENABLE_TESTS “Enable tests” ON)

if(ENABLE_TESTS)
set(TEST_DEP test_app)
else()
set(TEST_DEP “”)
endif()

add_custom_target(integration_test
COMMAND run_integration_tests
DEPENDS ${TEST_DEP}
VERBATIM
)
解释
：
如果禁用测试，依赖为空，避免未定义目标错误。
4.3 工作目录和环境变量
指定工作目录避免路径错误。使用
ENV
设置环境变量。
示例：设置环境变量
add_custom_target(setup_env
COMMAND ${CMAKE_COMMAND} -E env VAR1=value1 ${CMAKE_COMMAND} -E echo “Setup done”
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
VERBATIM
)
解释
：
-E env
设置临时环境变量。
工作目录确保相对路径正确。
5. 调试和测试自定义目标
5.1 启用详细输出
在配置时使用
cmake –build . –verbose
查看命令细节。
5.2 使用message()调试
在CMakeLists.txt中添加：
message(STATUS “Configuring custom target: generate_version”)
5.3 测试构建
创建测试CMakeLists.txt：
cmake_minimum_required(VERSION 3.10)
project(TestCustomTarget)

# 示例：完整的工作自定义目标
add_executable(tool tool.cpp)

add_custom_target(generate_and_run
COMMAND tool –arg1 value1 –output ${CMAKE_BINARY_DIR}/out.txt
DEPENDS tool
BYPRODUCTS ${CMAKE_BINARY_DIR}/out.txt
COMMENT “Running tool”
VERBATIM
)

# 默认包含
add_custom_target(all_targets ALL DEPENDS generate_and_run)
构建测试：
mkdir build && cd build
cmake ..
cmake –build . –verbose
如果失败，检查：
命令是否存在（
which command
）。
依赖文件是否生成。
平台兼容性。
6. 最佳实践总结
始终使用VERBATIM
：避免shell解释问题。
指定BYPRODUCTS
：支持并行构建和正确依赖。
使用绝对路径和CMake变量
：如
${CMAKE_SOURCE_DIR}
。
测试命令独立运行
：确保命令在目标环境中工作。
避免循环依赖
：使用中间目标。
文档化目标
：添加清晰的COMMENT。
在大型项目中使用ALL
：仅当目标是核心时使用，避免默认构建膨胀。
集成到IDE
：使用
add_custom_target
生成IDE可识别的项目文件。
通过这些配置，您可以显著减少构建失败的概率。记住，CMake的
add_custom_target
是灵活的，但需要仔细设计依赖和命令以匹配您的工作流。如果遇到特定错误，检查CMake输出日志并逐步调试命令。
如果您有特定场景或错误日志，可以提供更多细节以获取针对性建议。