跳到主要内容

5.3 项目构建 (CMake)​

ChipON VSCode Extension 采用现代 CMake + Ninja 构建系统，支持通过可视化界面管理不同构建预设（Build Configuration），并能够一键触发配置（Configure）、构建（Build）与清理（Clean）。

构建配置与工程体系​

项目初始化后，系统将在 cmake/ 目录与 .vscode/ 目录下生成标准化构建规则文件：

核心配置文件说明​

配置文件作用与职责维护建议
cmake/CMakeLists.txtCMake 工程顶层入口，负责定义工程、收集源码、添加头文件包含路径、链接库及输出目标当需要新增/删除源码文件、包含目录、引用的静态库或更换链接脚本（.ld）时修改
cmake/CMakePresets.json预设配置文件（Build Configuration 的来源），定义所有构建预设（Debug / Release 等）及编译宏建议优先通过图形化界面的 Add/Duplicate/Edit/Delete 操作管理；高级用户可手动调整 USER_*_FLAGS
cmake/configPresets.json项目级基础参数定义，包含目标芯片型号（CONFIG_CHIP_NAME）与工具链主路径（TOOLCHAIN_HOME）由插件根据工作区设置中的 chipon.toolchain.path 自动同步，无需手动编辑
cmake/flags.cmake编译与链接参数处理脚本，将预设中的各类 Flags 追加至系统默认 CMAKE_*_FLAGS需要设定对所有编译配置均生效的全局编译参数时可修改此脚本
.vscode/tasks.jsonVSCode 内部任务定义，包含 CMake: Configure、CMake: Build 与 CMake: Clean插件自动生成；切换激活配置时其中的 preset 字段会自动联动更新

构建配置管理 (Build Configuration)​

在 PROJECTS 视图中，展开 Build Configuration 节点，可通过右侧快捷图标执行配置管理：

1. 新增配置 (Add)​

点击 Build Configuration 右侧的 + (Add Build Configuration) 按钮。输入唯一的配置名称，并选择构建类型（Debug 或 Release）。插件将自动在 CMakePresets.json 中追加对应的 configure 与 build 预设项。

新增编译配置

2. 复制配置 (Duplicate)​

在已有配置条目上点击 Duplicate 图标。插件将完整克隆该配置的全部编译选项，并自动生成带递增后缀的新配置名（如 debug_1）。

复制编译配置

3. 编辑配置 (Edit)​

点击目标配置右侧的 Edit 图标，可在打开的可视化配置面板中直接调整各项编译参数：

  • C Flags：C 语言编译器选项（如优化等级 -O0/-O2、调试符号等级等）
  • C++ Flags：C++ 编译器专用参数
  • Assembly Flags：汇编器选项（如 -gdwarf-3）
  • Linker Flags：链接器选项（如内存段定义、优化选项）

编辑编译配置

4. 删除配置 (Delete)​

点击目标配置右侧的 Delete 图标，即可安全移除无用的编译配置项。

删除编译配置

执行构建与产物说明​

1. 激活目标配置 (Set as Default)​

在 PROJECTS 视图中展开 Build Configuration，在目标配置项右侧点击 Set as Default。成功激活后，配置名称旁将出现绿色 Active 状态标记。

激活编译配置

2. 触发构建​

开发者可通过以下任意方式触发项目编译：

  • PROJECTS 视图：鼠标悬停在工程根节点，点击右侧 编译 (Build) 按钮（🔨），或右键菜单选择 Build Project。
  • 资源管理器 (Explorer)：在工程文件夹上单击右键，选择 Build Project。
  • 命令面板：按快捷键 Ctrl + Shift + P，输入并执行 ChipON: Build Project。

执行编译

全量编译触发场景

在以下情况下，构建系统会自动触发全量重编译（Rebuild）：

  • 首次构建新工程
  • 执行 Clean Project 清理后重新构建
  • 切换不同的构建预设（如 Debug ↔ Release）
  • 修改了全局编译/链接参数或链接脚本
  • 手动删除了构建输出目录
构建诊断与注意事项
  • 自动 Configure 机制：插件会自动检测并判断是否需要先执行 CMake Configure（如首次编译或构建参数变更时）。
  • 日志窗口划分：CMake Configure 日志在底部 Output 面板的 CMake/Build 窗口中展示；实际的编译进度与错误日志则输出在 Terminal 面板中。
  • 手动触发 Configure：若手动修改了外部文件而未触发自动配置，可在 PROJECTS 视图中手动执行 Configure。

编译成功效果

3. 构建产物说明​

编译成功后，构建产物将输出在 cmake/<当前配置名>/ 目录下（如 cmake/debug/）：

产物文件格式类型主要用途
<project>.elfELF 可执行格式包含完整调试符号表，用于在线 GDB 调试与符号解析
<project>.hexIntel HEX 格式标准烧录固件，适用于生产烧录工具或上位机
<project>.binRaw Binary 格式连续二进制映像文件，常用于 Bootloader 升级
<project>.mapLinker Map 格式链接映射报告，用于详细分析各函数、变量的内存段与地址占用

命令行构建​

在独立脚本自动化或持续集成（CI/CD）环境中，开发者可以直接在终端通过命令行驱动构建：

1. CMake Configure 阶段​

在 Output 窗口中可获取插件生成的原生构建命令范例：

# 配置工程与构建预设
cmake \
  -DCMAKE_BUILD_TYPE=Debug \
  -DUSER_C_FLAGS="-O0 -g" \
  -DUSER_CXX_FLAGS="-O0 -g" \
  -DUSER_ASM_FLAGS="-gdwarf-3" \
  -DUSER_LINKER_FLAGS="" \
  -DCURRENT_PRESET=debug \
  -DCONFIG_CHIP_NAME=KF32A156MQV \
  -DCONFIG_ARCH=kf32r \
  -DENABLE_CPP=true \
   -DCMAKE_TOOLCHAIN_FILE="D:/toolchains/ChipONCC32/KungFu32-LLVM-Compiler-v0.1.6/cmake/llvm_toolchain.cmake" \
  -S "D:/code/my_project/cmake" \
  -B "D:/code/my_project/cmake/debug" \
  -G Ninja
2. CMake Build 阶段​
# 触发 Ninja 编译
cmake --build "D:/code/my_project/cmake/debug"
环境变量提示

独立在终端或 CI 脚本执行命令行构建前，请确保环境中已设置工具链根路径变量，例如：

CHIPON_TOOLCHAIN="D:\toolchains\ChipONCC32\KungFu32-LLVM-Compiler-v0.1.6"

清理构建 (Clean)​

ChipON VSCode Extension 支持一键清除构建中间文件及输出产物，相当于执行 CMake 的 clean 目标。

操作方式​

在 PROJECTS 视图工程节点或 Explorer 视图工程文件夹上单击右键，选择 Clean Project。

执行清理项目

清理完成后，cmake/<配置名>/ 目录下的目标编译产物将被重置。

完成执行清理