VSCode+arm-none-eabi-gcc交叉编译+CMake构建+OpenOCD（基于Pico rp2040的保姆级教程）

原创已于 2025-11-12 17:24:55 修改 · 901 阅读

7 ·

CC 4.0 BY-SA版权

文章标签：

#vscode #arm开发 #ide #rp2040

于 2025-07-06 17:54:17 首次发布

VSCode+单片机专栏收录该内容

16 篇文章

订阅专栏

部署运行你感兴趣的模型镜像

一、Pico SDK安装&pico-examples下载

1.1 Pico SDK的“三剑客”安装

我们先一键部署Pico SDK， Pico SDK下载地址如下：

raspberrypi / pico-setup-windows：https://github.com/raspberrypi/pico-setup-windows。
warning：实际上，在该仓库的README中，我们可以看到该仓库已存档并停止更新，官方更推荐VSCode上的Raspberry Pi Pico扩展插件，但这并不影响我们下载。

笔者将其安装在自定义的embedded_dev_tools文件夹下，其命名为Pico_SDK_v1.5.1。
在这里插入图片描述
其中有三个关键的依赖：

pico-sdk 是核心开发库，提供基础API和构建系统。
picotool 是依赖 pico-sdk 的独立工具，负责二进制处理和设备交互。
pico-sdk-tools 可能是工具集的统称，涵盖 picotool 或其他辅助工具。

pico-sdk、picotool、pico-sdk-tools三者共同构成完整的开发工具链，覆盖从代码编写、构建到固件部署的全环节。

1.1.1 pico-sdk

pico-sdk是Raspberry Pi Pico 系列的核心软件开发工具包，负责提供 C/C++ 开发环境、硬件抽象层（HAL）和底层库。

设置环境变量：按下Win键→输入“查看高级系统设置”→点击环境变量→在用户变量区中，新建一个用户变量名称PICO_SDK_PATH，如下图添加，之后一直点击确定即可。

1.1.2 pico-sdk-tools

pico-sdk-tools是 pico-sdk 的配套工具集合，依赖于 pico-sdk ，可能包含开发流程中的辅助工具（如日志分析、固件生成），提供自动化脚本或工具简化开发流程（如批量编译、烧录）。

设置环境变量：按下Win键→输入“查看高级系统设置”→点击环境变量→双击Path→添加pico-sdk-tools路径，如下图添加，之后一直点击确定即可。

1.1.3 picotool

picotool是专用于 RP2040/RP2350 设备的二进制处理和设备交互工具，pico-sdk 调用 picotool 完成固件转换（如 ELF→UF2）、签名等操作。

设置环境变量：按下Win键→输入“查看高级系统设置”→点击环境变量→双击Path→添加picotool路径，如下图添加，之后一直点击确定即可。

1.2 pico-examples例程包

pico-examples例程地址：https://github.com/raspberrypi/pico-examples，按下图所示，下载 pico-examples 压缩包。

我们将该pico-examples例程包解压缩后，无需设置环境变量，拷贝放在常用文件夹即可，里面有许多外设文件和demo工程供我们参考使用。

1.3 arm交叉编译器安装

下载地址： https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases/download/v14.2.1-1.1/xpack-arm-none-eabi-gcc-14.2.1-1.1-win32-x64.zip

解压缩到固定的安装目录，并设置环境变量，在cmd中输入arm-none-eabi-gcc -v确认是否安装成功。

1.4 CMake工具安装

下载地址：https://github.com/xpack-dev-tools/cmake-xpack/releases/download/v3.30.7-1/xpack-cmake-3.30.7-1-win32-x64.zip

解压缩到固定的安装目录，并设置环境变量，在cmd中输入cmake -v确认是否设置成功。

1.5 Ninja构建工具安装

下载地址： https://github.com/xpack-dev-tools/ninja-build-xpack/releases/download/v1.12.1-1/xpack-ninja-build-1.12.1-1-win32-x64.zip

解压缩到固定的安装目录，并设置环境变量，在cmd中输入ninja --version确认是否设置成功。

1.6 GNU Make构建工具安装

下载地址：https://github.com/xpack-dev-tools/windows-build-tools-xpack/releases/download/v4.4.1-3/xpack-windows-build-tools-4.4.1-3-win32-x64.zip

解压缩到固定的安装目录，并设置环境变量，在cmd中输入make -v或者where make确认是否设置成功。

1.7 openocd调试工具安装

下载地址：https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-6/xpack-openocd-0.12.0-6-win32-x64.zip

解压缩到固定的安装目录，并设置环境变量，在cmd中输入openocd -v确认是否设置成功。

1.8 J-Link下载工具安装

下载地址：https://www.segger.com/downloads/jlink/JLink_Windows_x86_64.exe

安装.exe到固定的安装目录，并设置环境变量，在cmd中输入jlink -v确认是否设置成功。

1.9 MinGW64—类Unix环境安装

下载地址：https://github.com/niXman/mingw-builds-binaries/releases/download/15.1.0-rt_v12-rev0/x86_64-15.1.0-release-win32-seh-ucrt-rt_v12-rev0.7z

解压缩到固定的安装目录，并设置环境变量，在cmd中输入gcc -v确认是否设置成功。

1.10 Python环境安装

下载地址：https://www.python.org/downloads/

安装.exe到固定的安装目录，并设置环境变量，在cmd中输入python --version确认是否设置成功。

1.11 Git Bash环境安装

下载地址：https://git-scm.com/downloads

安装.exe到固定的安装目录，并设置环境变量，在cmd中输入git -v确认是否设置成功。
打开开始菜单，键盘输入 git ，可确认是否装上Git Bash。
在这里插入图片描述

二、VSCode插件

在这里插入图片描述

Tips：
无需安装CMake、CMake Tools、Raspberry Pi Pico这3个插件，只需安装CMake Highlight插件，用于高亮显示CmakeLists.txt的语法。
至于原因的话，CMake和CMake Tools插件的作用是在VSCode中产生内置的CMake GUI，但我们不需要用GUI界面，而是使用后面的tasks.json中的自定义CMake命令，写入VSCode的内置终端执行即可。
因此我们禁用掉下述3个插件：
在这里插入图片描述

三、创建Pico rp2040 demo工程

笔者的工程目录和结构如下图所示，
在这里插入图片描述
其中：

.vscode目录为VSCode的内置json文件，需手动创建并自定义内容；
build目录无需手动创建，后续用命令配置CMake的时候会自动产生；
USER目录为自定义代码目录；
CMakeLists.txt为CMake构建脚本；
pico_sdk_import.cmake在Pico SDK包的\Pico_SDK_v1.5.1\pico-sdk\external文件夹中拷贝，如下图所示，pico_sdk_import.cmake文件见名知义，是引用Pico SDK中的 API 和库文件。

至此，demo工程初步创建完成。

四、.vscode文件的json脚本配置

4.1 settings.json

⭐内容无需修改，开箱即用⭐。

{
  // 字符集编码选择
  "files.encoding": "utf8",
  // 自动保存任意文件
  "files.autoSave": "afterDelay",
  // 文件图标主题:"material-icon-theme"
  "workbench.iconTheme": "material-icon-theme",
  // 颜色主题设置
  "workbench.colorTheme": "Default Dark Modern",
  //粘贴时格式化代码
  "editor.formatOnPaste": true,
  //保存时格式化代码
  "editor.formatOnSave": true,
  //设置字体的大小，最小值能设置为6
  "editor.fontSize": 15,
  //设置字体的粗细
  "editor.fontWeight": "500",
  //设置字体的样式
  // "terminal.integrated.fontFamily":"Courier New",
  //使用Ctrl+滚轮缩放编辑区的字体大小
  "editor.mouseWheelZoom": true,
  //使用Ctrl+滚轮缩放终端Terminal的字体大小
  "terminal.integrated.mouseWheelZoom": true,
  //设置为false，这样打开新的文件时，不会自动关闭旧的文件
  "workbench.editor.enablePreview": false,
  //这2行配置很重要！！！在tasks.json中的任务类型如果是"shell"，则这里的shell选择，关系到对应shell命令的使用适配与否。
  "terminal.explorerKind": "integrated",
  "terminal.integrated.defaultProfile.windows": "Command Prompt", //You can also choose from the following three shells："Command Prompt" or "PowerShell" or "Windows PowerShell" or "Git Bash"
    //warning 1：若想使用makefile.makePath配置，则需安装Makefile Tools插件；
    //warning 2：若想使用cmake.generator生成器配置，则需安装CMake和CMake Tools这两个插件
    /*
                                    👇
                                    👇
                                    👇
    */
    // "makefile.makePath": "E:/embedded_dev_tools/xpack-ninja-build-1.12.1-1/bin/ninja.exe",
    // "cmake.generator": "Ninja", // VSCode的CMake插件默认配置生成器为Ninja
    //
    // "makefile.makePath": "E:/embedded_dev_tools/xpack-windows-build-tools-4.4.1-2/bin/make.exe",
    // "cmake.generator": "Unix Makefiles",
  "files.associations": {
    "stdio.h": "c",
    "stdlib.h": "c"
  }
}

4.2 c_cpp_properties.json

⭐内容无需修改，开箱即用⭐。

{
  "configurations": [
    {
      "name": "Pico-RP2040_ARM_GCC",
      "includePath": [
        "${workspaceFolder}/**"
        // "${env:PICO_SDK_PATH}/**"
      ],
      "defines": [
        "__GNUC__"
      ],
      /*
      只要设置了系统环境变量，在此处填写arm-none-eabi-gcc即可。
      VSCode C/C++ IntelliSense插件会自动索引arm-none-eabi-gcc.exe所在路径，故无需在此填写完整路径。
      */
      "compilerPath": "arm-none-eabi-gcc",
      //这一配置在目前所搭建的环境下没用，但是如果你使用的是SDK，库和驱动文件与项目工程不在一个文件夹中，这一步就很有用了，它能让你在当前项目就能向库代码跳转。
      "compileCommands": "${workspaceFolder}/build/compile_commands.json",
      "cStandard": "gnu17",
      "cppStandard": "gnu++14",
      "intelliSenseMode": "gcc-arm",
      "configurationProvider": "ms-vscode.cmake-tools"
    }
  ],
  "version": 4
}

4.3 tasks.json

CMake编译工程分为2个步骤：CMake配置、CMake构建，分别对应下述json脚本的CMake configure任务和CMake build任务。关于该json脚本的命令行编写，各位可以参考Raspberrypi官方的Pico 系列微控制器命令行设置README：https://github.com/raspberrypi/pico-setup。

🍍🍍🍍修改要点如下：
① tasks.json内第135行"interface/jlink-swd.cfg"的jlink-swd.cfg文件来源请参考：OpenOCD之J-Link下载。

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "CMake configure",
            "type": "shell",
            "command": "cmake", //要执行的命令，前提是已经在系统环境变量PATH中安装了CMake
            "args": [
                //严格顺序要求：必须按 -S <source> -> -B <build> -> -G <generator> -> [其他选项] 的顺序排列，否则可能导致配置失败或逻辑错误
                "-S", //可选，-S <sourceDir>。若未显式指定，CMake 默认从当前工程目录开始查找 CMakeLists.txt。
                ".", // "."表示指定源代码目录为包含 CMakeLists.txt 的根目录。
                "-B", //必选，-B <buildDir>。配置生成Makefile or Ninja脚本及其相关文件的路径, 使得源码和构建过程文件分开，以便更好地管理项目
                "./build", //这条命令会告诉 CMake 在工程根目录下创建一个名为 build 的子目录（如果它不存在的话），并在该子目录下生成makefile/build.ninja/rules.ninja等构建文件
                "-G", //配置生成器类型
                "Ninja", //"Unix Makefiles",
                //"-D", //设置构建类型，可选择如下：Debug/Release/RelWithDebInfo/MinSizeRel
                //"CMAKE_BUILD_TYPE=Debug",
                "-D",
                "CMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE", //生成compile_commands.json的文件，该文件是为了让vscode有代码导航、自动补全和语法高亮功能。
                // "--debug-output" //显示详细的CMake配置过程信息，可用于调试 CMakeLists.txt 脚本的逻辑问题。
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": "$gcc"
        },
        {
            "label": "CMake build",
            "type": "shell", //直接使用shell的手动输入命令行“cmake --build {构建目录的相对路径} 其他可选的配置参数”
            "command": "cmake",
            "args": [
                "--build", //不论后端构建工具是Make or Ninja, 只需调用CMake的统一命令接口"--build", 便能实现在某个文件夹下构建(生成可执行文件)，具有跨平台特性。
                "${workspaceFolder}/build", //生成可执行文件.elf和进制文件.hex/.bin的路径
                "--config Debug",//选项优先级的大小：(构建阶段)--config > (配置阶段)-DCMAKE_BUILD_TYPE
                "--target ${workspaceRootFolderName}.elf", //"all",构建整个项目。允许指定单一或多个目标来构建，而不是构建整个项目，这可以显著减少构建时间。
                "--parallel 5", //CMake的现代化语法，其功能是并行编译，区别于 CMakeLists.txt 中的多线程功能开关：add_compile_options(-pthread)
                // "--verbose" //可简写为 -v，让底层的构建工具（如 Make 或 Ninja）输出详细的构建(编译和链接)过程信息，为CMake通用命令。
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "dependsOn": [
                "CMake configure"
            ],
            "problemMatcher": [
                "$gcc"
            ]
        },
        {
            "type": "shell",
            "label": "CMake cleanRebuild",
            "dependsOrder": "sequence",
            "dependsOn": [
                "CMake clean",
                "CMake build"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": [
                "$gcc"
            ]
        },
        {
            "label": "CMake clean",
            "type": "shell",
            // "command": "Remove-Item -Path ./build/* -Recurse", 
            ////powershell(windows10及以上的操作系统)可调用，只删除build目录下的所有文件。
            ////使用该命令的前提是在settings.json中设置了：
            //// "terminal.explorerKind": "integrated",
            //// "terminal.integrated.defaultProfile.windows": "PowerShell",
            /*
            ||此为分隔标识，无需反注释
            ||此为分隔标识，无需反注释
            ||此为分隔标识，无需反注释
            */
            // "command": "rmdir /q /s build", 
            ////cmd(windows操作系统任意版本)可调用，这会直接将build目录本身一起删除。
            ////使用该命令的前提是在settings.json中设置了：
            //// "terminal.explorerKind": "integrated",
            //// "terminal.integrated.defaultProfile.windows": "Command Prompt",
            /*
            ||此为分隔标识，无需反注释
            ||此为分隔标识，无需反注释
            ||此为分隔标识，无需反注释
            */
            "command": "rm -rf ./build/*", 
            ////rm -rf为Linux用法，只删除build目录下的所有文件。
            ////使用该命令的前提是在settings.json中设置了：
            //// "terminal.explorerKind": "integrated",
            //// "terminal.integrated.defaultProfile.windows": "Git Bash",
            //// 只要安装了像Git Bash的类Unix环境，Windows的cmd终端可以间接调用rm -rf命令，因此也可在settings.json中设置：
            //// "terminal.explorerKind": "integrated",
            //// "terminal.integrated.defaultProfile.windows": "Command Prompt",
            "args": [],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": [
                "$gcc"
            ]
        },
        {
            "label": "flash with CMSIS-DAP-Link",
            "type": "shell",
            "command": "openocd",
            "args": [
                "-f",
                "interface/cmsis-dap.cfg",
                "-f",
                "target/rp2040.cfg",
                "-c",
                "adapter speed 2000",
                "-c",
                "program build/${workspaceRootFolderName}.elf verify reset exit"
            ],
            "group": "build",
            "problemMatcher": [
                "$gcc"
            ],
            "dependsOn": [ //任务依赖
                "CMake build"
            ]
        },
        {
            "label": "flash with J-Link",
            "type": "shell",
            "command": "openocd",
            "args": [
                "-f",
                "interface/jlink-swd.cfg",
                "-f",
                "target/rp2040.cfg",
                "-c",
                "adapter speed 1000",
                "-c",
                "program build/${workspaceRootFolderName}.elf verify reset exit"
            ],
            "group": "build",
            "problemMatcher": [
                "$gcc"
            ],
            "dependsOn": [ //任务依赖
                "CMake build"
            ]
        }
    ]
}

4.4 launch.json

${env:VAR_NAME}是VSCode的特有语法，作用是动态引用系统环境变量（如 PATH、HOME 或自定义变量）。
在上面的Pico SDK环境变量设置中，笔者已经对Pico SDK中的pico-sdk建立了一个用户变量名：PICO_SDK_PATH，
可以注意到的是，launch.json中svdfile寄存器文件路径设置，是通过动态引用系统环境变量${env:PICO_SDK_PATH}来设置的。

🍍🍍🍍修改要点如下：
① launch.json内第40行"interface/jlink-swd.cfg"的jlink-swd.cfg文件来源请参考：OpenOCD之J-Link下载。

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Pico-rp2040 Debug with cmsis-dap-link",
      "cwd": "${workspaceRoot}",
      "executable": "./build/${workspaceRootFolderName}.elf",
      "request": "launch",
      "type": "cortex-debug",
      "servertype": "openocd",
      "device": "RP2040",
      "configFiles": [
        "interface/cmsis-dap.cfg",
        "target/rp2040.cfg"
      ],
      "svdFile": "${env:PICO_SDK_PATH}/src/rp2040/hardware_regs/rp2040.svd",
      "openOCDLaunchCommands": [
        "adapter speed 5000"
      ],
      "postRestartCommands": [
        "break main",
        "continue"
      ],
      "runToEntryPoint": "main",
      "showDevDebugOutput": "none",
      "preLaunchTask": "flash with CMSIS-DAP-Link" //每次调试之前会先下载程序
    },
    {
      "name": "Pico-rp2040 Debug with j-link",
      "cwd": "${workspaceRoot}",
      "executable": "./build/${workspaceRootFolderName}.elf",
      "request": "launch",
      "type": "cortex-debug",
      "servertype": "openocd",
      "device": "RP2040",
      "configFiles": [
        "interface/jlink-swd.cfg",
        "target/rp2040.cfg"
      ],
      "svdFile": "${env:PICO_SDK_PATH}/src/rp2040/hardware_regs/rp2040.svd",
      "openOCDLaunchCommands": [
        "adapter speed 5000"
      ],
      "postRestartCommands": [
        "break main",
        "continue"
      ],
      "runToEntryPoint": "main",
      "showDevDebugTimestamps": true,
      "showDevDebugOutput": "none",
      "preLaunchTask": "flash with J-Link" //每次调试之前会先下载程序
    }
  ]
}

五、CMakeLists.txt构建脚本

修改要点：
①

set(PICO_SDK_PATH “D:/Software/embedded_dev_tools/Pico_SDK_v1.5.1/pico-sdk”)

上述双引号中的路径修改为安装Pico_SDK的路径，位于第11行；
②

project(rp2040_blink C CXX ASM)

rp2040_blink为笔者的工程名称，需要将其修改为你自己的工程名称，位于第19行。
③

include_directories(
./USER/Inc
)

file(GLOB_RECURSE SOURCES
./USER/Src/*.c
)

include_directories是你工程的头文件相对路径；file是你工程的源文件相对路径，请自行修改，分别位于第57和61行。

CMakeLists.txt:

# Raspberry pi Pico Cmake工程

cmake_minimum_required(VERSION 3.20)

set(CMAKE_SIZE arm-none-eabi-size)

set(CMAKE_C_STANDARD 17)
set(CMAKE_CXX_STANDARD 14)

# 设置pico_sdk
set(PICO_SDK_PATH "D:/Software/embedded_dev_tools/Pico_SDK_v1.5.1/pico-sdk")

# 导入pico_sdk，必须放在工程之前
include(pico_sdk_import.cmake)

# 设置工程，名称可以根据需要设置
# project : 定义工程名称，并可以指定工程可支持的语言，语法格式为 project(项目域名 语言)
# .HEX  .bin  .elf  .map的文件名设置
project(rp2040_blink C CXX ASM)


#设置代码调试等级
set(CMAKE_BUILD_TYPE "Debug")
#   +---------------+---------------+--------------+--------------+----------+
#   |               |               | optimization | assert works | stripped |
#   +---------------+---------------+--------------+--------------+----------|
#   |               |     None      |              |              |          |
#   |    -g         |     Debug     |     no       |     yes      |    no    |
#   |-O3 -DNDEBUG   |    Release    |    full      |      no      |   yes    |
#   |-O2 -g -DNDEBUG| RelWithDebInfo|    good      |      no      |    no    |
#   |-Os -DNDEBUG   |   MinSizeRel  |    size      |      no      |   yes    |
#   +---------------+---------------+--------------+--------------+----------+
# Release 进行优化，提高速度 -排除调试信息
if ("${CMAKE_BUILD_TYPE}" STREQUAL "Release")
    message(VERBOSE "Maximum optimization for speed")
    add_compile_options(-Ofast)
# RelWithDebInfo 进行优化，提高速度 -包含调试信息
elseif ("${CMAKE_BUILD_TYPE}" STREQUAL "RelWithDebInfo")
    message(VERBOSE "Maximum optimization for speed, debug info included")
    add_compile_options(-Ofast -g)
# MinSizeRel 优化二进制大小 -排除调试信息
elseif ("${CMAKE_BUILD_TYPE}" STREQUAL "MinSizeRel")
    message(VERBOSE "Maximum optimization for size")
    add_compile_options(-Os)
# Debug 禁用优化 -包含调试信息
else ()
    message(VERBOSE "Minimal optimization, debug info included")
    add_compile_options(-Og -g)
endif ()


# 初始化SDK
pico_sdk_init()

#添加头文件路径，即.h文件
include_directories(
                    ./USER/Inc
                    )

file(GLOB_RECURSE SOURCES
     ./USER/Src/*.c
    )

add_link_options(-Wl,--print-memory-usage -Wl,--gc-sections -flto)

# 添加可执行文件
add_executable(${PROJECT_NAME} ${SOURCES})

#启用多线程支持
#⚠️仅适用于 GCC/Clang 等遵循 POSIX 标准的编译器，对 MSVC 无效（MSVC 通过 <thread> 头文件原生支持）
add_compile_options(-pthread)


# 设置工程信息
pico_set_program_name(${PROJECT_NAME} "${PROJECT_NAME}")
pico_set_program_version(${PROJECT_NAME} "0.1")

# 默认打开串口
pico_enable_stdio_uart(${PROJECT_NAME} 0)# 是否将串口数据的标准输入输出(stdin和stdout)重定向到UART 
pico_enable_stdio_usb(${PROJECT_NAME} 1)# 是否将串口数据的标准输入输出(stdin和stdout)重定向到USB CDC 

# 添加链接标准库
target_link_libraries(${PROJECT_NAME} pico_stdlib)

# Print executable size
add_custom_command(TARGET "${PROJECT_NAME}" POST_BUILD
        # COMMENT "Invoking: Cross ARM GNU Print Size"
        COMMAND ${CMAKE_SIZE} ${PROJECT_NAME}.elf
        )

# 除 ELF 文件外, 生成 map/bin/hex/uf2 文件
pico_add_extra_outputs(${PROJECT_NAME})