# cmake-tutorial

**Repository Path**: demon0511/cmake-tutorial

## Basic Information

- **Project Name**: cmake-tutorial
- **Description**: CMake学习^^
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-07-08
- **Last Updated**: 2023-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: cmake, Cpp

## README

# CMake学习

[TOC]

# 0 准备

## 0.1 实验环境

- 主机：Windows

- 命令行：WSL（Windows Subsystem for Linux）, Ubuntu-20.04

- 依赖：Cmake3.20.0（构建工具），gcc9.4.0（编译工具）

  ```bash
  # Cmake3.20.0 (Unbuntu22版本会自动安装最新版，但20版本需要手动安装)
  cd $HOME
  sudo apt update
  sudo apt install -y libssl-dev
  wget https://github.com/Kitware/CMake/releases/download/v3.20.0/cmake-3.20.0-linux-x86_64.tar.gz
  tar -xzvf cmake-3.20.0-linux-x86_64.tar.gz
  echo 'export PATH="$HOME/cmake-3.20.0-linux-x86_64/bin:$PATH"' >> ~/.bashrc
  source ~/.bashrc
  cmake --version
  # gcc
  sudo apt-get install gcc
  ```

## 0.2 教程链接

[CMake实践应用专题 - 知乎 (zhihu.com)](https://www.zhihu.com/column/c_1369781372333240320) 

[CMake 良心教程，教你从入门到入魂 - 知乎 (zhihu.com)](https://zhuanlan.zhihu.com/p/500002865) 

# 1 CMake构建

> [CMake应用：基础篇 - 知乎 (zhihu.com)](https://zhuanlan.zhihu.com/p/367808125) 
>
> [CMake 良心教程，教你从入门到入魂 - 知乎 (zhihu.com)](https://zhuanlan.zhihu.com/p/500002865) 
>
> [冷风 - 知乎 (zhihu.com)](https://www.zhihu.com/people/sprout37/posts) 

## 1.1 CMake/Makefile/gcc的关系

<img src="assets/cmake_makefile_gcc.png" width="60%">

- gcc（GNU Compiler Collection）将源文件编译（Compile）成可执行文件或者库文件
- 当需要编译的东西很多时，需要说明先编译什么，后编译什么，这个过程称为构建（Build）。常用的工具是make，对应的定义构建过程的文件为`Makefile`
- 由于编写Makefile对于大型项目又比较复杂，通过CMake就可以使用更加简洁的语法定义构建的流程，CMake定义构建过程的文件为`CMakeLists.txt`

## 1.2 cmake命令

- CMake提供cmake、ctest和cpack三个命令行工具分别负责构建、测试和打包。本文只介绍cmake命令，通过`cmake --help`可以看到cmake命令的使用方法，以下列举常见使用方法和可选参数：

- Usage（3种方法）

  ```bash
  cmake [options] <path-to-source>
  cmake [options] <path-to-existing-build>
  cmake [options] -S <path-to-source> -B <path-to-build>
  ```

  - Specify a source directory to (re-)generate a build system for it in the current working directory.
  - Specify an existing build directory to re-generate its build system.

- Options

  | 参数                            | 含义                                                     |
  | ------------------------------- | -------------------------------------------------------- |
  | -S \<path-to-source\>           | 指定源文件根目录，必须包含一个CMakeLists.txt文件         |
  | -B \<path-to-build\>            | 指定构建目录，构建生成的中间文件和目标文件的生成路径     |
  | -D \<var\>[:\<type\>]=\<value\> | 指定变量， -D后面的空格可以省略                          |
  | -G \<generator-name\>           | 指定编译器，系统所有可用编译器在`cmake --help`的末尾显式 |
  | --build \<dir\>                 | 执行构建，Build a CMake-generated project binary tree.   |

## 1.3 CMake使用流程

1. 生成构建系统（buildsystem，比如make工具对应的Makefile）

   ```bash
   cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DAUTHOR=RealCoolEngineer
   ```

   - `-S .`：指明使用当前目录`.`作为源文件目录，其中包含`CMakeLists.txt`文件
   - `-B build`：使用`build`目录作为构建目录，执行完成后，在项目的根目录下会创建build目录，其中生成了`Makefile`文件。这里创建了一个 build 目录存放编译产物，可以避免编译产物与代码文件混在一起，这种叫做外部构建；还有一种内部构建，即直接在项目根目录下进行构建系统与编译，会使得项目文件很混乱，一般直接用外部构建即可。 
   - 设定变量`CMAKE_BUILD_TYPE`的值为`Debug`，变量`AUTHOR`的值为`RealCoolEngineer`

2. 执行构建（比如make），生成目标文件

   - 可以直接使用cmake命令：

     ```bash
     cmake --build build
     ```

   - 也可以使用等价的make命令：

     ```bash
     cd build && make && cd ..
     ```

3. 执行测试、安装或打包

## 1.4 build目录介绍

- build 目录用来存放 cmake 构建和编译的产物，大致如下

  ```txt
  build/
  	CMakeFiles/
  	lib/ 如果有库就会生成
  	cmake_install.cmake
  	CMakeCache.txt
  	demo 即CMakeLists.txt中设置的project名称
  	config.h 即CMakeLists.txt中设置的configure_file名称
  	Makefile
  ```

  - 其中
    - `lib/`文件夹存放库文件
    - `CMakeCache.txt` 文件缓存变量
    - `demo`是生成的执行文件，通过该文件运行程序
    - `config.h` 是用于配置信息的头文件，是 cmake 根据 `config.h.in` 文件自动生成的。
    - `Makefile` 是 cmake 根据顶级 CMakeLists.txt 生成的构建文件，通过该文件可以对整个项目进行编译。

- 由于CMake会缓存信息，因此重复运行`cmake -B build` 时就可以直接用缓存的值，就不需要重新检测编译器、检测编译特性是否支持C++17等信息。但有时候外部的情况有所更新（比如编译器卸载了，CMake却还是指向原来的地址），这时候 CMake 里缓存的却是旧的值，会导致一系列问题。

  - 最简单的方法就是删除build文件夹然后重新`cmake -B build`
    - Linux：rm -rf build
    - Windows：rd /s /q build
  - 删 build 虽然彻底，也会导致编译的中间结果（`.o`文件）都没了，重新编译要花费很长时间。如果只想清除缓存，不想从头重新编译，可以只删除 `CMakeCache.txt` 这个文件，因为它里面装的就是缓存的变量，删了他就可以让 CMake 强制重新检测一遍所有库和编译器。 

- p.s. 90%的CMake错误都是缓存未更新导致的！

## 1.5 编码1：构建最小项目

- 项目结构

  ```txt
  |_ cmake-tutorial/
  	|_ 1/
  		CMakeLists.txt
  		main.cpp
  	...
  ```

- main.cpp

  ```cpp
  #include <iostream>
  
  int main() {
    std::cout << "Hello CMake!" << std::endl;
    return 0;
  }
  ```

- CmakeList.txt

  ```cmake
  cmake_minimum_required(VERSION 3.20)
  
  # set the project name
  project(demo)
  
  # add the executable
  add_executable(demo main.cpp)
  ```

- 构建与执行

  ```bash
  cd 1 && cmake -B build && cmake --build build && build/demo && cd ..
  ```

# 2 CMake语法

> [CMake应用：核心语法篇 - 知乎 (zhihu.com)](https://zhuanlan.zhihu.com/p/368701263) 
>
> [CMake 良心教程，教你从入门到入魂 - 知乎 (zhihu.com)](https://zhuanlan.zhihu.com/p/500002865) 
>
> [CMake 入门实战 | HaHack](https://www.hahack.com/codes/cmake/) 

## 2.1 CMake命令类型

CMake语言有3种命令类型：

1. 脚本命令（[Scripting Commands](https://cmake.org/cmake/help/v3.21/manual/cmake-commands.7.html#id3)）：always available. 
   - 例如`if`、`else`等命令
2. 项目配置命令（[Project Commands](https://cmake.org/cmake/help/v3.21/manual/cmake-commands.7.html#id4)）：available only in CMake projects. 
   - 例如`add_executable`、`include_directories `、`set_target_properties `等命令
3. 测试命令（[CTest Commands](https://cmake.org/cmake/help/v3.21/manual/cmake-commands.7.html#id5)）：available only in CTest scripts. 
   - 都是`ctest_`开头的命令

## 2.2 CMake文件类型

CMake语言在项目配置中组织为3种源文件类型：

1. 目录：`CMakeLists.txt`，针对的是一个目录，描述如何针对目录（Source tree）生成构建系统，会用到项目配置命令；
2. 脚本：`<script>.cmake`，就是一个CMake语言的脚本文件，可使用`cmake -P`直接执行，只能包含脚本命令；
3. 模块：`<module>.cmake`，实现一些模块化的功能，可以被前面两者包含，比如`include(CTest)`启用测试功能。

## 2.3 CMake语法

- 注释

  - 行注释：`#...`
  - 块注释：`#[[...]]`，内容可以有多行。

- 常量

  1. ON、YES、TRUE、Y和非0值均被视为`True`；
  2. 0、OFF、NO、FALSE、N、IGNORE、空字符串、NOTFOUND、及以"-NOTFOUND"结尾的字符串均视为`False`；
  3. 对于变量，只要其值不是常量中为False的情形，则均视为True。 

- 变量

  - 使用`set`和`unset`命令设置或者取消设置变量。主要有以下3类变量：

  - 一般变量：设置的变量可以是字符串、列表、数字、布尔值等，比如：

    ```cmake
    # Set variable
    set(AUTHOR_NAME Farmer)
    set(AUTHOR "Farmer Li")
    set(AUTHOR Farmer\ Li)
    
    # Set list
    set(SLOGAN_ARR To be)   # Saved as "To;be"
    set(SLOGAN_ARR To;be)
    set(SLOGAN_ARR "To;be")
    
    set(NUM 30)   # Saved as string, but can compare with other number string
    set(FLAG ON)  # Bool value
    ```

    - 要点：
      1. 如果要设置的变量值包含空格，则需要使用双引号或者使用"\"转义，否则可以省略双引号；
      2. 如果设置多个值或者字符串值的中间有";"，则保存成list，同样是以";"分割的字符串；
      3. 变量可以被list命令操作，单个值的变量相当于只有一个元素的列表；
      4. 引用变量：`${<variable>}`，在`if()`条件判断中可以简化为只用变量名`<variable>`。

  - Cache变量（缓存条目，cache entries）：主要是为了提供用户配置选项（比如编译开关），如果用户没有指定，则使用默认值。

    - 设置： `set(<variable> <value>... CACHE <type> <docstring> [FORCE])`，例如：

      ```cmake
      # set(<variable> <value>... CACHE <type> <docstring> [FORCE])
      set(CACHE_VAR "Default cache value" CACHE STRING "A sample for cache variable")
      ```

    - 引用：`$CACHE{<varialbe>}`。
    - 要点：Cache变量会被保存在构建目录下的CMakeCache.txt中，缓存起来之后是不变的，除非重新配置更新；

  - 环境变量：

    - 设置：`set(ENV{<variable>} [<value>])`，例如：

      ```cmake
      set(ENV{ENV_VAR} "$ENV{PATH}")
      ```

    - 引用：`$ENV{<variable>}`，例如：

      ```cmake
      message("Value of ENV_VAR: $ENV{ENV_VAR}")
      ```

- 条件语句

  1. 字符串比较，比如：**STREQUAL、STRLESS、STRGREATER**等；
  2. 数值比较，比如：**EQUAL、LESS、GREATER**等；
  3. 布尔运算，**AND、OR、NOT**；
  4. 路径判断，比如：**EXISTS、IS_DIRECTORY、IS_ABSOLUTE**等；
  5. 版本号判断；等等；
  6. 使用小括号可以组合多个条件语句，比如：**(cond1) AND (cond2 OR (cond3))**。

## 2.4 CMake常用脚本命令

- 消息打印（message）：

  - 其实就是打印log，用来打印不同信息，常用命令格式为： 

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

  - 其中`mode`就相当于打印的等级，常用的有这几个选项： 

    1. 空或者`NOTICE`：比较重要的信息
    2. DEBUG：调试信息，主要针对开发者
    3. STATUS：项目使用者可能比较关心的信息，比如提示当前使用的编译器
    4. WARNING：CMake警告，不会打断进程
    5. SEND_ERROR：CMake错误，会继续执行，但是会跳过生成构建系统
    6. FATAL_ERROR：CMake致命错误，会终止进程

- 条件分支（if/elseif/else/endif，for/while，……）

  - 例如：

    ```cmake
    set(EMPTY_STR "")
    if (NOT EMPTY_STR AND FLAG AND NUM LESS 50 AND NOT NOT_DEFINE_VAR)
        message("The first if branch...")
    elseif (EMPTY_STR)
        message("EMPTY_STR is not empty")
    else ()
        message("All other case")
    endif()
    ```

- 列表操作（list(APPEND/LENGTH/JOIN/... ...)）

  - 比较常用的有：

    1. `APPEND`，往列表中添加元素；
    2. `LENGTH`，获取列表元素个数；
    3. `JOIN`，将列表元素用指定的分隔符连接起来；

  - 示例如下： 

    ```cmake
    set(SLOGAN_ARR To be)                    # Saved as "To;be"
    set(WECHAT_ID_ARR Real Cool Eengineer)   # Saved as "Real;Cool;Engineer"
    list(APPEND SLOGAN_ARR a)                # "To;be;a"
    list(APPEND SLOGAN_ARR ${WECHAT_ID_ARR}) # "To;be;a;Real;Cool;Engineer"
    list(LENGTH SLOGAN_ARR SLOGAN_ARR_LEN)   # 6
    list(JOIN SLOGAN_ARR " " SLOGEN_STR)     # "To be a Real Cool Engineer"
    message("Slogen list length: ${SLOGAN_ARR_LEN}")
    message("Slogen list: ${SLOGAN_ARR}")
    message("Slogen list to string: ${SLOGEN_STR}\n")
    ```

- 文件操作（file）

  - CMake的`file`命令支持的操作比较多，可以读写、创建或复制文件和目录、计算文件hash、下载文件、压缩文件等等，使用的语法都比较类似。

  - 以递归遍历文件为例，下面是获取src目录下两个子目录内所有c文件的列表的示例： 

    ```cmake
    file(GLOB_RECURSE ALL_SRC
            src/module1/*.c
            src/module2/*.c
            )
    ```

    - `GLOB_RECURSE`表示执行递归查找，查找目录下所有符合指定正则表达式的文件。 

- 配置文件生成（configure_file）

  - 使用`configure_file`命令可以将配置文件模板中的特定内容替换，生成目标文件。 输入文件中的内容`@VAR@`或者`${VAR}`在输出文件中将被对应的变量值替换。

  - 使用方式例如： 

    ```cmake
    set(VERSION 1.0.0)
    configure_file(version.h.in "${PROJECT_SOURCE_DIR}/version.h")
    ```

    - 假设`version.h.in`的内容为： 

      ```cpp
      #define VERSION "@VERSION@"
      ```

    - 那么生成的`version.h`的内容为： 

      ```cpp
      #define VERSION "1.0.0"
      ```

- 执行系统命令（execute_process）

  - 使用`execute_process`命令可以执行一条或者顺序执行多条系统命令，对于需要使用系统命令获取一些变量值是有用的。

  - 比如获取当前仓库最新提交的commit的commit id： 

    ```cmake
    execute_process(COMMAND bash "-c" "git rev-parse --short HEAD" OUTPUT_VARIABLE COMMIT_ID)
    ```

- 查找库文件（find_library）

  - 通过`find_library`在指定的路径和相关默认路径下查找指定名字的库，找到的库就可以被其他target使用，表明依赖关系。

  - 常用的格式如下： 

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

- 包含其他模块（include）

  - `include`命令将cmake文件或者模块加载并执行

  - 例如：

    ```cmake
    include(CPack) # 开启打包功能
    include(CTest) # 开启测试相关功能
    ```

  - CMake自带有很多有用的模块，可以看看官网的链接：[cmake-modules](https://link.zhihu.com/?target=https%3A//cmake.org/cmake/help/latest/manual/cmake-modules.7.html)，对支持的功能稍微有所了解，后续有需要再细看文档。 

## 2.5 编码2：优化CMakelist.txt

- 项目结构

  ```txt
  |_ cmake-tutorial/
  	...
  	|_ 2/
  		CMakeLists.txt
  		main.cpp
  		myMath.cpp
  		myMath.h
  	...
  ```

- C++文件

  - myMath.h

    ```cpp
    #ifndef MY_MATH_H
    #define MY_MATH_H
    
    float mySqrt(float);
    float myPow2(float);
    
    #endif
    ```

  - myMath.cpp

    ```cpp
    #include "myMath.h"
    #include <math.h>
    
    float mySqrt(float num) {
      return sqrt(num);
    }
    
    float myPow2(float num) {
      return pow(num, 2);
    }
    ```

  - main.cpp

    ```cpp
    #include <iostream>
    #include <cstdlib>
    #include "myMath.h"
    
    int main(int argc, char *argv[]) {
      if (argc < 2) {
        std::cout << "Usage: " << argv[0] << " number" << std::endl;
        return 1;
      }
    
      const double inputValue = atof(argv[1]);
      std::cout << "The square root of " << inputValue
                << " is " << mySqrt(inputValue) << std::endl;
      std::cout << "The square of " << inputValue
                << " is " << myPow2(inputValue) << std::endl;
    
      return 0;
    }
    ```

- 在CMakelist.txt中替换`PROJECT_NAME`与`SRC_LIST`

  ```cmake
  cmake_minimum_required(VERSION 3.20)
  
  # set the project name
  project(demo)
  
  # add the executable
  aux_source_directory(. SRC_LIST) # 等价于set(SRC_LIST main.cpp myMath.cpp)
  add_executable(${PROJECT_NAME} ${SRC_LIST})
  ```

  - 项目名的引用`${PROJECT_NAME}`是为了多处使用时统一更改
  - `${SRC_LIST}`代表源文件列表， `aux_source_directory` 命令会查找指定目录下的所有源文件，然后将结果存进指定变量名 

- 构建与执行

  ```bash
  cd 2 && cmake -B build && cmake --build build && build/demo 9 && cd ..
  ```

# 3 CMake配置

## 3.1 编码3：配置版本号与时间戳

- 项目结构

  ```txt
  |_ cmake-tutorial/
  	...
  	|_ 3/
  		|_ 3.1/
  			CMakeLists.txt
  			config.h.in
  			main.cpp
  		...
  	...
  ```

- c++文件沿用1

- CMakeLists.txt

  ```cmake
  # CMake 最低版本号要求
  cmake_minimum_required(VERSION 3.20)
  
  # 项目信息
  project(demo VERSION 1.0.0)
  string(TIMESTAMP COMPILE_TIME %Y.%m.%d-%H:%M:%S)
  
  # 加入一个配置头文件，用于处理 CMake 对源码的设置
  configure_file (
    "${PROJECT_SOURCE_DIR}/config.h.in"
    "${PROJECT_BINARY_DIR}/config.h"
  )
  
  # 查找当前目录下的所有源文件，并将名称保存到 DIR_SRCS 变量
  aux_source_directory(. SRC_LIST)
  
  # 指定生成目标
  add_executable(${PROJECT_NAME} ${SRC_LIST})
  
  # 为目标添加配置文件的包含路径
  target_include_directories(${PROJECT_NAME} PUBLIC
    ${PROJECT_BINARY_DIR}
  )
  ```

  - 在`project`中通过`VERSION`指定版本号，格式为`major.minor.patch.tweak`；CMake会将对应的值分别赋值给以下变量（如果没有设置，则为空字符串）： 

    ```cpp
    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
    ```

  - 有时候我们需要知道编译时的时间戳，并在程序运行时打印出来，因此将时间戳通过`string`以指定格式保存到 COMPILE_TIME 变量中。 注意，任何在config.h.in中定义的变量都要在`configure_file`之上

  - `configure_file`：配置文件`.h.in`可以自定义名称，以下取名为`config.h.in`，其中可以包含项目版本、时间戳等宏定义的占位符

    - `config.h.in`需要手动创建，包含以下内容（字符串的话要双引号！）

      ```cpp
      #define HELLO_VERSION "@PROJECT_VERSION@"
      #define HELLO_VERSION_MAJOR @PROJECT_VERSION_MAJOR@
      #define HELLO_VERSION_MINOR @PROJECT_VERSION_MINOR@
      #define HELLO_VERSION_PATCH @PROJECT_VERSION_PATCH@
      
      #define TIMESTAMP "@COMPILE_TIME@"
      ```

    - 当执行cmake配置构建系统后，会在`build`中生成`config.h`，并将占位符`@<var-name>@`替换为`CMakelist.txt`中定义的值。例如：

      ```cpp
      #define HELLO_VERSION "1.0.0"
      #define HELLO_VERSION_MAJOR 1
      #define HELLO_VERSION_MINOR 0
      #define HELLO_VERSION_PATCH 0
      ```

  - `target_include_directories`：由于`config.h`文件这里被设置为自动写入 build 目录，因此需要将该目录添加到搜索头文件的路径列表中。`PROJECT_BINARY_DIR` 表示当前工程的二进制路径，即编译产物会存放到该路径，此时`PROJECT_BINARY_DIR` 就是 build 所在路径。 

    - `include_directories`：当前`CMakeList.txt`中的所有目标以及所有在其调用点之后添加的子目录中的所有目标将具有此头文件搜索路径。
    - `target_include_directories`：指定目标包含的头文件路径。因此必须在`add_executable`生成目标后添加

- 构建与执行

  ```bash
  cd 3 && cmake -B build && cmake --build build && build/demo && cd ..
  ```

## 3.2 指定编程语言版本

- 为了在不同机器上编译更加统一，最好指定语言的版本

- 比如在CMakelist.txt中声明C使用`c99`标准，C++使用`c++11`标准（要确保在 `add_executable` 命令之前添加这些命令）： 

  ```cmake
  set(CMAKE_C_STANDARD 99)
  set(CMAKE_C_STANDARD_REQUIRED True)
  set(CMAKE_CXX_STANDARD 11)
  set(CMAKE_CXX_STANDARD_REQUIRED True)
  ```

  - `CMAKE_`、`_CMAKE`或者以下划线开头后面加上任意CMake命令的变量名都是CMake保留的，正是通过修改这些变量的值来配置CMake构建的行为。 

## 3.3 配置编译选项

- 通过命令`add_compile_options`命令可以为所有编译器配置编译选项（同时对多个编译器生效） 

  -  比如： 

    ```cmake
    add_compile_options(-Wall -Wextra -pedantic -Werror)
    ```

- FLAGS

  - 通过设置变量`CMAKE_C_FLAGS`可以配置c编译器的编译选项； 

  - 而设置变量`CMAKE_CXX_FLAGS`可配置针对c++编译器的编译选项。

  - 比如：

    ```cmake
    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -pipe -std=c99")
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pipe -std=c++11")
    ```

- LINKER_FLAGS

  - 设置`CMAKE_EXE_LINKER_FLAGS`会被链接器使用以构建可执行文件

  - 比如C++使用OpenMP时：

    ```cmake
    set(CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS} ${OpenMP_CXX_FLAGS})
    set(CMAKE_EXE_LINKER_FLAGS ${CMAKE_EXE_LINKER_FLAGS} ${OpenMP_EXE_LINKER_FLAGS})
    ```

## 3.4 配置编译类型

- 通过设置变量`CMAKE_BUILD_TYPE`来配置编译类型，可设置为：`Debug`、`Release`、`RelWithDebInfo`、`MinSizeRel`等。

- 如果设置编译类型为`Debug`，那么对于c编译器，CMake会检查是否有针对此编译类型的编译选项`CMAKE_C_FLAGS_DEBUG`，如果有，则将它的配置内容加到`CMAKE_C_FLAGS`中

  - CMakelist.txt添加一行即可

    ```cmake
    set(CMAKE_BUILD_TYPE Debug)
    ```

  - 当然，更好的方式应该是在执行`cmake`命令的时候通过参数`-D`指定：

    ```cmake
    cmake -B build -DCMAKE_BUILD_TYPE=Debug
    ```

- 可以针对不同的编译类型设置不同的编译选项

  - 比如对于`Debug`版本，开启调试信息，不进行代码优化：

    ```cmake
    set(CMAKE_C_FLAGS_DEBUG "${CMAKE_C_FLAGS_DEBUG} -g -O0")
    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -g -O0")
    ```

  - 对于`Release`版本，不包含调试信息，优化等级设置为2：

    ```cmake
    set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS_RELEASE} -O2")
    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O2")
    ```

## 3.5 添加全局宏定义

- 通过命令`add_definitions`可以添加全局的宏定义，在源码中就可以通过判断不同的宏定义实现相应的代码逻辑。用法如下：

  ```cmake
  add_definitions(-DDEBUG -DREAL_COOL_ENGINEER)
  ```

## 3.6 添加include目录

- 通过命令`include_directories`来设置头文件的搜索目录，比如：

  ```cmake
  include_directories(src/c)
  ```

# 4 CMake自定义库

> [CMake应用：CMakeLists.txt完全指南 - 知乎 (zhihu.com)](https://zhuanlan.zhihu.com/p/371257515) 
>
> [CMake 入门实战 | HaHack](https://www.hahack.com/codes/cmake/) 
>
> [CMake链接动态库与静态库的方法 - 知乎 (zhihu.com)](https://zhuanlan.zhihu.com/p/631234923) 

## 4.1 编译目标

- 一般来说，编译目标(target)的类型一般有静态库、动态库和可执行文件。这时编写`CMakeLists.txt`主要包括两步：
  1. 编译：确定编译目标所需要的源文件（`add_executable`、`add_library`等）
  2. 链接：确定链接的时候需要依赖的额外的库（`target_link_libraries`等）
- 编译可执行文件已经在之前的编码中熟悉了，本节主要介绍如何编译自定义静态库并与可执行文件进行链接

## 4.2 编码4-1：一个自定义库

- 项目结构

  ```txt
  |_ cmake-tutorial/
  	...
  	|_ 4/
  		|_ 1/
  			|_ include
  				myMath.h
  			|_ lib
  				CMakeLists.txt
  				myMath.cpp			
  			CMakeLists.txt
  			main.cpp
  		...
  	...
  ```

- c++文件沿用2，只是把myMath.h移动到include，myMath.cpp移动到lib

- lib目录的CMakeLists.txt

  ```cmake
  aux_source_directory(. LIB_SRC_LIST)
  add_library(myLib OBJECT ${LIB_SRC_LIST})
  ```

  - `add_library`生成库文件`myLib`
    - `STATIC`生成静态库（`.a`），`SHARED`生成动态库（`.so`），`OBJECT`生成对象库。对象库类似于静态库，但不生成`.a`文件，只由 CMake 记住该库生成了哪些对象文件。
    - 对象库是 CMake 自创的，绕开了编译器和操作系统的各种繁琐规则，保证了跨平台统一性；对象库仅仅作为组织代码的方式，而实际生成的可执行文件只有一个，减轻了部署的困难。

- 主目录的CMakeLists.txt

  ```cmake
  # CMake最低版本号要求
  cmake_minimum_required(VERSION 3.20)
  
  # 项目信息
  project(demo)
  
  # 添加包含路径
  include_directories(include) # 新增
  
  # 递归构建
  add_subdirectory(lib) # 新增
  
  # 查找当前目录下的所有源文件，并将名称保存到 DIR_SRCS 变量
  aux_source_directory(. SRC_LIST)
  
  # 指定生成目标
  add_executable(${PROJECT_NAME} ${SRC_LIST})
  
  # 添加链接库
  target_link_libraries(${PROJECT_NAME} PUBLIC
    myLib
  ) # 新增
  ```

  - `include_directories`添加包含路径，这样`main.cpp`只需`#include "myMath.h"`而不用`#include "include/myMath.h"`。注意，该命令需放在递归构建命令之前
  - `add_subdirectory`进行递归构建，即主`CMakeLists.txt`运行到此处时，先去运行`lib`中的`CMakeLists.txt`，再回来接着运行
  - `target_link_libraries`进行链接，注意到递归构建时已生成了`myLib`
    - 每一个目录都是一个模块，目录内部应将对外和对内的头文件进行区分，由模块的调用者决定模块是否被传递（PRIVATE，INTERFACE，PUBLIC）。PUBLIC = PRIVATE + INTERFACE。简单起见用PUBLIC即可。

- 构建与执行

  ```bash
  cd 4/1 && cmake -B build && cmake --build build && build/demo 9 && cd ../..
  ```

## 4.3 编码4-2：多个自定义库

- 项目结构（编译器流程）

  ```txt
  |_ cmake-tutorial/
  	...
  	|_ 4/
  		|_ 2/
  			|_ include
  				|_ compiler
  					|_ step1
  						lexer.h
  						parser.h
  						translator.h
  					|_ step2
  						opt1.h
  						opt2.h
  						opt3.h
  					|_ step3
  						codegen.h
  				|_ runtime
  					compiler.h
  			|_ lib
  				|_ runtime
  					CMakeLists.txt
  					compiler.cpp
  				|_ step1
  					CMakeLists.txt
  					lexer.cpp
  					parser.cpp
  					translator.cpp
  				|_ step2
  					CMakeLists.txt
  					opt1.cpp
  					opt2.cpp
  					opt3.cpp
  				|_ step3
  					CMakeLists.txt
  					codegen.cpp
  				CMakeLists.txt
  			CMakeLists.txt
  			main.cpp
  	...
  ```

  - 在include中按逻辑定义目录树，其中都是.h文件
  - lib中存放叶目录，其中是对应的.cpp文件

- C++文件就是简单的打印输出，略

- CMakeLists.txt类似地使用4中的

  - `include_directories`添加包含路径
  - `add_subdirectory`进行递归构建
  - `target_link_libraries`进行链接

- 构建与执行

  ```bash
  cd 4/2 && cmake -B build && cmake --build build && build/demo && cd ../..
  ```

# 5 CMake外部库

> [CMake链接第三方库的方法 - 知乎 (zhihu.com)](https://zhuanlan.zhihu.com/p/631238808) 
>
> [Cmake之深入理解find_package()的用法 - 知乎 (zhihu.com)](https://zhuanlan.zhihu.com/p/97369704) 
>
> [OpenMP cmake写法_wwxy261的博客-CSDN博客](https://blog.csdn.net/wwxy1995/article/details/114796854) 
>
> [CMake&yacc&lex_lazying_bird的博客-CSDN博客](https://blog.csdn.net/a_flying_bird/article/details/54913824) 
>
> [FindFLEX — CMake 3.6.3 Documentation](https://cmake.org/cmake/help/v3.6/module/FindFLEX.html) 

## 5.1 find_package

- Module模式

  - 为了方便我们在项目中引入外部依赖包，cmake官方为我们预定义了许多寻找依赖包的Module，在官方文档的[Find Modules](https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html#find-modules)中可以看到哪些库已经定义好并可以直接使用find_package函数进行引用。以curl库为例，假设我们项目需要引入这个库，从网站中请求网页到本地，我们看到官方已经定义好了FindCURL.cmake，所以我们在CMakeLists.txt中可以直接用find_pakcage进行引用（对于系统预定义的 `Find<LibaryName>.cmake` 模块，使用方法一般都如下）：

    ```cmake
    find_package(CURL)
    add_executable(curltest curltest.cc)
    if(CURL_FOUND)
        target_include_directories(clib PRIVATE ${CURL_INCLUDE_DIR})
        target_link_libraries(curltest ${CURL_LIBRARY})
    else()
        message(FATAL_ERROR ”CURL library not found”)
    endif()
    ```

  - 在Module模式中，cmake需要找到一个叫做`Find<LibraryName>.cmake`的文件，这个文件负责找到库所在的路径，为我们的项目引入头文件路径和库文件路径。cmake搜索这个文件的路径有两个，一个是cmake安装目录下的`share/cmake-<version>/Modules`目录，另一个是我们指定的`CMAKE_MODULE_PATH`的所在目录。 

- Config模式

  - 如果Module模式搜索失败，没有找到对应的`Find<LibraryName>.cmake`文件，则转入Config模式进行搜索。它主要通过`<LibraryName>Config.cmake` or `<lower-case-package-name>-config.cmake`这两个文件来引入我们需要的库。
  - 对于原生支持Cmake编译和安装的库，通常会安装Config模式的配置文件到对应目录，这个配置文件直接配置了头文件库文件的路径以及各种cmake变量供find_package使用。 

- 一般而言，搜索如何在CMake引入特定外部库可以在浏览器上搜索相应的教程

## 5.2 编码5-1：引入OpenMP库

- 项目结构

  ```txt
  |_ cmake-tutorial/
  	...
  	|_ 5/
    	|_ 1/
  			CMakeLists.txt
  			main.cpp
  		...
  	...
  ```

- C++文件是使用omp进行快速排序

- CMakeLists.txt参考[OpenMP cmake写法_wwxy261的博客-CSDN博客](https://blog.csdn.net/wwxy1995/article/details/114796854)

  ```cmake
  # CMake最低版本号要求
  cmake_minimum_required(VERSION 3.20)
  
  # 项目信息
  project(demo)
  set(CMAKE_CXX_STANDARD 17)
  
  # 外部库
  find_package(OpenMP REQUIRED)
  if(OPENMP_FOUND)
      set(CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS} ${OpenMP_CXX_FLAGS})
      set(CMAKE_EXE_LINKER_FLAGS ${CMAKE_EXE_LINKER_FLAGS} ${OpenMP_EXE_LINKER_FLAGS})
  else()
      message(FATAL_ERROR "OpenMP NOT FOUND!")
  endif()
  
  # 查找当前目录下的所有源文件，并将名称保存到 DIR_SRCS 变量
  aux_source_directory(. SRC_LIST)
  
  # 指定生成目标
  add_executable(${PROJECT_NAME} ${SRC_LIST})
  ```

- 构建与执行

  ```cmake
  cd 5/1 && cmake -B build && cmake --build build && build/demo 10000000 4 && cd ../..
  ```

## 5.3 编码5-2：引入flex库

- 项目结构

  ```txt
  |_ cmake-tutorial/
  	...
  	|_ 5/
  		...
    	|_ 2/
    		CMakeLists.txt
    		input
    		lexer.l
  			main.cpp
  		...
  	...
  ```

- lexer.l

  ```l
  %{
  #include <iostream>
  %}
  %%
  [\t\r\n ]+   /* white space */
  [a-zA-Z]+ { printf("word: %s\n", yytext); }
  [0-9]+ { printf("number: %s\n", yytext); }
  .  { printf("uncatagorized: %s\n", yytext); }
  %%
  int yywrap() { return 1; }
  ```

- main.cpp

  ```cpp
  #include <iostream>
  
  extern int yylex();
  
  int main(int argc, const char *argv[]) {
      if (argc != 2) {
          std::cout << "Usage: " << argv[0] << " filename" << std::endl;
          return 1;
      }
  
      freopen(argv[1], "r", stdin);
      while (!feof(stdin))
          yylex();
  
      return 0;
  }
  ```

- CMakeLists.txt

  ```cmake
  # CMake最低版本号要求
  cmake_minimum_required(VERSION 3.20)
  
  # 项目信息
  project(demo)
  
  # flex
  find_package(FLEX)
  FLEX_TARGET(lexer lexer.l ${PROJECT_BINARY_DIR}/lexer.cpp)
  
  # 添加包含路径
  include_directories(${PROJECT_BINARY_DIR})
  
  # 查找当前目录下的所有源文件，并将名称保存到 DIR_SRCS 变量
  aux_source_directory(. SRC_LIST)
  
  # 指定生成目标
  add_executable(${PROJECT_NAME} 
      ${SRC_LIST}
      ${FLEX_lexer_OUTPUTS}
  )
  ```

- 构建与运行

  ```bash
  cd 5/2 && cmake -B build && cmake --build build && build/demo input && cd ../..
  ```

## 5.4 编码5-3：引入flex与bison库

- 项目结构

  ```txt
  |_ cmake-tutorial/
  	...
  	|_ 5/
  		...
    	|_ 3/
    		CMakeLists.txt
    		|_ input
    			pass
    			fail
    		lexer.l
  			main.cpp
  			parser.y
  	...
  ```

- parser.y

  ```y
  %{
  #include <iostream>
  extern int yylex();
  void yyerror(const char *s, ...);
  %}
  %token OBJECT PRICE
  %%
  description: object PRICE { printf("pass...\n"); } ;
  object: OBJECT ;
  %%
  void yyerror(const char *s, ...) { fprintf(stderr, "%s\n", s); }
  ```

- lexer.l

  ```l
  %{
  #include "parser.hpp"
  %}
  %%
  [\t\r\n ]+   /* white space */
  [a-zA-Z]+ {return OBJECT;}
  [0-9]+ {return PRICE;}
  .   /* ignore */
  %%
  int yywrap() { return 1; }
  ```

- main.cpp

  ```cpp
  #include <iostream>
  
  extern int yyparse();
  
  int main(int argc, const char *argv[]) {
      if (argc != 2) {
          std::cout << "Usage: " << argv[0] << " filename" << std::endl;
          return 1;
      }
  
      freopen(argv[1], "r", stdin);
      while (!feof(stdin))
          yyparse();
  
      return 0;
  }
  ```

- CMakeLists.txt

  ```cmake
  # CMake最低版本号要求
  cmake_minimum_required(VERSION 3.20)
  
  # 项目信息
  project(demo)
  
  # flex和bison
  find_package(FLEX)
  find_package(BISON)
  FLEX_TARGET(lexer lexer.l ${PROJECT_BINARY_DIR}/lexer.cpp)
  BISON_TARGET(parser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
  ADD_FLEX_BISON_DEPENDENCY(lexer parser)
  
  # 添加包含路径
  include_directories(${PROJECT_BINARY_DIR})
  
  # 查找当前目录下的所有源文件，并将名称保存到 DIR_SRCS 变量
  aux_source_directory(. SRC_LIST)
  
  # 指定生成目标
  add_executable(${PROJECT_NAME} 
      ${SRC_LIST}
      ${FLEX_lexer_OUTPUTS}
      ${BISON_parser_OUTPUTS}
  )
  ```

- 构建与运行

  ```bash
  cd 5/3 && cmake -B build && cmake --build build && build/demo input/pass && build/demo input/fail && cd ../..
  ```