# LearnCMake

**Repository Path**: dream_zhou/LearnCMake

## Basic Information

- **Project Name**: LearnCMake
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2018-06-23
- **Last Updated**: 2025-12-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LearnCMake
## CMake
### bool
- `true` :
    `1`, `ON`, `YES`, `true`, `Y` 及 `非零数`
- `false` :
    `0`, `OFF`, `NO`, `false`, `N`, `IGNORE`, `NOTFOUND`, 空字符串， 以`NOTFOUND` 为后缀

### 全局变量
- `BUILD_SHARED_LIBS` 
  true: 动态库
  false: 生产静态库
  
### 定义变量
变量的值始终是 `string` 类型的
变量名大小写敏感 
- 定义
`set(KEY VALUE)`
- 取消
`unset(KEY)`
- 引用变量
`${variable_name}`
- 嵌套
  `${outer_${inner_variable}veriable}`
- 环境变量
  `$ENV{VAR}`

### cmake-variables

#### `PROJECT_SOURCE_DIR`
工程的根目录

#### `CMAKE_CURRENT_SOURCE_DIR`
当前处理的 CMakeLists.txt 所在的路径

#### `PROJECT_BINARY_DIR`
运行cmake命令的目录
通常为`${PROJECT_SOURCE_DIR}/build`

#### `CMAKE_CURRENT_BINARY_DIR`
target 编译目录

#### `CMAKE_CURRENT_LIST_DIR`
CMakeLists.txt 的完整路径
这是当前正在处理的列表文件的目录

变量 CMAKE_CURRENT_SOURCE_DIR 和 CMAKE_CURRENT_LIST_DIR 
可以指代由具有 include 命令的不同文件包括的CMake列表文件的不同目录
例如,如果目录项目中存在CMakeLists.txt并且包含以下指令
```Cmake
include(src/CMakeLists.txt)
```
然后在处理`src/CMakeLists.txt`时,`CMAKE_CURRENT_LIST_DIR`将引用`project/src`,而`CMAKE_CURRENT_SOURCE_DIR`仍然指向外部目录项目.

当您需要找到当前正在处理的 CMakeLists.txt 文件旁边的模板文件或批处理脚本等资源文件时,CMAKE_CURRENT_LIST_DIR 会派上用场.


#### `EXECUTABLE_OUTPUT_PATH`
重新定义目标二进制可执行文件的存放位置

#### `LIBRARY_OUTPUT_PATH`
重新定义目标链接库文件的存放位置

#### `CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY`
If enabled, the Xcode generator will generate only a single Xcode project file for the topmost project() command instead of generating one for every project() command.

#### `PROJECT_NAME`
返回通过 project 命令定义的项目名称


## commands
### `project`
设置的项目名存储在 `PROJECT_NAME`,
同时指定了4个变量
`PROJECT_SOURCE_DIR`, `<PROJECT_NAME>_SOURCE_DIR`
`PROJECT_BINARY_DIR`, `<PROJECT_NAME>_BINARY_DIR`

### `PROJECT_VERSION`
`PROJECT_VERSION`,
`<PROJECT-NAME>_VERSION`

`PROJECT_VERSION_MAJOR`,
`<PROJECT-NAME>_VERSION_MAJOR`

`PROJECT_VERSION_MINOR`,
`<PROJECT-NAME>_VERSION_MINOR`

`PROJECT_VERSION_PATCH`,
`<PROJECT-NAME>_VERSION_PATCH`

`PROJECT_VERSION_TWEAK`,
`<PROJECT-NAME>_VERSION_TWEAK`


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

| -- mode --       |-- desc --|
|(node) or NOTICE  |          |
| STATUS           |          |
| VERBOSE          |          |


### `configure_file`
文件复制到文件中，并在输入文件内容中替换`@VAR@`或`${VAR}`的变量值
```
configure_file(<input> <output>
               [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
               [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
```
input和output假如不指定绝对路径，
则会被默认设置为`CMAKE_CURRENT_SOURCE_DIR`和`CMAKE_CURRENT_BINARY_DIR`

`COPYONLY`      只是复制文件
`ESCAPE_QUOTES` 禁止为"转义
`@ONLY `只允许替换 `@VAR@` 包裹的变量 `${VAR}` 则不会被替换；
`NEWLINE_STYLE <style>` 设置换行符格式
## 
```shell
cmake --help    # 找到生成器 列表
cmake -G Ninja  # 切换生成器 
```
## 单个源文件
recipe-01

```cmake
# CMake 最低版本号要求
cmake_minimum_required(VERSION 3.20 FATAL_ERROR)
# 项目信息
project(recipe-01 LANGUAGES CXX)
# 指定生成目标
add_executable(hello-cmake recipe01.cpp)
```
编译
```shell
mkdir -p build
cd build
cmake ..
cmake --build .
```
也可使用
```shell
cmake -H. -Bbuild
cd build
cmake --build .
```
-H 表示当前目录中搜索根 CMakeLists.txt文件。
-Bbuild 告诉CMake在一个名为build的目录中生成所有的文件。

## 多个文件
recipe-02
```cmake
# CMake 最低版本号要求
cmake_minimum_required(VERSION 3.20 FATAL_ERROR)
# 项目信息
project(Demo2 LANGUAGES CXX)
# 指定生成目标
add_executable(demo2 main.cc MathFunction.cc)
```

## 构建和链接静态库和动态库
recipe-03
- add_library 
  第一个参数是目标名。整个CMakeLists.txt中，可使用相同的名称来引用库。
  生成的库的实际名称将由CMake通过在前面添加前缀lib和适当的扩展名作为后缀来形成。
  生成库是根据第二个参数(STATIC或SHARED)和操作系统确定的。

    STATIC：用于创建静态库
    SHARED：用于创建动态库
    OBJECT：可将给定add_library的列表中的源码编译到目标文件，不将它们归档到静态库中，也不能将它们链接到共享对象中。
    如果需要一次性创建静态库和动态库，那么使用对象库尤其有用
    MODULE：又为DSO组。与SHARED库不同，它们不链接到项目中的任何目标，不过可以进行动态加载。该参数可以用于构建运行时插件。

- target_link_libraries(hello-world message)
   将库链接到可执行文件。
   此命令还确保hello-world可执行文件可以正确地依赖于消息库。
   因此，在消息库链接到hello-world可执行文件之前，需要完成消息库的构建。

```cmake
# CMake 最低版本号要求
cmake_minimum_required(VERSION 3.20 FATAL_ERROR)
# 项目信息
project(recipe-03 LANGUAGES CXX)

add_library(message 
    STATIC
        Message.hpp
        Message.cpp
)
# 指定生成目标
add_executable(hello-world hello-world.cpp)

target_link_libraries(hello-world message)
```

OBJECT 类型
- 引用对象库的表达式
`$<TARGET_OBJECTS:message-objs>`

- 生成2个同名的库
  ```
    add_library(message-shared
      SHARED
        $<TARGET_OBJECTS:message-objs>
        )
    set_target_properties(message-shared
        PROPERTIES
            OUTPUT_NAME "message"
        )
    add_library(message-static
        STATIC
            $<TARGET_OBJECTS:message-objs>
        )
    set_target_properties(message-static
        PROPERTIES
            OUTPUT_NAME "message"
        )
  ```

```cmake
cmake_minimum_required(VERSION 3.20 FATAL_ERROR)

project(recipe-03 LANGUAGES CXX)

add_library(message-objs 
    OBJECT
        Message.hpp
        Message.cpp
)

# this is only needed for older compilers
# but doesn't hurt either to have it
set_target_properties(message-objs
    PROPERTIES
        POSITION_INDEPENDENT_CODE 1 )

add_library(message-shared
    SHARED
        $<TARGET_OBJECTS:message-objs>)
    
add_library(message-static
    STATIC
        $<TARGET_OBJECTS:message-objs>)

add_executable(hello-world hello-world.cpp)

target_link_libraries(hello-world message-static)
```

## 条件语句控制编译
```cmake
cmake_minimum_required(VERSION 3.20 FATAL_ERROR)

project(recipe-04 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 23 CACHE STRING "The C++ standard to use")
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

set(USE_LIBRARY OFF)

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

set(BUILD_SHARED_LIBS OFF)

list(APPEND _source Message.hpp Message.cpp)

if(USE_LIBRARY)
    #add_library will create a static library
    #since BUILD_SHARED_LIBS is OFF
    add_library(message ${_sources})
    add_executable(hello-world hello-world.cpp)
    target_link_libraries(hello-world message)
else()
    add_executable(hello-world hello-world.cpp ${_source})
endif()
```

## 显示选项
```
    option(USE_LIBRARY "Compile sources into a library" OFF)
```
`-D` 
- 传递CLI选项
- 设置任何类型的变量：逻辑、路径

option(<option_variable> "help string" [initial value])
接受三个参数
<option_variable>   该选项的变量的名称。
"help string"       选项的字符串，在CMake的终端或图形用户界面中可见。
[initial value]     默认值，可以是ON或OFF。

cmake_dependent_option(<option> "<help_text>" <value> <depends> <force>)
    定义需要其他选项的选项， 需要包含 `CMakeDependentOption`
    `depends` 为true时， `option` 可用，值为 `value`,
    `depends` 为 false 时， `option` 值为 `force`
`
cmake_dependent_option(USE_FOO "Use Foo" ON "USE_BAR;NOT USE_ZOT" OFF)
`

## 指定编译器

### `CMAKE_<LANG>_COMPILER`
- CMake将语言的编译器存储在变量
- <LANG>是受支持的任何一种语言，对于我们的目的是CXX、C或Fortran
```bash
# 使用 -D 选项 
cmake -D CMAKE_CXX_COMPILER=clang++
# 通过到处环境选项
env CXX=clang++ cmake ..
```

### `CMAKE_<LANG>_COMPILER_LOADED`
- 如果为项目启用了语言<LANG>，则将设置为TRUE

### `--system-information` 
- 把系统信息存储到文件
```bash
cmake --system-information information.txt
```

### 指定构建类型
- Debug            调试版本
- Release          正式版本
- RelWithDebInfo   正式版本含有调试信息
- MinSizeRel       最小体积版本

## 检测外部库和程序

### 检测`Eigen`库

07-recipe

```shell
# Mac 下安装 OpenMP
brew install libomp

# Mac 下安装 Eigen3
brew install eigen
```

## 配置时和构建时的操作

![工作流程和对应的时序](00-images/workflow.png)

### 平台无关的文件操作
`add_custom_target`

使用-E标志可以以与操作系统无关的方式，运行许多公共操作。
运行cmake -E或cmake -E help可以获得特定操作系统的完整列表


```
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...]])
```
增加一个没有输出的目标，使得它总是被构建
- ALL   表明该目标会被添加到默认的构建目标，使得它每次都被运行
- COMMAND 指定要在构建时执行的命令
- DEPENDS 指定命令所依赖的文件
- COMMENT 在构建时执行命令之前显示给定消息
- WORKING_DIRECTORY：使用给定的当前工作目录执行命令。
  如果它是相对路径，它将相对于对应于当前源目录的构建树目录
- BYPRODUCTS：指定命令预期产生的文件



```cmake
add_custom_target(unpack-eigen      # 引入了一个名为unpack-eigen的目标
  ALL                               # 传递了ALL参数，目标将始终被执行
  COMMAND ${CMAKE_COMMAND} -E tar xzf ${CMAKE_CURRENT_SOURCE_DIR}/eigen-3.4.0.tar.bz2

  # 工作目录
  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}

  # 指定CMake在执行自定义目标时输出什么样的消息
  COMMENT "Unpacking Eigen3 in ${CMAKE_CURRENT_BINARY_DIR}/eigen-3.4.0"

  # 复制 目录
  COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/config 
    ${CMAKE_CURRENT_BINARY_DIR}/etc

  # 复制文件
  COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/log.txt 
    ${CMAKE_CURRENT_BINARY_DIR}/etc
  )
```

### 配置时运行自定义命令
参见 chapter-5-02
`execute_process` 命令将从当前正在执行的CMake进程中派生一个或多个子进程，从而提供了在配置项目时运行任意命令的方法。可以在一次调用execute_process时执行多个命令。但请注意，每个命令的输出将通过管道传输到下一个命令中。
该命令接受多个参数:
- `WORKING_DIRECTORY`，指定应该在哪个目录中执行命令
- `RESULT_VARIABLE` 将包含进程运行的结果。这要么是一个整数，表示执行成功，要么是一个带有错误条件的字符串
- `OUTPUT_VARIABLE` `ERROR_VARIABLE` 执行命令的标准输出和标准错误
- `INPUT_FILE`  标准输入重定向的文件名
- `OUTPUT_FILE` 标准输出重定向的文件名
- `ERROR_FILE`  标准错误重定向的文件名