CMake中add_custom_target的使用

Posted 2022-12-16 fengbingchun

      CMake中的add_custom_target命令用于添加一个没有输出的target，以便始终构建它，其格式如下：

add_custom_target(Name [ALL] [command1 [args1...]]
                  [COMMAND command2 [args2...] ...]
                  [DEPENDS depend depend depend ... ]
                  [BYPRODUCTS [files...]]
                  [WORKING_DIRECTORY dir]
                  [COMMENT comment]
                  [JOB_POOL job_pool]
                  [VERBATIM] [USES_TERMINAL]
                  [COMMAND_EXPAND_LISTS]
                  [SOURCES src1 [src2...]])

      添加给定名称的target以执行给定命令(Adds a target with the given name that executes the given commands)。target没有输出文件，并且始终被认为是过时的，即使命令尝试创建具有target名称的文件也是如此。使用add_custom_command命令生成具有依赖项的文件。默认情况下，没有什么依赖于自定义target。使用add_dependencies命令向其它target添加依赖项。
      可选项包括：
      (1).ALL:表示要把这个target加入到默认的构建target中，以便每次都会运行。
      (2).BYPRODUCTS:指定命令预期生成的文件，但其修改时间可能会或可能不会在后续构建中更新。如果副产品(byproduct)名称是相对路径，它将相对于与当前源目录相对应的构建树目录进行解释。每个副产品将自动标记为GENERATED源文件属性。
      BYPRODUCTS的参数可以使用一组受限制的生成器表达式(generator expression)。不允许使用依赖于target的表达式。
      (3).COMMAND:指定要在构建时执行的命令行。如果指定了多个COMMAND，它们将按顺序执行，但不一定组成有状态的shell或batch脚本。
      命令和参数是可选的，如果未指定，将创建一个空target.
      (4).COMMENT:在构建时执行命令之前显示给定的消息。
      (5).DEPENDS:在同一目录(CMakeLists.txt文件)中使用add_custom_command命令创建的自定义命令的引用文件和输出(reference files and outputs)。它们将在构建targets时更新。
      (6).COMMAND_EXPAND_LISTS:COMMAND参数中的列表(list)将被扩展。
      (7).JOB_POOL:为Ninja生成器指定一个池(pool).
      (8).SOURCES:指定要包含在自定义target中的其它源文件。指定的源文件将添加到IDE项目文件中,以便于编辑,即使它们没有构建规则。
      (9).VERBATIM:对于构建工具，命令的所有参数都将正确转义(escaped properly),将正确转义命令的所有自变量，以便调用的命令接收每个参数不变。建议使用 VERBATIM，因为它可以实现正确的行为。当未指定VERBATIM时,行为是特定于平台的。
      (10).USES_TERMINAL:如果可能，该命令将被授予直接访问终端(terminal)的权限。
      (11).WORKING_DIRECTORY:使用给定的当前工作目录执行命令。如果是相对路径，会被解释为相对于当前源目录对应的构建树目录。

message("#### test_$TEST_CMAKE_FEATURE.cmake ####")

# 创建一个空的target:add,在build目录下并不会生成add
add_custom_target(add)
if(TARGET add)
    message("target add") # print
endif()

file(MAKE_DIRECTORY $CMAKE_CURRENT_SOURCE_DIR/docs)
add_custom_target(DOCUMENTATION
    ALL
    COMMAND $CMAKE_COMMAND -E echo_append "**** Building API Documentation..."
    COMMAND $CMAKE_COMMAND -E make_directory $CMAKE_CURRENT_SOURCE_DIR/docs
    COMMAND $CMAKE_COMMAND -E echo "**** Done."
    WORKING_DIRECTORY $CMAKE_CURRENT_SOURCE_DIR/docs
    COMMENT "**** test cmake command: add_custom_target"
    VERBATIM
)
if(TARGET DOCUMENTATION)
    message("target DOCUMENTATION") # print
endif()

      执行测试代码需要多个文件：

      build.sh内容如下：

#! /bin/bash

# supported input parameters(cmake commands)
params=(function macro cmake_parse_arguments \\
		find_library find_path find_file find_program find_package \\
		cmake_policy cmake_minimum_required project include \\
		string list set foreach message option if while return \\
		math file configure_file \\
		include_directories add_executable add_library target_link_libraries install \\
		target_sources add_custom_command add_custom_target)

usage()

	echo "Error: $0 needs to have an input parameter"

	echo "supported input parameters:"
	for param in $params[@]; do
		echo "  $0 $param"
	done

	exit -1


if [ $# != 1 ]; then
	usage
fi

flag=0
for param in $params[@]; do
	if [ $1 == $param ]; then
		flag=1
		break
	fi
done

if [ $flag == 0 ]; then
	echo "Error: parameter \\"$1\\" is not supported"
	usage
	exit -1
fi

if [[ ! -d "build" ]]; then
	mkdir build
	cd build
else
	cd build
fi

echo "==== test $1 ===="

# test_set.cmake: cmake -DTEST_CMAKE_FEATURE=$1 --log-level=verbose ..
# test_option.cmake: cmake -DTEST_CMAKE_FEATURE=$1 -DBUILD_PYTORCH=ON ..
cmake -DTEST_CMAKE_FEATURE=$1 ..
# It can be executed directly on the terminal, no need to execute build.sh, for example: cmake -P test_set.cmake
make
# make install # only used in cmake files with install command

      CMakeLists.txt内容如下：

cmake_minimum_required(VERSION 3.22)
project(cmake_feature_usage)

message("#### current cmake version: $CMAKE_MAJOR_VERSION.$CMAKE_MINOR_VERSION.$CMAKE_PATCH_VERSION")
include(test_$TEST_CMAKE_FEATURE.cmake)
message("==== test finish ====")

      test_add_custom_target.cmake内容为上面的所有测试代码段。

      另外还包括三个目录：include,source,samples,它们都是非常简单的实现，仅用于测试，如下：

      可能的执行结果如下图所示:

      GitHub： https://github.com/fengbingchun/Linux_Code_Test