环境搭建与编译工具链

本文档介绍 fw-AD16N_GP-MCU_SDK 开发环境的前置条件、杰理编译工具链的安装与验证方法，以及 Code::Blocks、Makefile、VS Code 三种编译方式的完整使用流程。内容基于仓库根目录 README.md 的官方说明整理。

Purpose and Scope

本页面覆盖「环境搭建与编译工具链」这一主题的完整内容：

支持的宿主操作系统与推荐工具（Windows / Linux / macOS）
杰理编译工具链（基于 clang 的 Pi32 交叉编译器）的下载、安装与验证
烧录工具（USB 升级工具、生产烧写工具）与音频辅助工具的获取
三种编译方式（Code::Blocks 图形化、Makefile 命令行、VS Code 任务）的详细操作
编译命令速查、编译产物位置与常见编译错误排查

以下相关主题属于独立页面，不在本页展开：

快速开始：克隆仓库与工程入口，见「2-getting-started」目录相关页面
烧录与升级：首次烧录、生产烧写与 OTA 升级的详细流程，本页仅涉及烧录工具的安装
配置说明：app_config.h 功能开关与芯片选型配置
工程结构：sdk/ 目录的完整组织方式

Overview

fw-AD16N_GP-MCU_SDK 是杰理科技为 AD16N 系列芯片（AD160A/AD161A/AD162A/AD165A/AD166A/AD168A 等）提供的通用 MCU SDK。该 SDK 的编译强依赖杰理自研的编译工具链：SDK 源码与预编译库（.a 文件）必须通过该工具链中基于 clang 的 Pi32 交叉编译器才能正确链接成可运行的固件镜像。

设计上，SDK 采用「预编译库 + 开源应用层」的发布形态：

sdk/apps/include_lib/liba/ 存放按命名规则发布的预编译库（.a），应用层代码依赖这些库的 API；
编译时工具链将应用层源码与预编译库链接，生成最终固件；
固件产物输出到 post_build/ 目录，再通过 USB 升级工具或生产烧写工具下载到目标板。

因此，「环境搭建」的本质是让宿主机具备三样东西：编译工具链（把源码变成固件）、烧录工具（把固件灌进芯片）、辅助音频工具（把音频资源打包进固件）。本页依次说明这三部分的安装与使用。

Architecture

下图展示了从宿主机到目标板的完整开发工具链架构：

flowchart TD
    subgraph sg_Host["宿主机 (Host PC)"]
        OS["Windows / Linux / macOS"]
        OS -->|"安装"| TC["杰理编译工具链<br/>(pi32/bin/clang)"]
        OS -->|"安装"| FT["USB 升级工具 / 生产烧写工具"]
        OS -->|"可选"| AT["音频工具<br/>(打包/转换/MIDI)"]
    end

    subgraph sg_Build["构建入口 (sdk/)"]
        CB["Code::Blocks<br/>AD16N_mbox_flash.cbp"]
        MK["Makefile<br/>make_prompt.bat 环境"]
        VS["VS Code 任务<br/>Ctrl+Shift+B"]
        TC --> CB
        TC --> MK
        TC --> VS
        CB -->|"Build (Ctrl+F9)"| PB["post_build/ 固件产物"]
        MK -->|"make -j4"| PB
        VS -->|"编译任务"| PB
    end

    subgraph sg_Target["目标板 (Target Board)"]
        FT -->|"USB / UART"| DEV["AD16N 开发板<br/>(编程模式)"]
    end

    PB -->|"选择固件"| FT

架构说明：

杰理编译工具链是所有构建方式的公共底层依赖。三种构建入口（Code::Blocks、Makefile、VS Code）最终都调用工具链中的 clang 交叉编译器与链接器；
Code::Blocks（Windows 推荐）：通过 .cbp 工程文件图形化构建，适合交互式开发调试；
Makefile（Windows/Linux）：make_prompt.bat 预先配置好环境变量与 make 路径，命令行编译适合脚本化、CI 集成与批量构建；
VS Code：仓库预配置了构建任务，Ctrl+Shift+B 即可选择编译目标；
固件产物统一落在 post_build/ 目录，是烧录环节的输入；
烧录工具是宿主机与目标板之间的桥梁，负责把固件写入芯片（开发阶段用 USB 升级工具，量产用生产烧写工具）。

支持的操作系统与前置条件

SDK 官方对三种宿主操作系统的支持程度不同，编译方式也随之不同：

系统	推荐编译方式	说明
Windows	Code::Blocks IDE	官方推荐路径，开箱即用
Linux	Makefile 命令行	需要重写 `download_sh.c` 脚本适配 Linux 环境
macOS	自行配置	需自行配置交叉编译工具链

来源：README.md「三、环境搭建 / 3.1 前提条件」

设计意图：Windows 是 SDK 的主要开发平台，因此官方优先保证 Code::Blocks 集成体验；Linux 用户则利用 Makefile 实现无 IDE 的构建，但烧录脚本（download_sh.c）按 Windows 环境编写，需要自行适配。理解这一点有助于在跨平台开发时提前规划脚本修改工作。

安装编译工具链

获取方式

Windows / macOS：从杰理官方工具文档下载并安装「杰理编译工具链」：dev_env 工具文档
Linux：从 pkgman.jieliapp.com 下载，解压到 /opt/jieli 目录，并确保 /opt/jieli/pi32/bin/clang 存在。

来源：README.md「3.2 安装编译工具链」

工具链的核心是可执行文件 clang，它位于工具链安装目录的 pi32/bin/ 子目录下。SDK 的 Makefile 与 Code::Blocks 工程会通过该路径（或环境变量）找到编译器。Linux 下固定解压到 /opt/jieli 是因为 Makefile 中硬编码了默认工具链路径。

验证安装

安装完成后，在命令行执行版本检查以确认工具链可用：

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

来源：README.md「3.2 安装编译工具链」

若输出显示杰理定制版 clang（Pi32 目标）版本信息，则说明工具链安装成功且已加入 PATH；若提示 clang: command not found，请参见下文「常见编译错误」的排查方法。

安装烧录与音频工具

烧录工具

工具	用途	获取方式
USB 升级工具	开发阶段将固件烧录到目标板	购买链接 · 使用文档
生产烧写工具	量产/裸片烧写	通过代理商获取 · 一拖二烧写器使用说明

来源：README.md「3.3 安装烧录工具」

音频工具

打包、音频文件转换、MIDI 等通用音频工具从百度网盘下载（提取码 3jey），用于在编译前把音频资源（提示音、语音、MIDI 曲目）转换为 SDK 支持的格式并打包进固件。

来源：README.md「3.4 音频工具」

三种编译方式

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

确保已安装杰理编译工具链；
双击 AD16N_mbox_flash.cbp 工程文件打开 Code::Blocks；
点击 Build → Build（快捷键 Ctrl+F9）；
编译成功后，固件生成在 post_build/ 目录。

来源：README.md「7.2 Code::Blocks 编译」

.cbp 工程已内置工具链路径、芯片型号与链接脚本等全部构建参数，用户无需手工配置，这是 Windows 下最不容易出错的编译路径。

方式二：Makefile 命令行

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

# 编译
make -j4

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

来源：README.md「4.4 编译并烧录 / 方式二」

make_prompt.bat 是 Windows 下的编译环境入口脚本，它预先设置好 make 的路径与所有环境变量，解决了 Windows 原生命令行没有 make 命令的问题。Linux 用户无需该脚本，直接在 sdk/ 目录执行 make -j\nproc`即可，但需先适配download_sh.c` 烧录脚本。

编译命令速查表（均在 sdk/ 目录下执行）：

目标	命令
编译	`make -j4`
编译（显示详情）	`make VERBOSE=1 -j4`
清理	`make clean`

来源：README.md「7.1 编译命令速查表」

方式三：VS Code 编译

仓库已预配置 VS Code 任务，按 Ctrl+Shift+B 即可选择编译目标。该方式底层仍调用 Makefile 构建系统，适合偏好编辑器内闭环开发的工程师。

来源：README.md「4.4 编译并烧录 / 方式三」

Core Flow：从源码到固件的完整流程

下图展示「环境就绪 → 编译 → 固件产出 → 烧录」的端到端流程：

sequenceDiagram
    participant Dev as 开发者
    participant TC as 杰理工具链 (clang)
    participant Build as 构建系统 (Makefile/CBP)
    participant PB as post_build/ 固件
    participant FT as USB 升级工具
    participant Board as AD16N 开发板

    Dev->>TC: 安装并验证 clang --version
    TC-->>Dev: 版本信息确认可用
    Dev->>Build: 双击 .cbp 或执行 make -j4
    Build->>TC: 调用 pi32 交叉编译器
    TC-->>Build: 编译 + 链接预编译库 (.a)
    Build->>PB: 输出固件镜像
    Dev->>FT: 打开 USB 升级工具并选择固件
    Dev->>Board: 按住烧录键复位进入编程模式
    FT->>Board: USB/UART 下载固件
    Board-->>Dev: 烧录完成，复位运行

关键节点说明：

工具链验证是第一步：clang --version 确认交叉编译器可用，避免后续所有构建入口集体报错；
构建入口统一收敛到工具链：无论走 Code::Blocks、Makefile 还是 VS Code，编译动作最终都是调用同一个 clang 与链接器；
固件产物位置固定：post_build/ 是烧录工具选择固件时的标准目录；
目标板须进入编程模式：烧录前按住烧录按键复位/重新上电，这是烧录失败最常见的人为原因（详见 README.md 8.1 首次烧录）。

Usage Examples

示例 1：克隆仓库并进入 SDK 目录

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

来源：README.md「4.1 克隆仓库」

示例 2：Windows 命令行编译（含清理与详情输出）

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

# 编译
make -j4

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

来源：README.md「4.4 编译并烧录 / 方式二」

示例 3：Linux 命令行编译

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

来源：README.md「7.3 Makefile 编译」

设计意图说明：Linux 下使用 nproc 自动探测 CPU 核数做并行编译，与 Windows 手写 -j4 形成对比——-j 参数即并行任务数，数值越大编译越快，但过大会导致内存占用飙升，建议按「核数 + 1~2」取值。

配置选项

本主题涉及的环境与构建配置如下：

配置项	类型	默认值	说明
工具链安装目录（Linux）	路径	`/opt/jieli`	解压后须存在 `/opt/jieli/pi32/bin/clang`
工具链可执行文件	路径	`pi32/bin/clang`	SDK 构建时调用的交叉编译器
`PATH` 环境变量	环境变量	—	需包含工具链 `bin` 目录，否则 `clang: command not found`
`-j` 并行编译数	make 参数	用户指定	如 `-j4`；Linux 可用 `nproc` 自动探测
`VERBOSE`	make 参数	关闭	`make VERBOSE=1` 输出完整编译命令，便于排查
`make clean`	make 目标	—	清理中间产物后重新全量编译
`app_config.h`	配置文件	随 SDK 发布	位于 `sdk/apps/app/src/mbox_flash/`，配置应用功能开关与芯片型号

配置参考：README.md 九、配置说明与 README.md 10.1 开发流程相关

失败模式、边界情况与排查

官方在 README 中直接给出了四类最常见的编译错误及其解决办法：

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

来源：README.md「7.4 常见编译错误」与 README.md 10.2 编译相关

其他边界情况：

Linux 平台适配：Linux 下编译需要重写 download_sh.c 烧录脚本，否则烧录环节不可用——这是官方明确标注的已知限制（README.md L91）；
macOS 无官方开箱支持：需自行配置交叉编译工具链（README.md L92）；
烧录前置条件：编译成功 ≠ 烧录成功，目标板必须进入编程模式（按住烧录键复位/重新上电），且 USB 升级工具正确连接（README.md L166）；
清理后重建：修改芯片型号或 Flash 配置后，建议先 make clean 再全量编译，避免旧中间产物干扰链接。

性能与运维提示

并行编译：优先使用 make -j4（或 -j\nproc`）缩短构建时间；编译大工程时注意内存上限，避免 -j` 过大导致 OOM；
详细日志：排查链接错误时用 make VERBOSE=1 查看完整编译/链接命令行，可快速定位缺失库或参数错误；
构建环境隔离：Windows 下始终通过 make_prompt.bat 进入编译环境，保证 make 与工具链路径一致性，避免系统 PATH 被污染；
产物目录：定期检查 post_build/ 输出，确认固件时间戳与源码版本对应，防止烧录旧固件。

SDK 概述与芯片支持（README.md）
英文版 README（README-en.md）
芯片选型说明（doc/README.md）
杰理工具在线文档：doc.zh-jieli.com/Tools
杰理编译工具链下载：dev_env 工具文档
USB 升级工具文档：forced_upgrade
生产烧写工具文档：一拖二烧写器 · 一拖八烧写器
ISD 配置说明（烧录配置文件）：ini_cfg.html
问题反馈：Gitee Issues