CMake 常用指令

范式

CMakeLists.txt 中，CMake 指令遵循 指令(参数1 参数2...) 。其中，参数分割符可以是 空格 也可以是 分号; 。

指令名称大小写无关，但参数和变量大小写相关

变量使用 ${} 方式取值，但是在 if 等控制语句中，直接使用变量名。

set(HELLO hello.cpp)
add_executable(hello main.cpp hello.cpp)
ADD_EXECUTABLE(hello main.cpp ${HELLO})

环境&工程配置

cmake_minimum_required

cmake_minimum_required(VERSION <versionNumber> [FATAL_ERROR])

// 设置支持的最小 CMake 版本为 2.8.3
cmake_minimum_required(VERSION 2.8.3)

project

project(<projectName>[, VERSION <version>] [DESCRIPTION 描述字符串] )

// 指定项目名称
project(Hello)
project(myproject, VERSION 1.0.0 DESCRIPTION "my first project" )

file

file(GLOB <variableName> [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] [<globbing-expressions>...])

// eg
file(GLOB source_list "src/*.cpp")

添加头文件搜索路径

include_directories([AFTER|BEFORE] [SYSTEM] dir1 dir2...)

link_directories

向工程添加特定的库文件搜索路径。相当于 -L 参数

link_directories(dir1 dir2...)

add_compile_options

添加编译参数

add_compile_options(<option>...)

// eg
add_compile_options(-Wall -std=c++11 -o2)

add_executable

当指定 EXCLUDE_FROM_ALL 参数时，要构建的 target 就会被排除在 all target 列表之外， 这样当执行 make 或 make all 时， 该 target 不会被编译

add_executable(name [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [source1] [source2] ...)

// 配置可执行文件
add_executable(myMain 1.c 2.c)

相关变量	含义
CMAKE_RUNTIME_OUTPUT_DIRECTORY	该变量指定了生成的可执行文件的保存路径

add_library

add_library(<name> [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [<source>...])

// 添加一个库文件的target, 包含静态库、动态库等
add_library(hello_library STATIC src/Hello.cpp)

相关变量	含义
ARCHIVE_OUTPUT_DIRECTORY	修改静态库的输出路径
LIBRARY_OUTPUT_DIRECTORY	修改动态库的输出路径
ARCHIVE_OUTPUT_NAME	修改静态库的输出名称
LIBRARY_OUTPUT_NAME	修改动态库的输出名称

target_include_directories

target_include_directories(<target> [SYSTEM] [AFTER|BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...])

// 当编译给定 target 时，该命令用于指定要包含的路径名。
// 当使用 gcc 编译器编译目标时，就会使用 -I 选项指定该命令添加的路径， 使用 -I directory/include
// 如果 target 是可执行文件，建议使用 PRIVATE， 如果 target 是动态或静态库， 建议使用 PUBLIC
target_include_directories(mylib PUBLIC include/1.h PUBLIC ${PROJECT_SOURCE_DIR}/include)
target_include_directories(mytarget PRIVATE ${PROJECT_SOURCE_DIR}/include)

target_link_libraries

为 target 添加需要连接的共享库。相当于 -l 参数

target_link_libraries(<target> <PRIVATE|PUBLIC|INTERFACE> <item>...)

// 指定一个target的链接阶段的依赖库
target_link_libraries( hello_binary PRIVATE hello_library)

aux_source_directory

发现一个目录下所有的源代码文件并将列表存储在一个变量中。这个指令临时被用来自动构建源文件列表

aux_source_directory(<dir> <VARIABLE>)

// eg
aux_source_directory(. SRC)  // 定义 SRC 变量，值为当前目录先所有的源码文件
add_executable(main ${SRC})

install 相关

安装指定的target到指定目录内

install(TARGETS targets ... [EXPORT <export-name>]
        [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>]
        
        [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
         [DESTINATION <dir>]
         [PERMISSIONS permissions...]
         [CONFIGURATIONS [Debug|Release|...]]
         [COMPONENT <component>]
         [NAMELINK_COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
         [NAMELINK_ONLY|NAMELINK_SKIP]
        ] [...]
        
        [INCLUDES DESTINATION [<dir> ...]]
)

// eg
install(TARGETS mylib LIBRARY DESTINATION lib)
install(TARGETS mybin RUNTIME DESTINATION bin)

安装指定的目录（包含目录内的文件）到指定目录

install(DIRECTORY dirs...
        TYPE <type> | DESTINATION <dir>
        [FILE_PERMISSIONS permissions...]
        [DIRECTORY_PERMISSIONS permissions...]
        [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
        [CONFIGURATIONS [Debug|Release|...]]
        [COMPONENT <component>] [EXCLUDE_FROM_ALL]
        [FILES_MATCHING]
        [[PATTERN <pattern> | REGEX <regex>]
         [EXCLUDE] [PERMISSIONS permissions...]] [...]
)

// eg
install(DIRECTORY ${PROJECT_SOURCE_DIR}/include/ DESTINATION include)

安装指定的文件到指定目录

install(<FILES|PROGRAMS> files...
        TYPE <type> | DESTINATION <dir>
        [PERMISSIONS permissions...]
        [CONFIGURATIONS [Debug|Release|...]]
        [COMPONENT <component>]
        [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL]
)

// eg
install(FILES cmake.config DESTINATION etc)

指定编译给定的 target 时，要定义的宏名称

target_compile_definitions(<target>
                           <INTERFACE|PUBLIC|PRIVATE> [items1...]
                           [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]
)

// eg
// source code
#include <iostream>
int main() {
#ifdef CHINA
	std::cout << "I Love CHINA" << std::endl;
#endif
	return 0;
}

cmake_minimum_required(VERSION 3.10.2)
add_executable(myTarget main.c)
target_compile_definations(myTarget PRIVATE CHINA)

add_subdirectory

该命令用于增加一个构建的子目录。 注意执行的数据流： CMake 命令会执行完子目录中的CMakeLists.txt文件之后，再执行后面的命令。

add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
// eg
cmake_minimum_required(VERSION 3.10.2)
project(example)
add_subdirectory(subdir1)
add_subdirectory(subdir2)

set_target_properties

用于设置给定target的一些属性值，类似于类对象的成员变量的值。 它们会影响到该target如何被构建的

set_target_properties(target1 target2 ...
                      PROPERTIES prop1 value1
                      prop2 value2 ...
)

// eg
add_executable(hello_main main.cpp)
set_target_properties(hello_main PROPERTIES CXX_STANDARD 11)

target_compile_features

target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])

// eg
add_executable(hello_main main.cpp)
target_compile_features(hello_main PRIVATE cxx_std_11)

工具

set

set(<variableName> <value>... CACHE <type> <docstring> [FORCE])

// 设置变量及名称
set(SRC sayHello.cpp hello.cpp)

set_property

set_property(<scope> [APPEND] [APPEND_STRING] PROPERTY <name> <value>)

// scope 可能的取值为
GLOBAL
DIRECTORY [<dir>]
TARGET    [<target1> ...]
SOURCE    [<src1> ...] [DIRECTORY <dirs> ...] | [TARGET_DIRECTORY <targets> ...]
INSTALL   [<file1> ...]
TEST      [<test1> ...]
CACHE     [<entry1> ...]

// eg
set_property(TARGET hello_main PROPERTY CXX_STANDARD 11)

include

include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>] [NO_POLICY_SCOPE])

// 导入文件或模块中的 CMake 代码, 类似于 C 语言中的 include 功能
// 这里导入 CheckCXXCompilerFlag 模块， 并运行该模块内的 CHECK_CXX_COMPILER_FLAG 命令。
include(CheckCXXCompilerFlag)
CHECK_CXX_COMPILER_FLAG("-std=c++11" COMPILER_SUPPORTS_CXX11)
CHECK_CXX_COMPILER_FLAG("-std=c++0x" COMPILER_SUPPORTS_CXX0X)

message([<mode>] "message text" ...)

// mode 的可能取值为
FATAL_ERROR  // CMake ERROR, 遇到该错误，CMake 直接停止处理
WARNING      // 警告信息
STATUS       // 普通状态信息

// 打印日志消息
message(STATUS "hello, world.")
set(NAME xiaoming)
messaeg(STATUS "hello, ${NAME}")

CMake 常用变量

名称	含义
CMAKE_SOURCE_DIR	源码的根目录，也就是最 top 层 CMakeLists.txt 文件存在的目录
CMAKE_BINARY_DIR	编译的 binary 的根目录，也就是运行 CMake 时的目录，一般就是 build 目录
CMAKE_CURRENT_SOURCE_DIR	当前正在运行的 CMakeLists.txt 文件的目录
CMAKE_CURRENT_BINARY_DIR	当前正处于的编译目录，例如如果正在运行 src 目录下的 CMakeLists.txt， 该变量通常为 build/src 目录
CMAKE_CXX_FLAGS 和 CMAKE_C_FLAGS	当使用 g++ (或 gcc)编译文件时，用于设置 compiler flags, 也就是宏定义
CMAKE_CXX_STANDARD	该变量用于编译 target 时，使用的 C++ 标准，支持 98, 11, 14, 17, 20, 23. 该变量的作用原理是：用于初始化 target 的CXX_STANDARD 属性。
CMAKE_BUILD_TYPE	编译类型。一般发布时使用 release，调试时使用 debug

// 在 CMAKE_CXX_FLAGS 编译选项后追加 -std=c++11
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")

// 设置编译类型为 debug
set(CMAKE_BUILD_TYPE Debug)