在苹果系统的电脑上搭建stm32f103c8t6的开发环境，本教程适配江科大的stm32教程

需要用到的工具：stm32cubemx、vscode
需要用到的工具链：cmake、ninja、xpack openocd、arm-gnu-toolchain

基础内容介绍

直接配置可跳过

vscode编辑器提供了两种设置编辑器的方式，第一种直接点击左下角的小齿轮打开设置面板进行设置，第二种通过编辑setting.json配置文件进行设置。

vscode提供了两个层级的设置权重，第一层级是user settings，对全局所有的项目文件生效，第二层级是workspace settings，对当前的项目生效，第二层级的设置项优先级更高会覆盖掉第一个层级的设置项。

第一个层级对应的settings.json文件打开方式为：command + shift + p，上方打开搜索栏后输入，open user settings(json)，搜索结果第一个点进去就是，并且打开后在上方的文件路径信息可以看到全局设置文件具体的存储地址。

第二个层级对应的settings.json的配置文件地址在当前的项目根目录下，找到.vscode目录，里面的settings.json就是当前workspace的设置文件，如果.vscode文件夹中没有这个文件，可以手动创建，功能是一样的，json文件具体写法后面会介绍。

使用vscode搭建嵌入式开发环境的原理其实很简单，就是把各种控制台的工具整合到vscode中，比如编译、烧录，正常你是可以在mac系统上找到合适的工具单独在控制台中输入一条条的命令来完成的，这些工具和命令都可以整合到vscode中，统一进行操作，这就不得不提到vscode的task功能。task任务功能允许你自定义多个task，每个task中可独立配置要执行的命令，你可以把一个task任务理解成你在控制台中输入的要执行的命令语句，并且，每个task任务可以以一个摁钮的方式（通过插件实现）显示在vscode的编辑器中。

配置步骤

1. 下载stm32cubemx，生成项目

下载链接：https://www.st.com/en/development-tools/stm32cubemx.html
打开stm32cubemx，在主页选择左上角的file->new project->左上角第一个搜索框搜索stm32f103c8t6后在右边列表中选择一下->点击右上角start project，创建好后进行以下配置

项目名称和路径自定义配置一下，配置完成后点击右上角的GENERATE CODE即可生成代码

2. 安装cmake

三种安装方式：homebrew、MacPorts、官网下载二进制包后配置环境。我自己采用homebrew的方式安装了cmake，其他两种自行探索，电脑中没有homebrew的自行查找如何安装，包括安装后如何换源。
打开终端，输入安装命令：brew install cmake 后回车
安装后可通过cmake --version来查看是否输出版本信息来判断是否安装成功

3. 安装ninja

安装方法：homebrew、github，本文依旧采用homebrew安装。
打开终端，输入安装命令 brew install ninja 后回车，安装后检验方法同上。

4. 下载配置arm-gnu-toolchain

下载链接：https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
如果你是intel的芯片选择macOS (x86_64)，如果是苹果芯片选择macOS (Apple silicon) 即可。
下载AArch32 bare-metal target (arm-none-eabi)这一栏下的版本，因为我们开发的是stm32，另外一个AArch64 bare-metal target (aarch64-none-elf)是开发64位arm架构用的，选择结尾为.pkg的文件进行下载。

提示

如果你是intel芯片的苹果电脑需注意，官网对intel的芯片只支持到14.2.rel1版本，往下翻，找到这个特定版本中的macOS (x86_64)一栏进行下载，旧版本不影响我们正常使用。

下载好后直接安装即可，安装好后文件会在访达的应用程序（Applications）文件夹中出现，文件夹名称为ArmGNUToolchain。
打开终端，输入nano ~/.bash_profile后回车打开文件，将光标移到最下方（没有方向键可直接摁control + v），输入以下代码配置环境变量：

添加环境变量
export PATH="$PATH:/Applications/ArmGNUToolchain/14.2.rel1/arm-none-eabi/bin”

注意

将上面文件路径中的14.2.rel1替换为你下载的具体版本号

编辑好后摁下 control + o 然后回车保存，control + x 退出
执行source ~/.bash_profile，应用环境变量。

5. 下载配置xpack openocd

安装方式：homebrew、github下载后配置环境变量。这里我们采用github下载预编译包后手动配置环境变量的方式，和上面的方法一样。
下载链接:https://github.com/xpack-dev-tools/openocd-xpack/releases
苹果电脑选择darwin后缀的，intel选x64，苹果芯片选arm64，选不带.sha后缀的。下载后解压，解压出来的文件夹随便放，记住路径就好，解压的文件夹中有一个bin目录，这就是我们要映射的目标位置。
打开终端输入：nano ~/.bash_profile回车打开，在最后一行添加以下内容，映射bin文件夹：

环境变量
export PATH="$PATH://替换为你的openocd完整路径/openocd-0.12.0-4/bin"

如何查看并直接复制文件夹的路径？

直接找到bin文件夹，右键bin文件夹，显示简介，在位置那一栏，直接选中所有内容，复制即可，粘贴后在路径最后手动加上一个/bin。不必担心简介显示的系统路径有中文字符，实际复制的位置是英文的真正的位置，不建议将解压后的文件夹放在自己创建带有中文的文件夹的路径下。

control + o + 回车保存，control + x 退出后执行source ~/.bash_profile
输入openocd --version检查是否正常打印版本信息

6. 下载配置llvm

下载链接：https://github.com/llvm/llvm-project/releases/tag/llvmorg-20.1.7
下载链接的版本是对mac intel x64 cpu平台的最后一个支持的版本
下载llvm的目的是为了使用工具包中的clangd，解压放好位置后，依旧映射bin目录，和上面的方法一样，打开终端输入 nano ~/.bash_profile 回车打开，最后一行添加

环境变量
export PATH="$PATH:/你的llvm完整路径/bin"

control + o + 回车保存 -> control + x 退出 -> 执行 source ~/.bash_profile 应用环境变量
配置好后终端输入 clangd 回车后会触发隐私保护不让陌生程序运行，我们去系统设置中的隐私与安全性中翻到最下面，信任允许一下
这时再在终端中输入 clangd --version 查看是否正常打印版本信息

7. 配置vscode

vscode下载地址：https://code.visualstudio.com/Download
vscode中需要安装的插件：clangd、cmake、task buttons、linkerscript

创建tasks.json

打开之前创建的stm32项目，在项目根目录的.vscode目录下，新建tasks.json，并输入以下内容：

tasks.json
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Configure",
            "type": "shell",
            "command" : "cmake",
            "args": [
                "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON",
                "-GNinja",
                "-Bbuild"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "Build",
            "type": "shell",
            "command": "cmake",
            "args": [
                "--build",
                "build",
                "--target",
                "all"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "Flash",
            "type": "shell",
            "command": "openocd",
            "args": [
                "-f",
                "interface/stlink.cfg",
                "-f",
                "target/stm32f1x_cn.cfg",
                "-c",
                "program ./build/修改为你的项目名称.elf verify reset exit"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]

}

注意

别忘了修改最后一个openocd任务的.elf文件的名称为项目名

重点参数介绍：
直接配置可跳过

label：任务的名字
command：要执行的命令
args：执行命令携带的参数

设置Settings.json

在.vscode目录下打开settings.json文件，给当前已存在的配置最后一行的花括号后面加上一个英文逗号 "}," 类似这样，如果有就不用了。然后另起一行输入以下配置

注意

一定要在上一个配置的最后加上一个英文的逗号，一定要粘贴在最外侧的大花括号{之内}

setting.json中的taskbuttons配置
    "VsCodeTaskButtons.showCounter": true,
    "VsCodeTaskButtons.tasks": [
    {
      "label": "$(collapse-all) CMake Configure",
      "task": "Configure",
      "tooltip": "Start the \"Configure\" task"
    },
    {
      "label": "$(debug-alt) CMake Build",
      "task": "Build",
      "tooltip": "Start the \"Build\" task"
    },
    {
      "label": "$(notebook-move-down) Flash",
      "task": "Flash",
      "tooltip": "Start a \"Flash\" task"
    }
  ],

做完到这一步你应该可以发现，在你编辑器的左下角出现了三个图标

从左到右依次是cmake configure，cmake build，和openocd的flash烧录，我们使用顺序也是从左到右依次运，运行configure会生成一个build目录，运行build会在build目录中生成.elf文件，flash就是向单片机中烧录.elf文件。这里我们先点击configure等待运行完成（终端窗口查看）后会生成一个build目录，为了下一步配置代码格式化使用。

配置代码格式化检查

代码的格式化检查利用的是前面我们已经安装的插件clangd，到目前为止我们的工程文件夹中已经有了build文件夹了，接着通过在.vscode文件夹->setting.json文件中添加以下内容实现对clangd的配置：

clangd配置
  "clangd.arguments": [
    "--compile-commands-dir=${workspaceFolder}/build", // 指向编译命令文件所在目录
    "--query-driver=/Applications/ArmGNUToolchain/14.2.rel1/arm-none-eabi/bin/arm-none-eabi-gcc", // 指定工具链驱动程序
    "--background-index", // 启用后台索引
    "--clang-tidy"        // 启用静态检查
  ],

注意

--query-driver=后面修改为你自己的实际ArmGnuToolchain的路径，注意看我的配置，后面的指定和之前的配置有区别

配置好后保存setting.json文件，通过control + shift + p执行clangd: restart language server后应该可以发现打开core/src/main.c代码文件里面没有报错了，并且代码提示也工作正常。在后续也许会发现一些文件依旧有报错，但是没关系不影响我们正常使用，只要build不出错，就说明我们的代码是正常的。

配置说明
直接配置可跳过

在我们创建tasks.json那一步，在configure任务中有一句命令是这样配置的 "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON" ，这是在显示的声明，在生成的build目录中会生成一个编译命令文件，文件名为compile_commands.json，这个文件中提供了头文件以及一些其他关键文件的位置信息，可以帮助clangd解析代码文件的依赖关系，从而实现代码的格式化和代码检查，我们上面配置的 "--compile-commands-dir=${workspaceFolder}/build" 就是在告诉clangd我们的这个编译命令文件所在的位置。

教程配置到这里，我们配置好的项目已经可以利用HAL库开发了，但在江科大的stm32教程中使用的是标准库开发，所以以下的教程是为了适配江科大的教程进行标准库的配置。

8. 适配江科大的stm32教程

我们的目录结构尽量做到和江科大教程的目录一样。在江科大教程的新建工程那一节，会复制几个文件到Start文件夹

先将项目根目录下的Core、Drivers、build、.cache（如果有的话）文件夹都删掉，然后新建Start、Library、User文件夹，即将要向这些文件夹中放一些文件，这些文件都是江科大的stm32视频中提供的，你可以自行下载江科大提供的文件，链接在这：江科大资料文件，也可以使用我提供的文件，都是一样的。
首先是startup_...文件，这个文件在我们用cubemx生成的项目中自带这个文件，在项目的根目录下，全名叫做 startup_stm32f103xb.s ，将这个文件移动到Start文件夹中
还有一些文件，下载后直接移动进Start文件夹，我提供的下载链接： Start中的文件，下载后放入Start文件夹中即可
接着是Library中的库文件，下载后直接放到文件夹中即可。我提供的下载链接： Library中的文件
下一个是User中的文件，方法同上，我提供的下载链接：User中的文件
接着在江科大教程中使用的keil5中需要手动添加头文件路径，我们这个项目也需要这样做，不过方法有些不同，在keil5中是通过设置然后选中添加，而在我们的项目中需要找到 cmake/stm32cubemx/CMakeLists.txt 这个文件，打开后会看到 target_include_directories 一栏和 target_sources 一栏，前者是添加头文件目录位置的，后者是添加具体的每个 .c 文件路径的。这两个地方在我们后面的教程中会经常的配置它，对于头文件，只需要把头文件所在的文件夹路径添加进来即可，但是对于.c文件，路径需要具体到每一个文件。
不过不用担心，我们不需要一次性将项目中所有的.c文件都添加进来，只需添加一些必要的，其他的在我们使用的时候再添加即可，比如在 main.c 中 #include "stm32f10x_rcc.h" 这个头文件了，那这时候就需要将 stm32f10x_rcc.c 这个文件的路径添加到这个cmake文件中了
接着我们开始配置，将这两栏里面现存的路径内容都删掉，然后添加以下路径配置：

target_include_directories配置块
target_include_directories(stm32cubemx INTERFACE

    ../../Start
    ../../Library/Inc
    ../../User
    
)

target_sources(stm32cubemx INTERFACE

    ../../Start/startup_stm32f103xb.s
    ../../Start/core_cm3.c
    ../../Start/system_stm32f10x.c
    
    ../../User/stm32f10x_it.c

)

提示

只复制配置块内的路径信息到相同的配置块内就可以了

由于我们使用的是标准库进行开发，刚刚导入的stm32f10x.h文件需要环境中有一个设备的宏定义，我们使用的c8t6属于中等容量（64-128KB Flash），所以，在cmake目录中的CMakeLists.txt文件，也就是我们刚打开的那个，找到配置块修改为：

CMakeLists.txt
target_compile_definitions(stm32cubemx INTERFACE 
    STM32F10X_MD #修改
    $<$<CONFIG:Debug>:DEBUG>
)

在我们刚复制到Start文件夹的 core_cm3.c 文件中有两处代码需要我们进行修改，不然build会报错。打开这个文件，command + f 搜索 strexb ，你会找到4个结果，导航到最后的那个结果，修改配置为：

core_cm3.c
//原始代码
__ASM volatile ("strexb %0, %2, [%1]" : "=r" (result) : "r" (addr), "r" (value) );

//修改为
__ASM volatile ("strexb %0, %2, [%1]" : "=&r" (result) : "r" (addr), "r" (value) );

其实就是在 “=r" 那里修改为 “=&r”
接着修改第二处，搜索 strexh ，依旧会搜到4个结果，导航到最后一个结果，修改配置为：

core_cm3.c
//原始代码
__ASM volatile ("strexh %0, %2, [%1]" : "=r" (result) : "r" (addr), "r" (value) );

//修改为
__ASM volatile ("strexh %0, %2, [%1]" : "=&r" (result) : "r" (addr), "r" (value) );

依旧是把 "=r" 修改成 "=&r"

配置好后，在User文件夹中新建一个main.c文件，并且在刚刚cmake文件的配置块中添加这个.c文件的路径 ../../User/main.c 并在main.c中输入以下内容：

main.c
#include "stm32f10x.h"

int main(void)
{
    
    while (1) 
    {
    
    }
}

这时候运行configure和build后会发现控制台会正常输出类似这个内容，如果有warning则不用管

js
[5/5] Linking C executable stm32test.elf
Memory region         Used Size  Region Size  %age Used
             RAM:        1568 B        20 KB      7.66%
           FLASH:         968 B        64 KB      1.48%

这说明我们的项目配置成功了，下一步就可以直接烧录程序了，连接好stm32执行flash即可。

教程到这里就结束了，如果有问题欢迎评论区留言。