嵌入式开发Git

背景

STM32+Git 协作方案
## 前言 在多人协作开发时往往需要用到 [Git](https://zh.wikipedia.org/wiki/Git) 来进行版本管理，但是嵌入式开发中有大量的外设初始化配置内容，STM32 开发又往往会搭配 STM32CubeMX 进行，STM32CubeMX 提供了一个图形化界面来管理 STM32 的板上外设，故我们无须关心具体的初始化代码。由此造成了一个问题：这些初始化代码由

上面的文章中提出了一种 STM32 + Git 多人协作开发方案，该方案虽然能对单个 STM32 项目进行较好的版本管理，却无法较好的进行驱动复用。如果希望维护一套可以在项目中复用的驱动，能采用的方案只有单独维护驱动仓库，在使用的时候复制到项目仓库内。这种形式会导致下游难以收到上游的更新，下游发现了 bug 自行修复也难以同步到上游，造成各模块不同步。

本文将提出基于 submodule 的模块分离方案。

IMPORTANT

该方案依赖 CMake，需要使用 STM32CubeMX 的 CMake 工具链

使用模块仓库

在新项目中使用

假设我们有一个模块仓库地址 https://github.com/HITSZ-WTRobot/motor_drivers

要使用这个仓库需要三步

  1. 将这个仓库添加到 submodule

    例如，模块目录在 ./Modules，我们进入这个目录 cd Modules（或者直接在 ./Modules 打开终端），并运行

    1
    git submodule add https://github.com/HITSZ-WTRobot/motor_drivers

  2. 将这个 submodule 目录添加到 CMake

    在根目录的 CMakeLists.txt 里新增

    1
    add_subdirectory(Modules/motor_drivers/UserCode)

    INFO

    大部分情况下 add_subdirectory 传入的参数都是 submodule 下的 UserCode 路径。

    少数情况如 s-curve-planner 仓库是直接导入根路径

  3. 将 模块添加到 target

    在根目录的 CMakeLists.txt 里找到

    1
    target_link_libraries(${CMAKE_PROJECT_NAME} ...)

    在里面添加模块名，一般情况下模块名是仓库名

    INFO

    模块名可以在 模块目录/UserCode/CMakeLists.txt 里找到，格式如下

    1
    add_library(motor_drivers STATIC ${ALL_SOURCES})

    这里 motor_drivers 就是模块名

拉取一个使用了模块的项目

在拉取有 submodule 的项目后，需要在项目根目录再运行

1
git submodule update --init --remote

更新项目里的模块

运行

1
git submodule update --remote

模块仓库编写

为了使模块仓库能够独立编译，模块仓库也应当是一个完整的项目。在之前的协作方案中我们提出

所有的项目代码都应当放在 UserCode 下，并分层编写

所以模块只需在 UserCode 下创建一个 CMakeLists.txt，并从中导出模块。

INFO

由于模块编写需要 CMake 基础，如果只是使用仓库不需要知道，本文不具体介绍

以下是一份示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
# UserCode/CMakeLists.txt
cmake_minimum_required(VERSION 3.21)

set(LIB_NAME motor_drivers)

project(${LIB_NAME})

# 导库方式
# add_subdirectory({project_path}/UserCode)
# target_link_libraries(${PROJECT_NAME}.elf PRIVATE motor_drivers)

# ---------------------------------------------------------------------------
# guard: UserCode should only be included by parent project
# ---------------------------------------------------------------------------
if (PROJECT_IS_TOP_LEVEL)
    message(FATAL_ERROR "UserCode must be included via add_subdirectory() from parent project")
endif ()

# ---------------------------------------------------------------------------
# layer options
# ---------------------------------------------------------------------------
option(MotorIF_UseBSP "use bsp layer" ON)
option(MotorIF_UseLibs "use library (pid_motor, pid_pd)" ON)
option(MotorIF_UseControllers "use s-curve-traj (depend on `s_curve`)" ON)

# ---------------------------------------------------------------------------
# collect layer sources
# ---------------------------------------------------------------------------
set(ALL_SOURCES interfaces/motor_if.c)

set(ALL_HEADERS "interfaces/motor_if.h")

if (MotorIF_UseBSP)
    file(GLOB_RECURSE BSP_SOURCES bsp/*.c)
    list(APPEND ALL_SOURCES ${BSP_SOURCES})
    list(APPEND ALL_HEADERS
            "bsp/can_driver.h"
            "bsp/gpio_driver.h"
            "bsp/pwm.h"
    )
endif ()

if (MotorIF_UseLibs)
    file(GLOB_RECURSE LIB_SOURCES libs/*.c)
    list(APPEND ALL_SOURCES ${LIB_SOURCES})
    list(APPEND ALL_HEADERS
            "libs/pid_motor.h"
            "libs/pid_pd.h"
    )
endif ()

if (MotorIF_UseControllers)
    file(GLOB_RECURSE CONTROLLER_SOURCES controllers/*.c)
    list(APPEND ALL_SOURCES ${CONTROLLER_SOURCES})
    list(APPEND ALL_HEADERS "controllers/s_curve_traj_follower.h")
endif ()

# ---------------------------------------------------------------------------
# feature options: option + source + macro
# ---------------------------------------------------------------------------
set(DRIVER_MACROS "")

option(MotorIF_UseDJI "enable DJI driver" ON)
if (MotorIF_UseDJI)
    list(APPEND ALL_SOURCES drivers/DJI.c)
    list(APPEND ALL_HEADERS "drivers/DJI.h")
    list(APPEND DRIVER_MACROS USE_DJI)
endif ()

option(MotorIF_UseTB6612 "enable TB6612 driver" OFF)
if (MotorIF_UseTB6612)
    list(APPEND ALL_SOURCES drivers/tb6612.c)
    list(APPEND ALL_HEADERS "drivers/tb6612.h")
    list(APPEND DRIVER_MACROS USE_TB6612)
endif ()

option(MotorIF_UseVESC "enable VESC driver" OFF)
if (MotorIF_UseVESC)
    list(APPEND ALL_SOURCES drivers/vesc.c)
    list(APPEND ALL_HEADERS "drivers/vesc.h")
    list(APPEND DRIVER_MACROS USE_VESC)
endif ()

option(MotorIF_UseDM "enable DM driver" OFF)
if (MotorIF_UseDM)
    list(APPEND ALL_SOURCES drivers/DM.c)
    list(APPEND ALL_HEADERS "drivers/DM.h")
    list(APPEND DRIVER_MACROS USE_DM)
endif ()

# ---------------------------------------------------------------------------
# create static library
# ---------------------------------------------------------------------------
add_library(motor_drivers STATIC ${ALL_SOURCES})
if (NOT TARGET ${LIB_NAME})
    message(FATAL_ERROR "target ${LIB_NAME} not created")
endif ()

# ---------------------------------------------------------------------------
# compile definitions
# ---------------------------------------------------------------------------
if (DRIVER_MACROS)
    target_compile_definitions(${LIB_NAME} PUBLIC ${DRIVER_MACROS})
endif ()

# ---------------------------------------------------------------------------
# build/include 目录
# ---------------------------------------------------------------------------
set(EXPORT_INCLUDE_DIR ${CMAKE_CURRENT_BINARY_DIR}/include)
file(MAKE_DIRECTORY ${EXPORT_INCLUDE_DIR})
target_include_directories(${LIB_NAME} PUBLIC ${EXPORT_INCLUDE_DIR})

# ---------------------------------------------------------------------------
# copy selected headers
# ---------------------------------------------------------------------------
foreach (header IN LISTS ALL_HEADERS)
    configure_file(${CMAKE_CURRENT_LIST_DIR}/${header}
            ${EXPORT_INCLUDE_DIR}/${header} COPYONLY)
endforeach ()


# ---------------------------------------------------------------------------
# declare dependencies
# ---------------------------------------------------------------------------
add_dependencies(${LIB_NAME} stm32cubemx)
target_link_libraries(${LIB_NAME} PRIVATE stm32cubemx)

if (MotorIF_UseControllers)
    # Repo: https://github.com/HITSZ-WTRobot/s-curve-planner
    target_link_libraries(${LIB_NAME} PRIVATE s_curve)
    add_dependencies(${LIB_NAME} s_curve)
endif ()

target_link_libraries(${LIB_NAME} PRIVATE m)