编译脚本与命令行工具

AC82N GP-MCU SDK 的编译脚本与命令行工具体系，覆盖从环境准备、Makefile 命令行编译、Windows 命令行入口到 Code::Blocks / VS Code 集成构建的完整链路，以及编译产物（sdk.elf）与烧录脚本的衔接方式。

Purpose and Scope

本页面向 SDK 使用者与集成工程师，系统说明 fw-AC82N_GP-MCU_SDK 中与"编译"相关的一切入口与脚本：

• 三种构建方式：Makefile 命令行、Code::Blocks IDE、VS Code 任务；
• 命令行工具链（杰理 pi32 clang 工具链）的安装与验证；
• Windows 命令行入口 tools/make_prompt.bat 与工具集 tools/utils/；
• 顶层 Makefile 的统一编译入口与目标（all / clean）；
• 编译产物 cpu/cd09/tools/sdk.elf 的生成位置及其与下载/烧录脚本的衔接；
• Code::Blocks 工程文件 AC82N_gp_mcu.cbp 与 .vscode/tasks.json 的预配置行为。

边界说明：本页不展开烧录/升级工具本身（USB 升级工具、生产烧写工具属于"烧录与升级"主题），也不涉及 UBOOT 工程、UI 工程等独立编译单元的内部细节——它们作为独立工程存在，仅在本页提及。硬件资料与 SDK 版本历史见 README 中的外部链接。

说明：当前仓库根目录仅包含 README.md、README-en.md 与 LICENSE，SDK 主体（sdk/ 下的 Makefile、tools/ 脚本、.vscode/ 配置）通过 Gitee 子模块/仓库结构分发。本页内容以仓库内 README 对构建体系的权威描述为准，并对无法直接读取的文件明确标注。

Overview

AC82N 系列是杰理科技面向无蓝牙功能通用 MCU SoC 的 SDK（支持 cd09 平台的 AC822B / AC823B / AC825A / AC826B），典型应用为体脂秤、传感器采集、血压计等高精度测量与低功耗产品。固件工程包含预编译静态库（liba/ 下的 *.a 文件）与源码，必须配合对应命名规则的库文件才能完成链接。

编译体系的设计意图（WHY）：

1. 多入口、单一构建核心：无论从 IDE 还是命令行发起编译，最终都收敛到顶层 Makefile，保证同一份构建规则、同一份产物，避免"IDE 能编译、命令行编不过"的分裂。
2. Windows 优先的开发者体验：官方推荐 Windows + Code::Blocks；tools/make_prompt.bat 为命令行用户一键准备带工具链环境的控制台，避免手工设置 PATH。
3. 产物路径固定化：编译输出固定到 cpu/cd09/tools/sdk.elf，使烧录脚本可以"自动调用"，无需用户在构建与烧录之间手工搬运固件。
4. 平台差异化处理：Windows 开箱即用；Linux 支持 Makefile 命令行；macOS 需自行配置交叉编译工具链——文档明确标出三种系统的支持等级。

flowchart TD
    subgraph sg_Env["环境层 (Environment)"]
        TC["杰理编译工具链<br/>(pi32 clang)"]
        CB["Code::Blocks IDE"]
        VS["VS Code (tasks.json)"]
    end

    subgraph sg_Entry["编译入口层 (Entry Points)"]
        BAT["tools/make_prompt.bat<br/>Windows 命令行入口"]
        MK["Makefile<br/>(顶层统一入口)"]
        CBP["AC82N_gp_mcu.cbp<br/>Code::Blocks 工程"]
    end

    subgraph sg_Utils["工具层 (Utilities)"]
        UTILS["tools/utils/<br/>(make / rm 等工具)"]
    end

    subgraph sg_Out["产物层 (Outputs)"]
        ELF["cpu/cd09/tools/sdk.elf"]
        SCRIPTS["链接脚本 / 下载脚本<br/>(cpu/*/tools/)"]
    end

    BAT -->|"进入带工具链的 shell"| MK
    CB --> CBP
    CBP -->|"调用编译器/链接器"| TC
    VS -->|"Ctrl+Shift+B 选择 all/clean"| MK
    MK --> TC
    MK --> UTILS
    MK --> ELF
    ELF -->|"烧录脚本自动调用"| SCRIPTS

架构说明：所有入口（批处理、IDE、VS Code 任务）最终都指向顶层 Makefile；Makefile 调用杰理 pi32 工具链（/opt/jieli/pi32/bin/clang）与 tools/utils/ 中的辅助工具完成编译链接；产物固定输出为 cpu/cd09/tools/sdk.elf，与 cpu/*/tools/ 下的链接脚本、下载脚本配合完成烧录。

编译方式总览

命令行编译流程

顶层 Makefile：统一编译入口

Makefile 位于 sdk/ 根目录，是全部构建路线的汇聚点。README 明确列出两个目标：

• make all —— 执行完整编译；
• make clean —— 清理编译中间产物。

设计上，Makefile 不区分"哪个 IDE 发起"，因此 Code::Blocks 工程（.cbp）与 VS Code 任务（tasks.json）实际上都只是对同一构建规则的不同前端。多核机器可用 -j 参数并行加速：

# Linux/macOS 用户
cd sdk 根目录
make all -j`nproc`

Source: README.md

Windows 命令行入口：tools/make_prompt.bat

tools/make_prompt.bat 是 Windows 下命令行编译的"环境引导器"。它的作用是在当前终端中加载杰理工具链环境（PATH 等），使用户能直接执行 make 系列命令，无需手工配置交叉编译环境：

# Windows 用户
双击 tools/make_prompt.bat 打开命令行环境

Source: README.md

与其配套的是 tools/utils/ 目录，README 将其描述为"工具集（make、rm 等）"——即在 Windows 环境下随 SDK 分发的 GNU 工具集合，保证 make、rm 等命令在无原生 POSIX 工具的 Windows 上可用。

Source: README.md

工具链安装与验证

命令行编译依赖杰理编译工具链（基于 pi32 架构的 clang 交叉工具链）：

1. 从杰理工具链下载页下载安装；
2. Linux 用户可从 pkgman.jieliapp.com 下载，解压到 /opt/jieli，并确认 /opt/jieli/pi32/bin/clang 存在；
3. 安装后验证：

# 验证工具链是否安装成功
clang --version

Source: README.md

平台支持矩阵（来自 README 环境搭建章节）：

Source: README.md

编译产物与烧录衔接

编译完成后生成 cpu/cd09/tools/sdk.elf。README 特别提示：烧录脚本会自动调用该产物。也就是说，ELF 文件与 cpu/*/tools/ 下的下载脚本/链接脚本（README 将其描述为"烧录/链接工具：下载脚本、链接脚本"）组成"编译 → 链接 → 烧录"闭环：

# 提示：编译完成后会生成 cpu/cd09/tools/sdk.elf，烧录脚本会自动调用。

Source: README.md

Source: README.md

这一设计的关键在于：sdk.elf 的路径是构建体系与烧录体系的契约。只要编译成功，烧录工具无需任何参数即可定位固件，减少了人工搬运固件导致的版本错配风险。

VS Code 任务集成

仓库预配置了 .vscode/tasks.json（位于 sdk/ 工程根目录），按 Ctrl+Shift+B 即可弹出任务选择，覆盖 all / clean 两个编译目标。它本质上是 Makefile 目标在 VS Code 任务面板中的映射，适合习惯编辑器内构建的开发者。

Source: README.md

Code::Blocks 工程

AC82N_gp_mcu.cbp 是 Code::Blocks 工程文件，双击打开后执行 Build → Build（Ctrl+F9）即可完成编译。该工程同样调用同一套工具链与构建规则，是 Windows 用户的首选路线。

Source: README.md

核心流程

下面以"开发者修改代码后完成一次固件构建"为主线，展示三种入口如何汇入同一条构建流水线：

sequenceDiagram
    participant Dev as 开发者
    participant Entry as 编译入口<br/>(BAT / .cbp / tasks.json)
    participant Make as 顶层 Makefile
    participant Tool as 杰理工具链<br/>(pi32 clang) + tools/utils
    participant Out as cpu/cd09/tools/sdk.elf
    participant Burn as 烧录/下载脚本

    Dev->>Entry: 选择入口（双击 BAT / Ctrl+F9 / Ctrl+Shift+B）
    Entry->>Make: 发起 all 目标（make all）
    Make->>Tool: 调用 clang 编译源码 + 链接 liba/*.a
    Tool-->>Make: 返回编译结果
    Make-->>Out: 生成 sdk.elf
    Out->>Burn: 烧录脚本自动定位产物
    Burn-->>Dev: 烧录完成 / 返回错误

流程要点：

1. 入口选择不改变构建语义——BAT 只是准备环境，.cbp 与 tasks.json 只是不同前端，真正的构建决策全部落在顶层 Makefile；
2. 工具链解析：Makefile 依赖 /opt/jieli/pi32/bin/clang（Linux 布局），若缺失则编译失败，这是最常见的环境性错误；
3. 链接依赖：链接阶段需要与芯片型号匹配的预编译库（cpu/*/liba/*.a），README 强调"需配合对应命名规则的库文件进行编译"，库不匹配是典型的链接期错误来源；
4. 产物契约：sdk.elf 路径固定，烧录脚本据此自动调用，无需人工传参。

使用示例

示例一：Linux 全量并行编译

# Linux/macOS 用户
cd sdk 根目录
make all -j`nproc`

-j\nproc`用本机逻辑核数并行编译，显著缩短大工程构建时间；产物固定输出到cpu/cd09/tools/sdk.elf`。

Source: README.md

示例二：Windows 命令行环境引导

# Windows 用户
双击 tools/make_prompt.bat 打开命令行环境

进入该环境后即可执行与 Linux 一致的 make all -j 等命令，tools/utils/ 提供 make、rm 等 GNU 工具保证命令可用。

Source: README.md

示例三：工具链安装验证

# 验证工具链是否安装成功
clang --version

该命令用于确认交叉编译工具链已正确加入 PATH；Linux 用户还需确认 /opt/jieli/pi32/bin/clang 实际存在。

Source: README.md

示例四：IDE 内构建

• Code::Blocks：双击 AC82N_gp_mcu.cbp → Build → Build（Ctrl+F9）；
• VS Code：按 Ctrl+Shift+B，在任务列表中选择 all 或 clean。

Source: README.md

Source: README.md

配置选项

以下选项来自 README 对构建体系的可验证描述（Makefile 内部变量未在本仓库直接暴露，暂无法逐一枚举）：

注：tools/make_prompt.bat 无用户可调参数，双击即用；.vscode/tasks.json 已预配置 all / clean 两个任务，可在 VS Code 中进一步自定义。

失败模式、边界情况与并发

失败模式

边界情况

• 平台差异：make_prompt.bat 与 tools/utils/（make/rm 等）专为 Windows 设计；Linux 直接使用系统 make。两套环境的命令语法一致，但路径约定不同（Windows 无 /opt/jieli 布局）。
• 空工程/无修改构建：make all 在无变更时依赖 make 的文件时间戳机制跳过重编译，快速返回；make clean 用于强制全量重建。
• 独立工程：UBOOT 工程、UI 工程需独立编译，不在 GP MCU 顶层 Makefile 的 all 目标范围内——修改它们后必须单独构建，再回归主工程。

并发与一致性

• 并行编译（-j\nproc`）可大幅缩短构建时间，但输出日志交错，定位错误时建议先以串行（去掉 -j`）重跑复现；
• 构建产物路径是体系级契约（cpu/cd09/tools/sdk.elf），并行构建多个工程或并发烧录时需避免对同一产物目录的竞争写入；
• make clean 与编译不要并行执行（例如 IDE 后台构建时另开终端 clean），否则可能产生文件竞争导致构建损坏。

性能与运维注意事项

• 并行加速：官方示例即使用 -j\nproc`，说明工程体量适合并行构建；CI 中可固定 -j $(nproc)` 以复用资源。
• 环境可复现性：Linux 下工具链路径固定为 /opt/jieli，CI 容器应确保该路径存在且版本一致，避免"本地能编、CI 失败"。
• 产物与烧录衔接：编译产物直接由烧录脚本自动调用，因此版本管理应以 sdk.elf 为基准，构建后立即归档，防止与源码快照错位。
• 预编译库依赖：liba/*.a 是二进制依赖，升级 SDK 或切换芯片型号时须同步替换库，并清理（make clean）后重新链接。

扩展点

1. 新增 make 目标：在顶层 Makefile 中按 all / clean 的模式扩展（如 debug、release、dist 打包目标），IDE 与 VS Code 入口无需改动即可继承。
2. VS Code 任务自定义：.vscode/tasks.json 是独立于 Makefile 的前端层，可增删任务（如绑定调试前构建）而不影响命令行行为。
3. 烧录脚本扩展：cpu/*/tools/ 下的下载脚本可扩展支持新烧录器或量产模式，只要保持自动定位 sdk.elf 的约定即可。
4. 独立工程接入：UBOOT 工程、UI 工程可通过在顶层 Makefile 中增加依赖/子目标，纳入统一构建流水线（当前为独立编译）。

测试与验证

SDK 仓库本身以示例工程（cpu/demo/ 下的 hadc_demo.c、uart_demo.c、rtc_demo.c 等）作为功能验证载体：修改外设驱动后，通过 make all 重建并烧录示例即可回归验证。构建体系的正确性验证路径为：make all 成功 → 生成 sdk.elf → 烧录 → 观察外设行为。工具链版本变更后，建议先用任一 demo 工程做冒烟编译。

Related Links

• README.md（工程总览与编译指南）
• README.md（工程结构与 tools 目录）
• README-en.md（英文版说明）
• AC82 文档中心（编译与烧录官方文档）
• 杰理编译工具链下载（开发环境）
• USB 升级工具使用文档（烧录环节）
• SDK 版本历史