CMake学习（2）—— 语法

一、CMakeLists.txt

        CMake的所有语句都写在一个CMakeLists.txt的文件中，文件编写完成后，可以直接使用cmake命令进行运行，注： 要指向CMakeLists.txt所在的目录。运行之后就会产生相关的工程构建文件，比如：Makefile、Visual Studio的工程文件等，然后再根据不同的构建文件进行构建编译工程。

二、命令

CMake命令官方文档

1、脚本命令

        这些命令总是有效的。

cmake_minimum_required

说明： 指定CMake的最低版本要求。一般放在项目主CMakeLists.txt文件的首行。
示例： cmake_minimum_required(VERSION 3.18.0)

file

说明： 文件操作命令，专门用于需要访问文件系统的文件和路径操作。子命令有：

• 读操作，READ、STRINGS、HASH、TIMESTAMP、GET_RUNTIME_DEPENDENCIES。
• 写操作，WRITE|APPEND、TOUCH|TOUCH_NOCREATE、ENERATE、CONFIGURE。
• 文件系统，GLOB|GLOB_RECURSE、RENAME、REMOVE|REMOVE_RECURSE、MAKE_DIRECTORY、COPY|INSTALL、SIZE、READ_SYMLINK、CREATE_LINK、CHMOD、CHMOD_RECURSE。
• 路径转换，REAL_PATH、RELATIVE_PATH、TO_CMAKE_PATH|TO_NATIVE_PATH。
• 传输操作，DOWNLOAD、UPLOAD。
• 锁操作，LOCK。
• 存档操作，ARCHIVE_CREATE、ARCHIVE_EXTRACT。

示例： file(GLOB SRC_LIST ${test1}/*.cpp ${test2}/*.h ${test3}/*.hpp)

find_package

说明： 引入外部依赖包。CMake官方的包
示例： find_package(Threads)

list

说明： 以分号分隔的字符串列表。子命令有：

• 读操作，LENGTH、GET、JOIN、SUBLIST。
• 查找操作，FIND。
• 修改操作，APPEND、FILTER、INSERT、POP_BACK、POP_FRONT、PREPEND、REMOVE_ITEM、REMOVE_AT、REMOVE_DUPLICATES、TRANSFORM。
• 排序操作，REVERSE、SORT。

示例： list(APPEND SRC_LIST a.cpp b.cpp c.cpp)

set

说明： 设置普通变量，缓存变量或环境变量。
示例：

set(CMAKE_CXX_COMPILER "c++")
set(CMAKE_CXX_STANDARD 11) # 指定C++版本
set(CMAKE_CXX_STANDARD_REQUIRED True)
set(CMAKE_CXX_FLAGS -g -Wall) # 通过空格来分隔多个编译选项，生成的 CMAKE_CXX_FLAGS 字符串是："-g;-Wall"，需要替换将分号替换为空格

include

说明： 从文件或模块加载并运行CMake代码。
示例： include(cmake/common.cmake)

message

说明： 显示消息。可用选项有FATAL_ERROR、SEND_ERROR、WARNING、AUTHOR_WARNING、DEPRECATION、NOTICE（默认）、STATUS、VERBOSE、DEBUG、TRACE。
示例： message(STATUS "hello world!")

option

说明： 定义选项开关，值为ON和OFF，如果不设置值，默认是OFF。
示例：

option(ENABLE_EXAMPLE "是否开启example" ON)
option(ENABLE_TEST "是否开启测试" OFF)

set_property

原型：

set_property(<GLOBAL                      |
              DIRECTORY [<dir>]           |
              TARGET    [<target1> ...]   |
              SOURCE    [<src1> ...]
                        [DIRECTORY <dirs> ...] |
                        [TARGET_DIRECTORY <targets> ...]
              INSTALL   [<file1> ...]     |
              TEST      [<test1> ...]     |
              CACHE     [<entry1> ...]>
             [APPEND] [APPEND_STRING]
             PROPERTY <name> [<value1> ...])

说明： 在指定域中设置一个命名属性。在某个域中对0个或多个对象设置一个属性。
参数：

• 第一个参数决定该属性设置所在的域。它必须为下面中的其中之一：
  GLOBAL，域是唯一的，并且不接特殊的任何名字。
  DIRECTORY，域默认为当前目录，但也可以用全路径或相对路径指定其他的目录（前提是该目录已经被CMake处理）。
  TARGET，域可命名0或多个已经存在的目标。
  SOURCE，域可命名0或多个源文件。注意：源文件属性只对在相同目录下的目标是可见的（CMakeLists.txt）。
  TEST，域可命名0或多个已存在的测试。
  CACHE，域必须命名0或多个已存在条目的cache。
• 必选项PROPERTY后面紧跟着要设置的属性的名字。其他的参数用于构建以分号隔开的列表形式的属性值。
• 如果指定了APPEND选项，则指定的列表将会追加到任何已存在的属性值当中。
• 如果指定了APPEND_STRING选项，则会将值作为字符串追加到任何已存在的属性值。

示例：

set_property(TARGET ${PROJECT_NAME} 
             APPEND_STRING 
             PROPERTY LINK_FLAGS " -Wl,--version-script=${VERSION_SCRIPT}"
             )

给当前项目增加链接选项

2、项目命令

        这些命令仅在CMake项目中可用。

add_compile_definitions

说明： 向源文件的编译中添加预处理器定义。
示例： add_compile_definitions(THREAD_ENABLE=1)

add_definitions

说明： 在编译源文件时添加-D标识。
示例：

add_definitions(-DSYSTEM_WINDOWS) # 增加宏定义SYSTEM_WINDOWS
add_definitions(/utf-8) # 指定默认编码
add_definitions(/WX) # 警告视为错误
add_definitions(-D_CRT_SECURE_NO_WARNINGS) # 屏蔽sscanf等不安全的函数编译警告

add_executable

说明： 使用源文件列表里的文件生成可执行文件。
示例： add_executable(hello ${SRC_LIST})，生成可执行文件hello。

add_library

说明： 使用源文件列表里的文件生成库。
示例：

add_library(hello STATIC ${SRC_LIST}) # 使用SRC_LIST源文件列表里的文件生成一个静态链接libhello.a
add_library(hello SHARED ${SRC_LIST}) # 使用SRC_LIST源文件列表里的文件生成一个动态链接库libhello.so

add_subdirectory

说明： 添加一个子目录并构建该子目录。
示例： add_subdirectory(src)

include_directories

说明： 添加构建的包含目录。注： 使用target_include_directories()命令将包含目录添加到单个目标，并可以将它们传播/导出到依赖项。
示例： include_directories(${PROJECT_SOURCE_DIR}/include ${PROJECT_SOURCE_DIR}/test)

link_directories

说明： 添加链接器将在其中查找库的目录。注： 这个命令很少需要，在有其他选择的情况下应该避免使用。
示例： link_directories(${LIBRARY_OUTPUT_PATH})

project

说明： 指定项目的名称。一般在cmake_minimum_required指令设置后就设置。项目名称存储在变量PROJECT_NAME中。
示例： project(helloworld)

target_link_libraries

说明： 指定链接给定目标和/或其依赖项时使用的库或flags。
示例： target_link_libraries(hello ${LIB1} ${LIB2})

set_target_properties

说明： 设置目标属性。
示例： set_target_properties(hello PROPERTIES 属性名 属性值)。

（1）根据Debug/Release指定目标输出文件后缀

set_target_properties(hello PROPERTIES DEBUG_POSTFIX _d)。
这里设置输出后缀为_d，则目标输出文件名为：hello_d。

三、变量

CMake变量官方文档

1、提供信息的变量（只读）

CMAKE_CURRENT_SOURCE_DIR

说明： 当前正在处理的源目录（CMakeLists.txt所在目录）的路径。

2、改变行为的变量（读写）

CMAKE_BUILD_TYPE

说明： 指定单个配置生成器上的构建类型。值为"Debug"、"Release"、"RelWithDebInfo"、"MinSizeRel"等。
示例： set(CMAKE_BUILD_TYPE "Debug")

CMAKE_MODULE_PATH

说明： 是以分号分隔的列表，在检查CMake自带的默认模块之前，指定通过include()或find_package()命令加载的CMake模块的搜索路径。初始为空。
示例： set(CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH};/opt/QT/5.12")

CMAKE_PREFIX_PATH

说明： 是以分号分隔的列表，指定要由find_package()、find_program()、find_library()、find_file()和find_path()命令搜索的安装前缀。初始为空。
示例： set(CMAKE_PREFIX_PATH "${CMAKE_PREFIX_PATH};/opt/QT/5.12")

CMAKE_INSTALL_PREFIX

说明： 指定安装的路径前缀。例如：值为"/usr/local"等。
示例： set(CMAKE_INSTALL_PREFIX "/usr/local")

3、描述系统的变量（只读）

CMAKE_SYSTEM_NAME

说明： CMake要构建的操作系统的名称。值为"Linux"、"Windows"、"Darwin"等。

4、控制构建的变量（读写）

EXECUTABLE_OUTPUT_PATH

说明： 用于指定可执行文件的输出路径。
示例： set(EXECUTABLE_OUTPUT_PATH ${CMAKE_CURRENT_SOURCE_DIR}/release)

LIBRARY_OUTPUT_PATH

说明： 用于指定库的输出路径。
示例： set(LIBRARY_OUTPUT_PATH ${CMAKE_CURRENT_SOURCE_DIR}/release)

5、语言变量（读写）

CMAKE_CXX_STANDARD

说明： 用于指定C++标准版本。
示例： set(CMAKE_CXX_STANDARD 11)

四、示例

1、根据配置（Debug/Release）构建不同名称的目标文件

# 构建库文件
ADD_LIBRARY(${PROJECT_NAME} STATIC ${src_files})
if(MSVC)
    set_target_properties(${PROJECT_NAME} PROPERTIES OUTPUT_NAME "${PROJECT_NAME}$<$<CONFIG:Debug>:d>")
elseif(NOT "${CMAKE_BUILD_TYPE}" MATCHES "Release")
    set_target_properties(${PROJECT_NAME} PROPERTIES OUTPUT_NAME "${PROJECT_NAME}d")
endif()