APM32芯得EP.43|使用CMake构建APM32工程

# 01 前言

一般嵌入式开发都是用集成 IDE 工具，IDE 的好处是集成了编辑器、编译器、调试器等工具，可以一站式开发。但是 IDE 也有很多缺点，比如不跨平台、不开源等。如果想要摆脱 IDE 的束缚，就需要手动编写编译规则，比如 Makefile 构建工程，但是 Makefile 语法比较复杂，很多时候手动编写 Makefile 比较繁琐，工作量也比较大。

CMake 是一个比较流行的跨平台构建工具，它可以自动生成 Makefile，本篇文章主要介绍怎么用 CMake 和 MinGW-w64 构建 APM32 工程，编译器使用 gcc-arm-none-eabi，调试器使用 DAPLink。

# 02 环境搭建

## 软件环境准备

- Windows 10/11

- CMake 3.28.0-rc5

- MinGW-w64 8.1.0

- gcc-arm-none-eabi 10.3.1

## 搭建 MinGW-w64 环境

### 安装 CMake

[CMake](https://cmake.org/download/) 是一个开源的跨平台构建工具，可以用简单的语句来描述所有平台的安装(编译过程)。它能够输出各种各样的makefile 或者 project 文件。到官网找到二进制版本的 CMake，本篇文章使用的是`cmake-3.28.0-rc5-windows-x86_64.zip`。

下载压缩包并解压到自己喜欢的位置，这里解压到 `E:\ToolChain\`。

### 配置环境变量

将`E:\ToolChain\cmake-3.28.0-rc5-windows-x86_64\bin` 添加到环境变量 `Path` 中。

### 验证 CMake 是否安装成功

打开 CMD，输入 `cmake -version`，如果出现如下信息，则说明 CMake 安装成功。

### 安装 MinGW-w64

[MinGW-W64](https://sourceforge.net/projects/mingw-w64/files/mingw-w64/)全称为 Minimalist GNU for Windows，是一个在 Windows 平台上编译 32 位和64 位应用程序的工具集。

下载 `x86_64-win32-seh` 并 解压压缩包中的 mingw64 文件夹到自己喜欢的位置，这里解压到 `E:\ToolChain\`。

### 配置环境变量

将 `E:\ToolChain\mingw64\bin` 添加到环境变量 `Path` 中。

### 验证 MinGW-w64 是否安装成功

打开 CMD，输入 `gcc -v`，如果出现如下信息，则说明 MinGW-w64 安装成功

## 搭建gcc-arm-none-eabi 环境

### 安装gcc-arm-none-eabi

[gcc-arm-none-eabi](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads)是 ARM 官方提供的一款免费的编译器，支持多种操作系统，包括Windows、Linux 和 macOS。

从上面的链接下载压缩包后，同样解压到 `E:\ToolChain\`。

### 配置环境变量

将 `E:\ToolChain\gcc-arm-none-eabi-10.3-2021.10\bin`添加到环境变量 `Path` 中。

### 验证gcc-arm-none-eabi 是否安装成功

打开 CMD，输入`arm-none-eabi-gcc -v`，如果出现如下信息，则说明 gcc-arm-none-eabi 安装成功。

# 03 构建工程

## 准备 APM32 工程

从 [APM32 DAL SDK](https://www.geehy.com/support/apm32?id=311) 下载APM32_DAL_SDK_V1.0，这里使用 GPIO_Toggle 工程进行构建。

## 编写CMakeLists.txt

在 `GPIO_Toggle` -> `Project` 目录下新建 `CMake` 目录并新增 `CMakeLists.txt` 文件，如下图所示。

CMake 的语法可以参考[CMake Documentation and Community](https://cmake.org/documentation/)，这里只介绍一些常用和关键的语法。

### 指定 CMake 最低版本和项目名称

`cmake_minimum_required` 用于指定构建此项目所需的 CMake 的最低版本，`project` 用于指定项目名称。

```cmake

cmake_minimum_required(VERSION 3.21) # 指定构建此项目所需的 CMake 的最低版本

project(GPIO_Toggle C CXX ASM) # 指定项目名称和编程语言

```

### 指定编译器

`set` 用于设置变量，`CMAKE_C_COMPILER`用于指定 C 语言编译器，`CMAKE_CXX_COMPILER`用于指定 C++ 语言编译器，`CMAKE_ASM_COMPILER`用于指定汇编语言编译器。

`CMAKE_OBJCOPY` 用于指定生成二进制文件的工具，`CMAKE_OBJDUMP` 用于指定生成汇编文件的工具，`CMAKE_SIZE` 用于指定生成大小报告的工具。

```cmake

set(CMAKE_C_COMPILER "arm-none-eabi-gcc") # 指定 C 语言编译器

set(CMAKE_ASM_COMPILER "arm-none-eabi-gcc") # 指定汇编语言编译器

set(CMAKE_OBJCOPY arm-none-eabi-objcopy) # 指定生成二进制文件的工具

set(SIZE arm-none-eabi-size) # 指定生成大小报告的工具

```

### 配置设备 ID

`set` 用于设置变量，`DEVICE_ID`用于指定设备 ID，`BSP_DEFINE` 用于指定 BSP 宏定义，`BSP_DIR_NAME` 用于指定 BSP 目录名称。

```cmake

# device settings

set(DEVICE_ID "APM32F407xx")

set(BSP_DEFINE BOARD_APM32F407_MINI)

set(BSP_DIR_NAME Board_APM32F407_Mini)

# select startup file

if ("${DEVICE_ID}" STREQUAL "APM32F405xx")

set(STARTUP_FILE startup_apm32f405xx.S)

set(LINKER_FILE apm32f405xg_flash.ld)

set(DEVICE_DEFINE APM32F405xx)

elseif ("${DEVICE_ID}" STREQUAL "APM32F407xx")

set(STARTUP_FILE startup_apm32f407xx.S)

set(LINKER_FILE apm32f407xg_flash.ld)

set(DEVICE_DEFINE APM32F407xx)

elseif ("${DEVICE_ID}" STREQUAL "APM32F417xx")

set(STARTUP_FILE startup_apm32f417xx.S)

set(LINKER_FILE apm32f417xg_flash.ld)

set(DEVICE_DEFINE APM32F417xx)

else()

message(FATAL_ERROR "Please select first the target APM32F4xx device")

endif ()

```

### 添加编译选项

`add_compile_options` 用于添加编译选项，`-mcpu=cortex-m4` 用于指定 CPU 架构，`-mthumb` 用于指定 Thumb 指令集，

`-mthumb-interwork` 用于指定 Thumb 指令集兼容 ARM 指令集。

```cmake

add_compile_options(-mcpu=cortex-m4 -mthumb -mthumb-interwork)

add_compile_options(-ffunction-sections -fdata-sections -fno-common -fmessage-length=0)

```

### 配置宏定义

`add_definitions` 用于添加宏定义，`-D${DEVICE_DEFINE}` 用于指定设备宏定义，`-D${BSP_DEFINE}`用于指定 BSP 宏定义，`-DUSE_DAL_DRIVER`用于指定使用 DAL 库。

```cmake

add_definitions(

-DUSE_DAL_DRIVER

-D${DEVICE_DEFINE}

-D${BSP_DEFINE}

)

```

### 添加头文件和源文件路径

`include_directories` 用于添加头文件路径，`file(GLOB_RECURSE SOURCES)` 用于添加源文件路径。

```cmake

# add include file

include_directories(

../../Include

../../Config/Include

../../../../../../Libraries/CMSIS/Include

../../../../../../Libraries/Device/Geehy/APM32F4xx/Include

../../../../../../Libraries/APM32F4xx_DAL_Driver/Include

../../../../../../Boards/${BSP_DIR_NAME}/Include

)

# add source file

file(GLOB_RECURSE SOURCES

"${STARTUP_FILE}"

"../../Source/*.c"

"../../Config/Source/*.c"

"../../../../../../Libraries/APM32F4xx_DAL_Driver/Source/*.c"

"../../../../../../Boards/${BSP_DIR_NAME}/Source/*.c"

)

```

PS: GCC编译器可以输出静态库、动态库和可执行文件，理论上来说可以将所有的源文件都放在一起编译，但是这样做的话，每次编译都会编译所有的源文件，这样会导致编译时间过长，所以一般情况下，我们会将源文件分成多个库，然后再将这些库链接到一起，这样可以减少编译时间。这样就会用到 `add_library`。比如将LwIP库编译成静态库，然后将静态库链接到主程序中。比如将 LwIP 编译成静态库：

```cmake

add_library(lwip

../../../../../../Middlewares/lwip-2.1.2/src/api/api_lib.c

...

)

```

### 添加链接脚本

`add_link_options` 用于添加链接脚本。

```cmake

set(LINKER_SCRIPT ${CMAKE_SOURCE_DIR}/${LINKER_FILE})

add_link_options(-T ${LINKER_SCRIPT})

```

### 添加链接选项

`-gc-sections`：这是一个链接器选项，用于在链接过程中删除未使用的代码和数据，有助于减小最终生成的二进制文件的大小。

`--print-memory-usage`：这是一个链接器选项，用于在链接过程结束后打印内存使用情况。

`-Map=${PROJECT_BINARY_DIR}/firmware.map`：这是一个链接器选项，用于生成一个map文件，该文件包含了链接过程的详细信息，如各个函数和变量在内存中的位置等。

```cmake

add_link_options(-Wl,-gc-sections,--print-memory-usage,-Map=${PROJECT_BINARY_DIR}/firmware.map)

add_link_options(-mcpu=cortex-m4 -mthumb -mthumb-interwork)

```

### 添加可执行文件

`add_executable` 用于添加可执行文件，`${SOURCES}` 用于指定源文件，`${LINKER_SCRIPT}` 用于指定链接脚本。

```cmake

add_executable(firmware.elf ${SOURCES} ${LINKER_SCRIPT})

```

### 添加生成二进制文件和汇编文件的命令

`add_custom_command` 用于添加自定义命令，`TARGET firmware.elf POST_BUILD` 用于指定在生成可执行文件后执行命令，`COMMAND ${CMAKE_OBJCOPY} -Oihex $ ${HEX_FILE}` 用于生成 HEX 文件，`COMMAND ${CMAKE_OBJCOPY} -Obinary $ ${BIN_FILE}` 用于生成 BIN 文件。

```cmake

set(HEX_FILE ${PROJECT_BINARY_DIR}/firmware.hex)

set(BIN_FILE ${PROJECT_BINARY_DIR}/firmware.bin)

add_custom_command(TARGET firmware.elf POST_BUILD

COMMAND ${CMAKE_OBJCOPY} -Oihex [        DISCUZ_CODE_420        ]lt;TARGET_FILE:firmware.elf> ${HEX_FILE}

COMMAND ${CMAKE_OBJCOPY} -Obinary [        DISCUZ_CODE_420        ]lt;TARGET_FILE:firmware.elf> ${BIN_FILE}

COMMENT "Building ${HEX_FILE}

Building ${BIN_FILE}")

```

## 编译工程

### 生成 Makefile

用下面的命令生成 Makefile。

```bash

$ cd .\Project\CMake

$ mkdir cmake-build

$ cmake -G "MinGW Makefiles" -B cmake-build

```

创建 `cmake-build` 目录用于存放生成的 Makefile。

生成 Makefile。

PS: `cmake -DCMAKE_BUILD_TYPE=Debug -B cmake-build` 可用于指定编译类型为 Debug。

### 生成可执行文件

用下面的命令编译工程。

```bash

$ cd .\Project\CMake\cmake-build

$ make (or mingw32-make)

```

编译完成后，会在 `cmake-build` 目录下生成 `firmware.elf`、`firmware.hex` 和 `firmware.bin` 文件。

PS：`make clean` 用于清除编译生成的文件。

PS：`make -j` 用于指定使用多线程编译。`-j`后面还可以跟一个数字来指定线程数。例如，`make -j4`会使用4个线程进行编译。

到此就完成了用 CMake 构建APM32 工程并输出可执行文件， 接着就可以用 OpenOCD 或 PyOCD 配合 DAPLink 进行下载、调试了。

# 参考资料

[CMake Documentation and Community](https://cmake.org/documentation/)

APM32F4xx_DAL_SDK_V1.0(CMake).zip