# CMake 基础

## CMakeLists.txt 文件

CMakeLists.txt 是 CMake 的配置文件，用于定义项目的构建规则、依赖关系、编译选项等。每个 CMake 项目通常都有一个或多个 CMakeLists.txt 文件。

### 文件结构和基本语法

CMakeLists.txt 文件使用一系列的 CMake 指令来描述构建过程。常见的指令包括：

1、指定 CMake 的最低版本要求：

```cmake
cmake_minimum_required(VERSION <version>)

#example
cmake_minimum_required(VERSION 3.10)
```

2、定义项目的名称和使用的编程语言：

```cmake
project(<project_name> [<language>...])

#example
project(MyProject CXX)
```

3、指定要生成的可执行文件和其源文件：

```cmake
add_executable(<target> <source_files>...)

#example
add_executable(Myexe main.cpp other_file.cpp)
```

4、创建一个库（静态库或动态库）及其源文件：

```cmake
add_library(<target> <source_file>...)

#example
add_library(MyLibrary STATIC library_file.cpp)
```

5、链接目标文件与其他库：

```cmake
target_link_libraries(<target> <libraries>...)

#example
target_link_libraries(MyExecutable MyLibrary)
```

6、添加头文件搜索路径：

```cmake
include_directories(<dirs>...)

#example
include_directories(${PROJECT_SOURCE_DIR}/include)
```

7、设置变量的值：

```cmake
set(<variable> <value>...)

#example
set(CMAKE_CXX_STANDARD 11)
```

8、设置目标属性：

```cmake
target_include_directories(TARGET target_name
                          [BEFORE | AFTER]
                          [SYSTEM] [PUBLIC | PRIVATE | INTERFACE]
                          [items1...])
#example
target_include_directories(MyExecutable PRIVATE ${PROJECT_SOURCE_DIR}/include)
```

9、安装规则：

```cmake
install(TARGETS target1 [target2 ...]
        [RUNTIME DESTINATION dir]
        [LIBRARY DESTINATION dir]
        [ARCHIVE DESTINATION dir]
        [INCLUDES DESTINATION [dir ...]]
        [PRIVATE_HEADER DESTINATION dir]
        [PUBLIC_HEADER DESTINATION dir])

#example
install(TARGETS MyExecutable RUNTIME DESTINATION bin)
```

10、条件语句 (if, elseif, else, endif 命令)

```cmake
if(expression)
  # Commands
elseif(expression)
  # Commands
else()
  # Commands
endif()

#example
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
  message("Debug build")
endif()
```

## 变量和缓存

CMake 使用变量来存储和传递信息，这些变量可以在 CMakeLists.txt 文件中定义和使用。变量可以分为普通变量和缓存变量。

### 变量定义与使用

**定义变量：**

```cmake
set(MY_VAR "Hello World")
```

**使用变量：**

```cmake
message(STATUS "Variable MY_VAR is ${MY_VAR}")
```

### 缓存变量

缓存变量存储在 CMake 的缓存文件中，用户可以在 CMake 配置时修改这些值。缓存变量通常用于用户输入的设置，例如编译选项和路径。

**定义缓存变量：**

```cmake
set(MY_CACHE_VAR "DefaultValue" CACHE STRING "A cache variable")
```

**使用缓存变量：**

```cmake
message(STATUS "Cache variable MY_CACHE_VAR is ${MY_CACHE_VAR}")
```

## 查找库和包

CMake 可以通过 **find_package()** 指令自动检测和配置外部库和包。

常用于查找系统安装的库或第三方库。

### find_package() 指令

基本用法：

```cmake
find_package(Boost REQUIRED)
```

指定版本：

```cmake
find_package(Boost 1.70 REQUIRED)
```

查找库并指定路径：

```cmake
find_package(OpenCV REQUIRED PATHS /path/to/opencv)
```

使用查找到的库：

```cmake
target_link_libraries(MyExecutable Boost::Boost)
```

设置包含目录和链接目录：

```cmake
include_directories(${Boost_INCLUDE_DIRS})
link_directories(${Boost_LIBRARY_DIRS})
```

### 使用第三方库

假设你想在项目中使用 Boost 库，CMakeLists.txt 文件可能如下所示：

```cmake
cmake_minimum_required(VERSION 3.10)
project(Myproject CXX)

#查找Boost库
find_package(Boost REQUIRED)

#添加源文件
add_executable(MyExe main.cpp)

#链接Boost库
target_link_libraries(MyExe Boost::Boost)
```

### include_directories() 和 target_include_directories()

在 CMake 中，include_directories() 和 target_include_directories() 都用于指定头文件的搜索路径，但它们的作用范围和使用方式有显著区别。

**相同点：**

- 两者都用于添加头文件的搜索路径，编译器会在这些路径中查找 #include 指令中指定的头文件。
- 两者都支持绝对路径和相对路径，相对路径是相对于当前 CMakeLists.txt 文件所在的目录。
- 两者都可以用于指定公共头文件路径（PUBLIC）、私有头文件路径（PRIVATE）或接口头文件路径（INTERFACE）。

**区别：**

| 特性                | `include_directories()`                  | `target_include_directories()`                               |
| :------------------ | :--------------------------------------- | :----------------------------------------------------------- |
| **作用范围**        | 全局作用域，影响所有目标（target）。     | 仅作用于指定的目标（target）。                               |
| **推荐使用场景**    | 适用于简单的项目或旧版 CMake 项目。      | 适用于现代 CMake 项目，推荐优先使用。                        |
| **目标关联性**      | 不直接关联到特定目标，可能影响所有目标。 | 显式关联到特定目标，避免污染其他目标。                       |
| **可维护性**        | 较差，容易导致全局路径污染。             | 较好，路径与目标绑定，逻辑清晰。                             |
| **作用域控制**      | 无法精确控制路径的作用范围。             | 可以通过 `PUBLIC`、`PRIVATE`、`INTERFACE` 精确控制路径的作用范围。 |
| **现代 CMake 推荐** | 不推荐使用，除非有特殊需求。             | 推荐使用，符合现代 CMake 的最佳实践。                        |

## 常用函数

**(1) cmake_minimum_required**

**含义：**设置项目所需的最低cmake版本以及更新策略

**语法：**

cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR])

**使用样例：**

cmake_minimum_required(VERSION 2.8.0)

------

**(2) project**

**含义：**设置项目的名称、版本、编程语言等信息

**语法：**

project(<PROJECT-NAME>

​           [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]

​           [LANGUAGES <language-name>...])

**使用样例：**

project(Demo)

------

**(3) set**

**含义：**设置普通变量、缓存或环境变量的值

**语法：**

set(<variable> <value>... [PARENT_SCOPE])

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

set(ENV{<variable>} [<value>])

**使用样例：**

set(CMAKE_CXX_COMPILER D:/MinGW/bin/g++)

------

**(4) file**

**含义：**定义对文件系统的文件和路径的操作，可以结合Linux指令对文件的操作去理解。

**语法：**

file(READ <filename> <out-var> [...])

file({WRITE | APPEND} <filename> <content>...)

file(MAKE_DIRECTORY [<dir>...])

**使用样例：**

file(WRITE test.txt "Test Write\n" )

------

**(5) option**

**含义：**提供用户可以选择的布尔选项。

**语法：**

option(<variable> "<help_text>" [value])

**使用样例：**

option(TEST_DEBUG "option for debug" OFF)

------

**(6) if…else[if]…endif**

**含义：**这个不用详细介绍了，用法同编程语言中的控制语句

**语法：**

if/else([<condition>])

**使用样例：**

if(WIN32)

  message(STATUS "in Windows System")

elseif(UNIX)

  message(STATUS "in Unix System")

endif()

------

**(7) include_directories**

**含义：**将指定目录添加到编译器的头文件搜索范围

**语法：**

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

**使用样例：**

include_directories(../src/com/include)

------

**(8) link_directories**

**含义：**添加需要链接的共享库(动态链接库)文件路径，相当于g++命令的-L参数，也相当于Linux环境变量设置LD_LIBRARY_PATH

**语法：**

link_directories([AFTER|BEFORE] directory1 [directory2 ...])

**使用样例：**

link_directories(${SOURCE_DIR}/lib)

------

**(9) aux_source_directory**

**含义：**查找指定目录中的所有源文件，将结果存进指定变量名

**语法：**

aux_source_directory(<dir> <variable>)

**使用样例：**

aux_source_directory(../src DIR_SRCS)

------

**(10) add_custom_command**

**含义：**添加自定义构建规则

**语法：**

add_custom_command(OUTPUT output1 [output2 ...]

​                                    COMMAND command1 [ARGS] [args1...]

​                                   [COMMAND command2 [ARGS] [args2...] ...])

**使用样例：**  

add_custom_command(

​                  TARGET  ${_target}

​                  POST_BUILD

​                  COMMAND echo ${_command}

​                  VERBATIM)

------

**(11) add_compile_options**

**含义：**设置编译选项

**语法：**

add_compile_options(<option> ...)

**使用样例：**

add_compile_options(-std=c++11)

------

**(12) add_subdirectory**

**含义：**将子目录添加到构建范围

**语法：**

add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])

**使用样例：**

add_subdirectory(utils)

------

**(13) add_executable**

**含义：**使用指定的源文件来生成目标可执行文件

**语法：**

add_executable(<name> [WIN32] [MACOSX_BUNDLE]

​               [EXCLUDE_FROM_ALL]

​               [source1] [source2 ...])

**使用样例：**

add_executable(main main.cpp)

------

**(14) add_dependencies**

**含义：**给编译目标添加依赖的target

**语法：**

add_dependencies(<target> [<target-dependency>]...)

**使用样例：**

add_dependencies(log com_log)

------

**(15) add_library**

**含义：**添加一个库到工程中，指定这个库的源文件

**语法：**

add_library(<name> [STATIC | SHARED | MODULE]

​            [EXCLUDE_FROM_ALL]

​            [<source>...])

**使用样例：**

add_library(opencv_core SHARED IMPORTED)

------

**(16) configure_file**

**含义：**将文件复制到另一个位置并修改其内容。

**语法：**

configure_file(<input> <output>

​               [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |

​                FILE_PERMISSIONS <permissions>...])

**使用样例：**

configure_file(CMakeLists.txt.in download/CMakeLists.txt)

------

**(17) find_package**

**含义：**查找依赖的包名

**语法：**

find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]

​             [REQUIRED] [[COMPONENTS] [components...]])

**使用样例：**

find_package(OpenSSL REQUIRED)

------

**(18) find_library**

**含义：**查找依赖的库

**语法：**

find_library (<VAR> name1 [path1 path2 ...])

**使用样例：**

find_library(LOG_LIB log)

------

**(19) find_path**

**含义：**搜索包含指定文件名的路径

**语法：**

find_path (<VAR> name1 [path1 path2 ...])

**使用样例：**

find_path(_ZeroMQ_ROOT NAMES include/zmq.h)

------

**(20) target_link_libraries**

**含义：**将之前打包的库链接到生成的目标上

**语法：**

target_link_libraries(<target> ... <item>... ...)

**使用样例：**

target_link_libraries(${THREAD_LIB_NAME} pthread)

------

**(21) target_include_directories**

**含义：**指定编译生成目标时，需要使用的目录

**语法：**

target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]

  <INTERFACE|PUBLIC|PRIVATE> [items1...]

  [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

**使用样例：**

target_include_directories(hello_library 

​                                          PUBLIC 

​                                          ${PROJECT_SOURCE_DIR}/include)

------

**(22) target_sources**

**含义：**指定构建目标或其依赖项时要使用的源文件

**语法：**

target_sources(<target>

  <INTERFACE|PUBLIC|PRIVATE> [items1...]

  [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

**使用样例：**

target_sources(main  PRIVATE main.cpp)

------

**(23) target_compile_definitions**

**含义：**在编译目标文件时，指定要用到的编译选项

**语法：**

target_compile_definitions(<target>

  <INTERFACE|PUBLIC|PRIVATE> [items1...]

  [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

**使用样例：**

target_compile_definitions(${PROJECTNAME} PUBLIC ARM7)

------

**(24) message**

**含义：**编译过程添加日志消息

**语法：**

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

**使用样例：**

message(STATUS "sources into a library? ${LIBRARY}")

## 常用的环境变量

--CMAKE_C_COMPILER

指定C编译器

------

--CMAKE_CXX_COMPILER

指定C++编译器

------

--CMAKE_BUILD_TYPE  

指定构建类型，例如Debug, Release

------

--CMAKE_C_FLAGS

指定C编译器配置

------

--CMAKE_CXX_FLAGS

指定C++编译器配置

------

--CMAKE_INSTALL_PREFIX

指定安装的路径前缀

------

--CMAKE_EXE_LINKER_FLAGS  

创建可执行文件时，定义链接器的配置

------

--CMAKE_MODULE_LINKER_FLAGS

创建模块时，定义链接器的配置

------

--CMAKE_BINARY_DIR

构建树顶层的完整路径

------

--PROJECT_BINARY_DIR

构建项目的完整路径

------

--CMAKE_SOURCE_DIR

源代码树顶层的完整路径

------

--PROJECT_SOURCE_DIR

当前项目的顶级源目录

------

--CMAKE_CURRENT_SOURCE_DIR

cmake 当前正在处理的源目录的完整路径

------

--EXECUTABLE_OUTPUT_PATH

生成的可执行文件路径

------

--LIBRARY_OUTPUT_PATH

生成的库路径

------

--BUILD_SHARED_LIBS

通过add_library构建“STATIC/SHARED”库

------

--CMAKE_CURRENT_LIST_FILE

当前正在处理的文件列表的完整路径

------

--CMAKE_CURRENT_LIST_LINE

当前正在处理的文件的行号

------

--CMAKE_MODULE_PATH

提供find_package搜索第三方库时使用的路径

## 示例

场景一：简单应用

```cmake
cmake_minimum_required(VERSION 3.1...3.24)

#项目声明：项目名/版本号/编码语言
project(
  ModernCMakeExample
  VERSION 1.0
  LANGUAGES CXX)

#把源代码添加进构建的目标库
add_library(MyLibExample simple_lib.cpp simple_lib.hpp)

#生成可执行文件
add_executable(MyExample simple_example.cpp)

#设置链接生成的库文件的名称
target_link_libraries(MyExample PRIVATE MyLibExample)
```

场景二，复杂工程--基于开源项目libjsonutils

```cmake
cmake_minimum_required(VERSION 3.13...3.19 FATAL_ERROR)
project(libjsonutils VERSION 1.0.0 LANGUAGES CXX)

#Make sure that custom modules like FindRapidJSON are found
list(INSERT CMAKE_MODULE_PATH 0 ${CMAKE_SOURCE_DIR}/cmake)

# Find system dependencies
set(MIN_BOOST_VERSION 1.65)
find_package(Boost ${MIN_BOOST_VERSION} REQUIRED COMPONENTS regex)

set(MIN_RapidJSON_VERSION 1.1)
find_package(RapidJSON ${MIN_RapidJSON_VERSION} REQUIRED)

# Create target and set properties
add_library(jsonutils
    src/json_utils.cpp
    src/file_utils.h
)

#Add an alias so that library can be used inside the build tree, e.g. when testing
add_library(JSONUtils::jsonutils ALIAS jsonutils)

#Set target properties
target_include_directories(jsonutils
    PUBLIC
        $<INSTALL_INTERFACE:include>
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
    PRIVATE
        ${CMAKE_CURRENT_SOURCE_DIR}/src
)

target_compile_features(jsonutils PRIVATE cxx_auto_type)
target_compile_options(jsonutils PRIVATE
    $<$<OR:$<CXX_COMPILER_ID:Clang>,$<CXX_COMPILER_ID:AppleClang>,$<CXX_COMPILER_ID:GNU>>:
    -Wall -Wextra -Wpedantic>)

target_link_libraries(jsonutils
    PUBLIC
        Boost::headers RapidJSON::RapidJSON
    PRIVATE
        Boost::regex
)
```

推荐目录结构

```
project_root/  
├── CMakeLists.txt          # 主入口 (project(), 添加子目录)  
├── include/                # 公共头文件  
├── src/  
│   ├── CMakeLists.txt      # 源码构建配置  
│   └── ...  
├── tests/
│   └── CMakeLists.txt      # 测试代码构建配置 
│   └── ... 
└── cmake/
│   └── FindMyLib.cmake
└── third_party/   
```


<!-- markdown for nginx, see https://phus.lu -->
<script>
!function(){
	var dom = {
		element: null,
		get: function (o) {
			var obj = Object.create(this)
			obj.element = (typeof o == "object") ? o : document.createElement(o)
			return obj
		},
		add: function (o) {
			var obj = dom.get(o)
			this.element.appendChild(obj.element)
			return obj
		},
		text: function (t) {
			this.element.appendChild(document.createTextNode(t))
			return this
		},
		attr: function (k, v) {
			this.element.setAttribute(k, v)
			return this
		}
	}

	if (!document.head) return
	head = dom.get(document.head)
	head.add('meta').attr('charset', 'utf-8')
	head.add('meta').attr('name', 'viewport').attr('content', 'width=device-width,initial-scale=1')

	if (!document.body) {
		document.write(["<div class=\"container\">",
		"<h3>nginx.conf</h3>",
		"<textarea rows=6 cols=50>",
		"# download markdown.html to /wwwroot",
		"location ~ \\.md$ {",
		"    default_type text/html;",
		"    add_after_body /markdown.html;",
		"}",
		"</textarea>",
		"</div>"].join("\n"))
		return
	}

	var bodytext = document.body.innerHTML
	document.body.innerHTML = ''

	div = dom.get('div').attr('class', 'container')

	div.add('script').attr('src', 'https://cdnjs.cloudflare.com/ajax/libs/marked/0.5.2/marked.min.js').attr('integrity', 'sha256-zFUosuESzULu5P+SZdjRRtBZR8+1u5RZDlbt3Q5KL8U=').attr('crossorigin', 'anonymous')
	div.add('link').attr('rel', 'stylesheet').attr('href', 'https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.1.0/github-markdown-light.min.css').attr('integrity', 'sha256-WQx0Y6LLZeGv3V3NVVge+YIL5MIOt45RPuFdkyNodls=').attr('crossorigin', 'anonymous')

	title = decodeURIComponent(document.location.pathname.replace(/.*\//, '').replace(/\.html$/, ''))
	document.title = '《' + title.replace(/\.md$/, '') + '》'
	tbody = div.add('table').add('tbody')
	tbody.add('tr').add('th').text(title).attr('class', 'octicon-book')
	tbody.add('tr').add('td').add('div').attr('id', 'readme').attr('class', 'markdown-body')

	wait = function (name, callback) {
		var interval = 10; // ms
		window.setTimeout(function() {
			if (window[name]) {
				callback(window[name])
			} else {
				window.setTimeout(arguments.callee, interval)
			}
		}, interval)
	}
	wait('marked', function() {
		document.getElementById("readme").innerHTML = marked.parse(bodytext)
	})

	document.body.appendChild(div.element)
}()
</script>

<style>
body {
	margin: 0;
	font-family: "ubuntu", "Tahoma", "Microsoft YaHei", Arial, Serif;
}
.markdown-body {
	float: left;
	font-family: "ubuntu", "Tahoma", "Microsoft YaHei", Arial, Serif;
}
.container {
	padding-right: 15px;
	padding-left: 15px;
	margin-right: auto;
	margin-left: auto;
}
@media (min-width: 768px) {
	.container {
		max-width: 80%;
	}
}
@media (min-width: 992px) {
	.container {
		max-width: 70%;
	}
}
@media (min-width: 1200px) {
	.container {
		max-width: 60%;
	}
}
table {
	width: 100%;
	max-width: 100%;
	margin-bottom: 20px;
	border: 1px solid #ddd;
	padding: 0;
	border-collapse: collapse;
}
table th {
	font-size: 14px;
}
table tr {
	border: 1px solid #ddd;
	padding: 5px;
}
table th, table td {
	border: 1px solid #ddd;
	font-size: 14px;
	line-height: 20px;
	padding: 3px;
	text-align: left;
}
.octicon-book {
	background-position: center left;
	background-repeat: no-repeat;
	padding-left: 20px;
	background-image: url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16'%3E%3Cpath d='M3,5 L7,5 L7,6 L3,6 L3,5 L3,5 Z M3,8 L7,8 L7,7 L3,7 L3,8 L3,8 Z M3,10 L7,10 L7,9 L3,9 L3,10 L3,10 Z M14,5 L10,5 L10,6 L14,6 L14,5 L14,5 Z M14,7 L10,7 L10,8 L14,8 L14,7 L14,7 Z M14,9 L10,9 L10,10 L14,10 L14,9 L14,9 Z M16,3 L16,12 C16,12.55 15.55,13 15,13 L9.5,13 L8.5,14 L7.5,13 L2,13 C1.45,13 1,12.55 1,12 L1,3 C1,2.45 1.45,2 2,2 L7.5,2 L8.5,3 L9.5,2 L15,2 C15.55,2 16,2.45 16,3 L16,3 Z M8,3.5 L7.5,3 L2,3 L2,12 L8,12 L8,3.5 L8,3.5 Z M15,3 L9.5,3 L9,3.5 L9,12 L15,12 L15,3 L15,3 Z' /%3E%3C/svg%3E");
}
</style>