CMake中target_precompile_headers的使用

Posted 2023-03-03 fengbingchun

      CMake中的target_precompile_headers命令用于添加要预编译的头文件列表，其格式如下：

target_precompile_headers(<target>
  <INTERFACE|PUBLIC|PRIVATE> [header1...]
  [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...]) # 1
target_precompile_headers(<target> REUSE_FROM <other_target>) # 2

      预编译头文件可以通过创建一些头文件的部分处理版本(partially processed version),然后在编译期间使用该版本而不是重复解析原始头文件来加快编译速度。

      1. 该命令将头文件添加到<target>的PRECOMPILE_HEADERS和/或INTERFACE_PRECOMPILE_HEADERS目标属性中。命名的<target>必须是由add_executable或add_library等命令创建，并且不能是ALIAS target。
      需要INTERFACE, PUBLIC和PRIVATE关键字来指定以下参数的范围：PRIVATE和PUBLIC items将填充<target>的PRECOMPILE_HEADERS属性。PUBLIC和INTERFACE items将填充<target>的INTERFACE_PRECOMPILE_HEADERS属性(IMPORTED targets仅支持INTERFACE items)。对相同<target>的重复调用将按所调用的顺序追加items。
      Projects通常应避免对要导出的targets使用PUBLIC或INTERFACE, 或者至少应使用$<BUILD_INTERFACE:...>生成器表达式(generator expression)来防止预编译头(precompile headers)出现在已安装的导出target中。target的使用者(consumers)通常应该控制他们使用的预编译头，而不是被使用的targets强加给他们的预编译头(因为预编译头通常不是使用要求(usage requirement))。
      头文件列表用于生成名为cmake_pch.h|xx的头文件，该文件用于生成预编译头文件(.pch、.gch、.pchi)工件(artifact)。cmake_pch.h|xx头文件将被强制包含(-include表示GCC，/FI表示MSVC），因此源文件不需要#include "pch.h"
      用尖括号(例如<unordered_map>)或显式双引号(例如[["other_header.h"]])指定的头文件名将按原样处理，并且包含目录必须可供编译器查找。其它头文件名(例如 project_header.h)被解释为相对于当前源目录(例如CMAKE_CURRENT_SOURCE_DIR)，并将包含在绝对路径中.
      target_precompile_headers命令的参数可以使用语法为$<...>的生成器表达式

add_library(add source/add.cpp)
target_include_directories(add PUBLIC include)
target_precompile_headers(add PRIVATE include/add.hpp)

get_target_property(var add PRECOMPILE_HEADERS)
message("var: $var") # var: /home/spring/GitCode/Linux_Code_Test/Samples_CMake/messy_usage/include/add.hpp

     执行以上测试代码，由于有target_precompile_headers命令，将会在build/CMakeFiles/add.dir目录下，会生成cmake_pch.hxx文件，其内容如下：

/* generated by CMake */

#pragma GCC system_header
#ifdef __cplusplus
#include "/home/spring/GitCode/Linux_Code_Test/Samples_CMake/messy_usage/include/add.hpp"
#endif // __cplusplus

      2. 该签名可用于指定一个target重用另一个target中的预编译头文件工件(artifact)，而不是生成自己的.
      此表单(form)将PRECOMPILE_HEADERS_REUSE_FROM属性设置为<other_target>并添加依赖关系，以便<target>依赖于<other_target>。如果在<target>使用REUSE_FROM表单时已设置PRECOMPILE_HEADERS属性，则CMake将停止并显示错误。

add_library(add source/add.cpp)
target_include_directories(add PUBLIC include)
target_precompile_headers(add PRIVATE <iostream> <vector>)

add_executable(main samples/sample_add.cpp)
target_include_directories(main PUBLIC include)
target_link_libraries(main add)
target_precompile_headers(main REUSE_FROM add)
# should not cause problems if configured multiple times
target_precompile_headers(main REUSE_FROM add)

get_target_property(var main PRECOMPILE_HEADERS_REUSE_FROM)
message("var: $var") # var: add

      执行以上测试代码，在build/CMakeFiles/add.dir目录下生成的cmake_pch.hxx文件，其内容如下：

/* generated by CMake */

#pragma GCC system_header
#ifdef __cplusplus
#include <iostream>
#include <vector>
#endif // __cplusplus

      在build/CMakeFiles/main.dir目录下的flags.make文件内容变为：

# CMAKE generated file: DO NOT EDIT!
# Generated by "Unix Makefiles" Generator, CMake Version 3.22

# compile CXX with /usr/bin/c++
CXX_DEFINES = 

CXX_INCLUDES = -I/home/spring/GitCode/Linux_Code_Test/Samples_CMake/messy_usage/include

CXX_FLAGS = 

# PCH options: CMakeFiles/main.dir/samples/sample_add.cpp.o_OPTIONS = -Winvalid-pch;-include;/home/spring/GitCode/Linux_Code_Test/Samples_CMake/messy_usage/build/CMakeFiles/add.dir/cmake_pch.hxx

      若要禁用特定target的预编译标头,参阅DISABLE_PRECOMPILE_HEADERS target属性。
      若要防止在编译特定源文件时使用预编译标头，参阅SKIP_PRECOMPILE_HEADERS源文件属性。

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

      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 link_libraries target_link_libraries install \\
		target_sources add_custom_command add_custom_target \\
		add_subdirectory aux_source_directory \\
		set_property set_target_properties define_property \\
		add_definitions target_compile_definitions target_compile_features \\
		add_compile_options target_include_directories link_directories \\
		add_link_options target_precompile_headers)

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_target_precompile_headers.cmake内容为上面的所有测试代码段

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

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

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