编译工程

本页说明 fw-AW30N_BLE_SDK 的工程编译完整流程：从环境准备、工具链安装、工程入口识别，到 Code::Blocks / Makefile / VS Code 三种编译方式的执行细节、编译产物与常见错误处理，帮助开发者快速把 SDK 源码编译为可烧录的固件。

目的与范围

本页聚焦「编译工程」这一环节，覆盖：

支持的操作系统与前置条件、杰理编译工具链（clang/pi32）的安装与验证；
SDK 工程入口（.cbp 工程文件、顶层 Makefile、make_prompt.bat）与工程目录结构；
三种编译方式（Code::Blocks、Makefile 命令行、VS Code 任务）的具体操作步骤；
编译命令速查、并行编译、编译产物（固件）的输出位置；
常见编译错误与解决办法、失败模式、性能与扩展建议。

以下内容属于兄弟主题，不在本页展开：

烧录与升级（USB 升级工具、生产烧写、OTA）——见 README「八、烧录与升级」；
功能配置（app_config.h 功能开关、BLE Profile 配置）——见 README「九、配置说明」；
环境搭建/工具链安装的详细下载方式——见 README.md。

本仓库是 AW30N 系列芯片的 SDK Release 版本，包含 SDK 源码及示例工程，编译时需要配合对应命名规则的预编译库文件（lib.a）一起链接（见 README.md）。因此编译过程不是单纯的源码编译，而是「应用源码 + 预编译库」的混合构建：应用层源码由工具链编译，芯片驱动、编解码器、协议栈等以静态库形式直接参与链接，最终经 post_build 后处理生成烧录固件。

SDK 面向 AW30N 全系列芯片，主推 BLE 蓝牙语音遥控器、BLE 对讲机、小音箱、语音玩具等应用，支持 BLE Core v5.4（QDID 223418）。仓库只提供一个统一的应用工程入口 AW30N_mbox_flash.cbp，通过配置即可覆盖全系列芯片型号，降低多工程维护成本。

架构

整个编译链路可以划分为源码层、构建层与产物层三个部分：

flowchart TD
    subgraph sg_Source["源码层"]
        Src["应用源码 apps/app/src/mbox_flash"]
        Hdr["头文件 apps/include_lib/*"]
        Lib["预编译库 apps/include_lib/liba (.a)"]
    end

    subgraph sg_Build["构建层"]
        CBP["AW30N_mbox_flash.cbp 工程"]
        MK["顶层 Makefile"]
        Toolchain["杰理编译工具链 clang/pi32"]
        Bat["tools/make_prompt.bat 环境入口"]
    end

    subgraph sg_Output["产物层"]
        PB["post_build 编译后处理"]
        Fw["固件镜像"]
        Doc["文档 doc/ 与 README"]
    end

    Src --> MK
    Hdr --> MK
    Lib --> MK
    CBP --> Toolchain
    MK --> Toolchain
    Bat --> MK
    Toolchain --> PB
    PB --> Fw
    Doc -.->|"编译指引"| MK

各层职责说明：

源码层：apps/app/src/mbox_flash/ 是唯一的应用入口目录（BLE 蓝牙/小音箱/音频播放应用），apps/include_lib/ 提供各功能模块的头文件与预编译静态库。由于库文件有命名规则约束，编译时必须保证库与工程匹配，否则链接阶段会报 cannot find -lxxx（见 README.md）。
构建层：AW30N_mbox_flash.cbp 是 Code::Blocks 工程文件，Makefile 是命令行构建入口，二者共享同一套杰理编译工具链（clang 交叉编译器）；make_prompt.bat 为 Windows 用户准备好 make 与环境变量的命令行环境。
产物层：编译成功后由 apps/app/post_build/ 的编译后处理脚本与工具生成固件镜像，供 USB 升级工具烧录。

设计意图：SDK 采用「源码 + 预编译库」的 Release 发布模式，既能让开发者修改应用层逻辑，又避免了暴露底层核心实现，同时保证全系列芯片共用统一的编译入口。

编译环境与前置条件

支持的操作系统

SDK 官方对三种主流操作系统的支持程度不同（见 README.md）：

系统	说明
Windows	推荐使用 Code::Blocks IDE 编译，或通过 `make_prompt.bat` 使用 Makefile 命令行编译
Linux	Makefile 命令行编译（需要重写 `download_sh.c` 脚本适配 Linux 环境）
macOS	需自行配置交叉编译工具链

设计意图：官方优先保障 Windows 下的开箱即用体验（提供 IDE 工程与批处理环境），Linux/macOS 属于进阶用法，需要开发者自行适配。

安装编译工具链

编译依赖杰理编译工具链（基于 clang 的交叉编译工具链），安装步骤如下（见 README.md）：

从杰理在线文档下载并安装工具链：下载链接；
Linux 用户可访问 pkgman.jieliapp.com 下载，解压到 /opt/jieli 目录，并确保 /opt/jieli/pi32/bin/clang 存在；
安装完成后执行 clang --version 验证。

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

Source: README.md

编译相关工具

工具	用途	获取方式
USB 升级工具	将编译产物固件烧录到目标板	申请链接 · 使用文档
生产烧写工具	量产/裸片烧写	代理商处 · 使用文档
无线测试盒	空中升级/射频标定/产品测试	申请链接 · 使用文档

编译本身不依赖这些烧录工具，但它们负责把编译产物部署到目标板，是编译→烧录闭环中的下一环（见 README.md）。

工程入口与目录结构

克隆仓库后进入 sdk/ 目录即完成工程定位：

git clone https://gitee.com/Jieli-Tech/AW30N.git
cd AW30N/sdk

Source: README.md

工程文件

工程文件	芯片	应用类型
`AW30N_mbox_flash.cbp`	AW30N 全系列	BLE 蓝牙 / 小音箱 / 音频播放

应用代码入口为 sdk/apps/app/src/mbox_flash/（蓝牙语音遥控器/对讲机/小音箱/音频播放应用）。

目录结构速览

fw-AW30N/
├── sdk/                           # SDK 主目录
│   ├── apps/                      # 应用层代码
│   │   ├── app/                   #   应用入口源码
│   │   │   ├── src/mbox_flash/    #     应用源码（唯一应用入口）
│   │   │   ├── bsp/               #     板级支持包（BSP）
│   │   │   └── post_build/        #     编译后处理脚本与工具
│   │   └── include_lib/           #   头文件与预编译库
│   │       ├── cpu/decoder/encoder/audio/device/...  # 各模块 API 头文件
│   │       └── liba/              #     预编译库 (.a)
│   ├── tools/                     # 编译工具与脚本
│   │   ├── make_prompt.bat        #   Windows 编译命令行入口
│   │   └── utils/                 #   工具集（make、rm 等）
│   ├── Makefile                   # 顶层 Makefile
│   └── *.cbp                      # Code::Blocks 工程文件
├── doc/                           # 文档（规格书/原理图/SDK 手册等）
└── README.md                      # 本文件

Source: README.md

关键点：

post_build/ 是编译产物的输出目录，同时存放编译后处理脚本，负责把链接结果打包成烧录固件；
tools/make_prompt.bat 是 Windows 命令行的「魔法入口」，它预先配置好 make 路径与相关环境变量，避免用户手动设置；
include_lib/liba/ 是预编译库目录，缺少对应库文件时链接失败（详见「常见编译错误」）。

三种编译方式

方式一：Code::Blocks（推荐 Windows 用户）

确保已安装杰理编译工具链；
双击打开 AW30N_mbox_flash.cbp 工程文件；
点击 Build → Build（Ctrl+F9）；
编译成功后，固件生成在 post_build/ 目录下（见 README.md）。

IDE 方式隐藏了 Makefile 细节，适合初次接触 SDK 的开发者；.cbp 工程与 Makefile 共用同一套工具链与源码，两种方式产物一致。

方式二：Makefile 命令行

# Windows 用户：双击 sdk/make_prompt.bat 打开命令行环境
# 编译
make -j4

# 显示编译详情
make VERBOSE=1 -j4

Source: README.md

# Linux 用户（需要自行修改 download_sh.c 文件适配 Linux）
cd sdk
make -j`nproc`

Source: README.md

-j 参数开启并行编译，数字为并行任务数；VERBOSE=1 输出完整编译命令，便于排查编译选项与链接细节。

方式三：VS Code

仓库已预配置 VS Code 任务，按 Ctrl+Shift+B 即可选择编译目标（见 README.md）。适合习惯编辑器工作流的开发者，底层仍然调用 Makefile 构建。

核心编译流程

一次完整的编译从开发者发起构建到产出固件，控制流如下：

flowchart TD
    Start([开始编译]) --> Env{"编译环境?"}
    Env -->|"Windows"| CB["Code::Blocks Build / make_prompt.bat + make -j4"]
    Env -->|"Linux"| MK["make -j nproc"]
    Env -->|"macOS"| Manual["手动配置交叉编译工具链"]
    CB --> TC["杰理编译工具链 clang/pi32 编译应用源码"]
    MK --> TC
    Manual --> TC
    TC --> Link{"链接预编译库 lib.a?"}
    Link -->|"缺少/不匹配"| Err["cannot find -lxxx 链接错误"]
    Link -->|"存在"| PB["post_build 编译后处理"]
    Err --> Fix["检查 apps/include_lib/liba/ 或 Makefile target"]
    Fix --> Link
    PB --> Out["生成固件"]
    Out --> Flash["USB 升级工具烧录"]

各步骤的职责：

环境判定：Windows 下推荐 Code::Blocks 或 make_prompt.bat 命令行；Linux 下直接用 make（需先适配 download_sh.c）；macOS 需自行搭建工具链；
源码编译：工具链（clang/pi32）编译 apps/app/src/mbox_flash/ 应用源码；
链接：把应用目标文件与 include_lib/liba/ 下的预编译库链接。库文件缺失或与芯片型号不匹配时在此阶段报错；
后处理：post_build/ 脚本把链接产物整理为烧录固件镜像；
烧录：使用 USB 升级工具将固件烧录到目标板（属于下一环节，不在本页展开）。

编译命令速查表

以下命令在 sdk/ 目录下执行（见 README.md）：

目标	命令
编译	`make -j4`
编译（verbose）	`make VERBOSE=1 -j4`
清理	`make clean`

make clean 用于清除上次构建的中间产物，在切换应用配置或芯片型号后建议先清理再重新编译，避免陈旧目标文件干扰链接。

编译产物

编译成功后，固件镜像输出到 apps/app/post_build/ 目录（见 README.md）；
产物即烧录工具所需的固件文件，供 USB 升级工具选择并下载到目标板；
关于烧录镜像配置文件 ISD_CONFIG.INI 的说明见 ISD 配置说明。

提示：编译前请确保 USB 升级工具正确连接且目标板已进入编程模式（见 README.md）。

编译过程中的失败与重试路径

sequenceDiagram
    participant Dev as 开发者
    participant Shell as 命令行环境 make_prompt.bat
    participant Make as Makefile 构建系统
    participant TC as 编译工具链 clang/pi32
    participant Ld as 链接器 + lib.a
    participant PB as post_build 脚本

    Dev->>Shell: 双击 make_prompt.bat（Windows）
    Dev->>Make: make -j4
    Make->>TC: 编译应用源码
    TC-->>Make: 目标文件 (.o)
    Make->>Ld: 链接预编译库
    alt 缺少库文件
        Ld-->>Dev: cannot find -lxxx
        Dev->>Make: 检查 liba/ 目录后重试
    else 库文件匹配
        Ld->>PB: 生成镜像
        PB-->>Dev: 固件输出到 post_build/
    end

该序列图展示了 Makefile 方式下一次构建的完整调用链，以及链接失败时的重试路径：失败点集中在链接阶段，修复手段是补全/匹配 liba/ 目录下的预编译库。

配置选项

编译行为相关的配置项如下（源码层面的功能开关见 README「九、配置说明」，不在本页展开）：

配置项	类型	默认值	说明
`make -j<N>`	命令行参数	无（单任务）	并行编译任务数，如 `-j4`；Linux 可用 `-j\`nproc`` 自动取核数
`make VERBOSE=1`	环境/命令行变量	关闭	输出完整编译命令与链接详情，用于排查编译选项
`make clean`	目标	—	清理中间产物，切换配置后建议执行
`download_sh.c`	源码脚本	适配 Windows	Linux 编译需重写该脚本以适配 Linux 环境
`app_config.h`	头文件	默认功能集	位于 `apps/app/src/mbox_flash/`，控制目标应用的功能开关
芯片型号	`.cbp`/配置	AW30N 全系列统一入口	切换芯片型号时需保证 Makefile target 与型号匹配

说明：VERBOSE 与 -j 的使用示例见 README.md；功能配置见 README.md。

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

常见编译错误对照表

README「7.4 常见编译错误」给出了官方排错指引（见 README.md）：

错误提示	原因	解决方法
`clang: command not found`	未安装杰理编译工具链，或环境变量未配置	按「安装编译工具链」章节安装并验证 `clang --version`
`cannot find -lxxx`	缺少对应的 `.a` 库文件	检查 `apps/include_lib/liba/` 目录是否齐全
`make: command not found`	Windows 下 `make` 不在 PATH	使用 `tools/make_prompt.bat` 打开预配置命令行环境
链接错误	Makefile target 与当前芯片型号不匹配	检查 Makefile target 是否匹配当前芯片型号

失败模式分析

工具链缺失（环境失败）：最常见的首编失败原因。Windows 下表现为 clang 命令不可用，Linux 下表现为 /opt/jieli/pi32/bin/clang 不存在。该失败发生在编译早期，可通过工具链验证命令提前暴露。
库文件缺失（链接失败）：SDK 采用 Release 发布模式，链接阶段强依赖 liba/ 目录下的预编译库。库缺失或命名不匹配时链接器报 cannot find -lxxx。这是「源码 + 预编译库」模式的固有边界——开发者无法修改库内部实现，只能保证库文件与 SDK 版本配套。
平台适配失败（Linux 边界）：download_sh.c 默认适配 Windows，Linux 下直接编译会在下载/烧录脚本环节出错，需重写该脚本。这是官方明确标注的平台边界。
芯片型号不匹配（配置边界）：切换芯片型号后若 Makefile target 未同步更新，会触发链接错误。SDK 通过全系列统一编译入口降低该风险，但仍需保持配置一致。

并发与一致性

编译阶段支持 -j 并行，多任务并发编译可显著提速；但并行任务数过高会耗尽内存，建议按 CPU 核数设置（Linux 下 -j\nproc``）；
make clean 与 make 不应并行执行（先清理再编译），否则可能因中间文件被删除而产生竞态；
SDK 发布模式下库文件为静态预编译产物，编译期无需并发访问外部服务，构建具备可重复性。

性能与运维建议

加快编译：使用 make -j4（或按核数提高）并行编译；Windows 下经 make_prompt.bat 进入环境后再执行，避免 shell 路径问题拖慢构建（见 README.md）；
排查问题：make VERBOSE=1 -j4 输出完整命令，便于定位具体编译/链接选项；
产物管理：固件统一输出到 post_build/，版本管理时建议连同对应的 lib.a 库与 SDK 版本一起归档，保证可复现；
构建可重复性：Release SDK + 静态库的组合使同一份源码在任何平台上产出一致的固件（除平台适配脚本差异外）。

扩展点

新建工程：基于现有 .cbp 工程和 apps/app/src/ 中的应用代码修改，配置对应用例即可（见 README.md）；
切换芯片型号：在配置中选择对应芯片型号，SDK 已为全系列预配置统一的编译入口（见 README.md）；
功能裁剪/使能：编辑 sdk/apps/app/src/mbox_flash/app_config.h 配置应用功能开关，编译时自动纳入/排除对应模块（见 README.md）；
编译后处理：apps/app/post_build/ 存放编译后处理脚本与工具，可在产物生成阶段插入自定义打包/校验逻辑；
GATT 服务定制：通过 BLE Profile 制作工具配置 GATT 服务，编译入口不变。

使用示例汇总

完整的最小编译流程（Windows）

# 1. 克隆仓库
git clone https://gitee.com/Jieli-Tech/AW30N.git
cd AW30N/sdk

# 2. 进入预配置命令行环境（Windows）
#    双击 sdk/make_prompt.bat

# 3. 编译（并行 4 任务）
make -j4

# 4. 排查时输出完整编译详情
make VERBOSE=1 -j4

# 5. 清理中间产物
make clean

Sources: README.md · README.md · README.md

Linux 命令行编译

cd sdk
# 使用全部 CPU 核数并行编译
make -j`nproc`

提示：Linux 下需先重写 download_sh.c 脚本适配 Linux 环境（见 README.md）。

Code::Blocks IDE 编译

双击打开 AW30N_mbox_flash.cbp；
Build → Build（Ctrl+F9）；
固件生成于 post_build/ 目录（见 README.md）。

常见问题（FAQ）

README「十、常见问题」给出了开发者高频疑问的官方答复（见 README.md）：

Q: Windows 下编译报错 make 不是有效命令？ A: 使用 sdk/make_prompt.bat 进入预配置的命令行环境，该脚本已设置好所有环境变量和 make 的路径。

Q: 如何加快编译速度？ A: 使用 -j 参数进行并行编译，如 make -j4（数字为并行任务数）。

Q: 如何创建一个新的工程？ A: 基于现有的 .cbp 工程和 apps/app/src/ 中的应用代码进行修改，配置对应用例即可。

Q: 如何切换不同的芯片型号？ A: 在配置中选择对应的芯片型号，SDK 已为全系列预配置了统一的编译入口。

调试技巧

串口日志：编译时保留调试选项，运行期通过 UART 输出调试日志；
BLE 抓包：使用 BLE Dongle 进行空中抓包分析（见 README.md）。

小结

编译工程是 AW30N SDK 开发闭环的起点：在 Windows 下推荐 Code::Blocks 或 make_prompt.bat + make -j4 完成构建，产物输出到 post_build/ 后交由 USB 升级工具烧录。编译的本质是「应用源码 + 预编译静态库」的混合链接，因此绝大多数失败都集中在工具链缺失、库文件不匹配与平台适配三类问题上，按本文档的排错表即可快速定位解决。

编译工程

目的与范围

概述

架构

编译环境与前置条件

支持的操作系统

安装编译工具链

编译相关工具

工程入口与目录结构

工程文件

目录结构速览

三种编译方式

方式一：Code::Blocks（推荐 Windows 用户）

方式二：Makefile 命令行

方式三：VS Code

核心编译流程

编译命令速查表

编译产物

编译过程中的失败与重试路径

配置选项

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

常见编译错误对照表

失败模式分析

并发与一致性

性能与运维建议

扩展点

相关链接

使用示例汇总

完整的最小编译流程（Windows）

Linux 命令行编译

Code::Blocks IDE 编译

常见问题（FAQ）

调试技巧

小结