开发环境搭建与工具链

本文档介绍 fw-AD23N_GP-MCU_SDK 的开发环境搭建方法、交叉编译工具链配置、构建系统（Makefile / Code::Blocks / VS Code）、固件烧录工具以及常见环境问题排查，帮助开发者在 Windows、Linux、macOS 上完成从源码到固件烧录的完整开发链路。

Purpose and Scope

本页覆盖以下内容：

支持的主机平台与前提条件（Windows / Linux / macOS）
杰理 PI32V2 交叉编译工具链的下载、安装与验证
SDK 构建系统的三种入口：顶层 Makefile、Code::Blocks 工程（.cbp）、VS Code 任务
工具链在 sdk/Makefile 中的实际路径与编译参数配置
固件烧录工具（USB 升级工具 / 生产烧写工具）与首次烧录流程
常见编译错误与开发环境问题排查

不在此页范围、请查阅对应页面的内容：SDK 整体工程结构（见「工程结构与目录」页面）、应用层功能配置（见「mbox_flash 应用」页面）、音频格式与解码器 API（见「解码器」页面）、OTA 升级与生产烧写细节（见「烧录与升级」页面）。

fw-AD23N_GP-MCU_SDK 是杰理科技为 AD23N 系列芯片（AD232A / AD232S / AD235A / AD236A / AD236B / AD238A / AD238B）提供的通用 MCU SDK，覆盖语音玩具、小音箱、通用 MCU 三大应用场景。SDK 发布包内含源码与示例工程，但必须配合对应命名规则的预编译库（lib.a）才能完成链接，因此工具链版本的匹配是环境搭建的关键前提。

整个开发环境由四层组成：

主机平台：Windows（推荐，Code::Blocks IDE）、Linux（Makefile 命令行）、macOS（需自行配置交叉工具链）。
交叉编译工具链：杰理 PI32V2 工具链，基于 LLVM/clang，目标架构 pi32v2、CPU 核 r3v2，支持 LTO 链接优化。Windows 下默认安装于 C:/JL/pi32，Linux 下解压于 /opt/jieli。
构建系统：顶层 Makefile（跨平台条件分支）+ Code::Blocks 工程 AD23N_mbox_flash.cbp + VS Code 预配置任务，三者共享同一套工具链路径与编译参数。
烧录工具：USB 升级工具（开发调试）、生产烧写工具（量产裸片烧写），配合目标板编程模式完成固件下载。

SDK 采用「一个统一编译入口、多芯片全系列支持」的设计：Makefile 通过 -DCPU_SH59=1 等宏定义区分芯片平台与功能开关，开发者无需为每颗芯片维护独立工程。

Architecture

flowchart TD
    subgraph sg_Host["主机平台 (Host)"]
        Win["Windows<br/>Code::Blocks / make_prompt.bat"]
        Linux["Linux<br/>Makefile 命令行"]
        Mac["macOS<br/>自配交叉工具链"]
    end

    subgraph sg_Toolchain["杰理 PI32V2 交叉工具链"]
        Clang["clang (pi32v2)<br/>-target pi32v2 -mcpu=r3v2"]
        Ld["lto-wrapper<br/>链接器 (LTO)"]
        Ar["llvm-ar / lto-ar<br/>静态库打包"]
        SysLib["系统库 r3<br/>SYS_LIB_DIR"]
    end

    subgraph sg_Build["构建系统"]
        Mk["sdk/Makefile<br/>跨平台条件分支"]
        Cbp["AD23N_mbox_flash.cbp<br/>Code::Blocks 工程"]
        Vsc["VS Code 任务<br/>Ctrl+Shift+B"]
        Post["后处理脚本<br/>download.bat / download.sh"]
    end

    subgraph sg_Output["产物与烧录"]
        Elf["sdk.elf 固件<br/>app/post_build/sh59/"]
        UsbTool["USB 升级工具"]
        ProdTool["生产烧写工具<br/>一拖二 / 一拖八"]
        Board["AD23N 目标板"]
    end

    Win --> Clang
    Linux --> Clang
    Mac --> Clang
    Win --> Mk
    Linux --> Mk
    Cbp --> Mk
    Vsc --> Mk
    Mk --> Clang
    Mk --> Ld
    Mk --> Ar
    Clang --> SysLib
    Ld --> Elf
    Elf --> Post
    Post --> UsbTool
    UsbTool --> Board
    ProdTool --> Board

架构说明：三个主机平台通过不同的入口（IDE / 命令行 / 编辑器任务）最终都汇聚到 sdk/Makefile 定义的统一构建流程；Makefile 按操作系统条件分支选择工具链路径与后处理脚本（Windows 使用 download.bat 并借助 fixbat.exe 处理 UTF-8→GBK 编码问题，Linux 使用 download.sh 且需要 -D__SHELL__ 宏保证 download.c 正确编译）；链接产物 sdk.elf 经后处理生成固件，再由 USB 升级工具或生产烧写工具写入目标板。

前提条件与平台支持

SDK 对不同主机平台的支持方式与成熟度不同，README 中的说明如下：

系统	说明
Windows	推荐使用 Code::Blocks IDE 编译；也可通过 `sdk/make_prompt.bat` 进入预配置的命令行环境
Linux	Makefile 命令行编译，需要重写 `download_bat.c` 脚本以适配 Linux 环境（README 7.3 节同时指出需修改该脚本）
macOS	需自行配置交叉编译工具链，SDK 不提供现成脚本

设计意图：SDK 以 Windows 为第一等开发平台（工具链安装包、Code::Blocks 工程、fixbat.exe 编码修复脚本均围绕 Windows 提供），Linux 为受支持的备选平台（工具链可通过 pkgman 包管理器获取），macOS 则需要开发者自行解决工具链与脚本兼容问题。

安装编译工具链

获取工具链

从杰理文档中心下载并安装杰理编译工具链：https://doc.zh-jieli.com/Tools/zh-cn/dev_tools/dev_env/index.html
Linux 用户可从包管理器站点下载：http://pkgman.jieliapp.com/doc/all
- 下载后解压到 /opt/jieli 目录
- 确保工具链 clang 可执行文件存在（README 要求 /opt/jieli/pi32/bin/clang；顶层 Makefile 的 Linux 分支实际使用 /opt/jieli/pi32v2/bin/clang，注意目录层次）
安装完成后验证：

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

工具链在 Makefile 中的实际路径

sdk/Makefile 顶部通过 OS 环境变量做平台分支，这是环境搭建的核心依据：

# 工具路径设置
ifeq ($(OS), Windows_NT)
# Windows 下工具链位置
TOOL_DIR := C:/JL/pi32/bin
CC    := clang.exe
CXX   := clang.exe
LD    := pi32v2-lto-wrapper.exe
AR    := llvm-ar.exe
MKDIR := mkdir_win -p
RM    := rm -rf

SYS_LIB_DIR := C:/JL/pi32/pi32v2-lib/r3
SYS_INC_DIR := C:/JL/pi32/pi32v2-include
EXT_CFLAGS  := # Windows 下不需要 -D__SHELL__
export PATH:=$(TOOL_DIR);$(PATH)

## 后处理脚本
FIXBAT          := tools/utils/fixbat.exe # 用于处理 utf8->gbk 编码问题
POST_SCRIPT     := app/post_build/sh59/download.bat
RUN_POST_SCRIPT := app\\post_build\\sh59\\download.bat
else
# Linux 下工具链位置
TOOL_DIR := /opt/jieli/pi32v2/bin
CC    := clang
CXX   := clang
LD    := lto-wrapper
AR    := lto-ar
MKDIR := mkdir -p
RM    := rm -rf
export OBJDUMP := $(TOOL_DIR)/objdump
export OBJCOPY := $(TOOL_DIR)/objcopy
export OBJSIZEDUMP := $(TOOL_DIR)/objsizedump

SYS_LIB_DIR := $(TOOL_DIR)/../lib/r3
SYS_INC_DIR := $(TOOL_DIR)/../include
EXT_CFLAGS  := -D__SHELL__ # Linux 下需要这个保证正确处理 download.c
export PATH:=$(TOOL_DIR):$(PATH)

## 后处理脚本
FIXBAT          := touch # Linux下不需要处理 bat 编码问题
POST_SCRIPT     := app/post_build/sh59/download.sh
RUN_POST_SCRIPT := bash $(POST_SCRIPT)
endif

Source: sdk/Makefile

关键点解读：

Windows 工具链默认安装在 C:/JL/pi32，其中 bin/ 存放编译器，pi32v2-lib/r3 存放系统运行库（SYS_LIB_DIR），pi32v2-include 存放系统头文件（SYS_INC_DIR）。链接器是 pi32v2-lto-wrapper.exe（LTO 包装器），归档器是 llvm-ar.exe。
Linux 工具链位于 /opt/jieli/pi32v2/bin，编译器名称为 clang（无 .exe 后缀），链接器为 lto-wrapper，归档器为 lto-ar；同时导出 OBJDUMP、OBJCOPY、OBJSIZEDUMP 供后处理脚本使用。
EXT_CFLAGS 的平台差异：Linux 下必须追加 -D__SHELL__，否则 download.c（后处理下载脚本的宿主程序）无法正确编译；Windows 下不需要。
PATH 注入：Makefile 通过 export PATH:=$(TOOL_DIR);$(PATH)（Windows）或 export PATH:=$(TOOL_DIR):$(PATH)（Linux）将工具链目录注入当前环境，因此即使系统未全局配置 PATH 也能编译——这也是 make_prompt.bat 与 Code::Blocks 都能直接工作的原因。
编码处理：Windows 后处理脚本是 .bat，存在 UTF-8→GBK 编码问题，因此用 tools/utils/fixbat.exe 修复；Linux 下直接以 touch 占位、无需处理。

Linux 额外注意

Makefile 头部注释明确给出了 Linux 环境的三个要点（README 未覆盖的细节）：

# 注意： Linux 下编译方式：
#     1. 从 http://pkgman.jieliapp.com/doc/all 处找到下载链接
#     2. 下载后，解压到 /opt/jieli 目录下，保证
#       /opt/jieli/common/bin/clang 存在（注意目录层次）
#     3. 确认 ulimit -n 的结果足够大（建议大于8096），否则链接可能会因为打开文件太多而失败
#       可以通过 ulimit -n 8096 来设置一个较大的值

Source: sdk/Makefile

即：工具链解压到 /opt/jieli 后需保证 clang 实际可执行（README 与 Makefile 注释给出的路径略有差异，实际以解压后的目录层次为准）；ulimit -n（文件描述符上限）建议大于 8096，否则 LTO 链接阶段会因打开文件过多而失败——这是 Linux 下最典型的环境坑之一。

构建系统详解

SDK 提供三种等价的构建入口，全部汇聚到顶层 sdk/Makefile。

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

双击打开 sdk/AD23N_mbox_flash.cbp 工程文件
点击 Build → Build（Ctrl+F9）
编译成功后在 app/post_build/sh59/ 目录下生成固件

.cbp 工程与 Makefile 共享同一套工具链（C:/JL/pi32/bin）与宏定义，因此只要工具链安装正确，Code::Blocks 即可直接构建。

方式二：Makefile 命令行

# Windows 用户：双击 sdk/make_prompt.bat 打开预配置命令行环境
# （该脚本已设置好所有环境变量和 make 的路径）

# 编译
make -j4

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

# 清理
make clean

# Linux 用户
cd sdk
make -j`nproc`

Source: README.md（命令摘要，另见 README.md）

方式三：VS Code 编译

仓库已预配置 VS Code 任务，按 Ctrl+Shift+B 即可选择编译目标，适合习惯编辑器工作流的开发者。

编译参数与目标架构

Makefile 中 CFLAGS 定义了目标架构与优化策略：

# 编译参数设置
CFLAGS := \
	-target pi32v2 \
	-mcpu=r3v2 \
	-integrated-as \
	-flto \
	-Wuninitialized \
	-Wno-invalid-noreturn \
	-fno-common \
	-integrated-as \
	-Oz \
	-g \
	-flto \
	-fallow-pointer-null \
	-fprefer-gnu-section \
	-Wno-shift-negative-value \
	-Wundef \

Source: sdk/Makefile

参数	含义
`-target pi32v2`	目标三态为杰理 PI32V2 架构（LLVM 交叉编译核心参数）
`-mcpu=r3v2`	CPU 核型号 r3v2，对应 AD23N 系列芯片
`-integrated-as`	使用 clang 内置汇编器，无需单独汇编器
`-flto`	启用链接时优化（LTO），配合 `lto-wrapper` 链接器，是性能与代码体积优化的关键
`-Oz`	优化目标为最小化代码体积（嵌入式固件 Flash 空间敏感）
`-g`	生成调试信息，便于串口日志与仿真器调试
`-fno-common`	禁止未初始化全局变量合并到 common 段
`-fprefer-gnu-section`	优先生成 GNU section 布局，配合链接脚本裁剪未用代码

功能宏定义（DEFINES）

Makefile 通过大量 -D 宏控制功能裁剪，直接影响链接的库与代码路径：

# 宏定义
DEFINES := \
	-DFPGA=0 \
	-DCPU_SH59=1 \
	-DAUDIO_ADC_EN=1 \
	-DROM_SECURE_BOOT \
	-DSPEAKER_EN \
	-DHAS_VOICE_PITCH_EN \
	-DHAS_VOICE_CHANGER_EN \
	-DHAS_PCM_EQ_FLOAT_EN \
	-DAUX_EN \
	-DENCODER_EN \
	-DHAS_UMP3_DECODER \
	-DHAS_MP3_ST_DECODER \
	-DHAS_WAV_DECODER \
	-DHAS_F1A_DECODER \
	-DHAS_MAX_F1A_NUMBER=2 \
	-DHAS_MIDI_DECODER \
	-DHAS_MIDI_KEYBOARD_DECODER \
	-DHAS_A_DECODER \
	-DHAS_ANS_EN \
	-DHAS_SPEED_EN \
	-DHAS_EXT_FLASH_EN \
	-DHAS_USB_EN=0 \
	-DHAS_SDMMC_EN \
	-DHAS_HW_SRC_MODULE=1 \
	-DHAS_UPDATE_EN=1 \
	-DHAS_ECHO_EN \
	-DHOWLING_EN \
	-DHAS_NORFS_EN \

Source: sdk/Makefile

其中 -DCPU_SH59=1 标识 AD23N 的芯片平台代号（SH59），-DROM_SECURE_BOOT 开启安全启动，-DHAS_UPDATE_EN=1 开启 OTA 升级，各 -DHAS_*_DECODER 宏决定启用哪些音频解码器（UMP3 / MP3 / WAV / F1A / MIDI / A 格式等），-DHAS_USB_EN=0 则关闭 USB 外设以减少资源占用。修改这些宏可以裁剪固件功能，但需与 include_lib/liba/ 中预编译库的命名规则（liba 库与宏的对应关系）保持一致。

编译产物

ELF 输出：app/post_build/sh59/sdk.elf
目标文件清单：sdk.elf.objs.txt（OBJ_FILE）
中间目录：objs/（BUILD_DIR）
最终固件：编译后由后处理脚本在 app/post_build/sh59/ 下生成，供烧录工具使用

烧录与升级工具

工具	用途	获取方式
USB 升级工具	将固件烧录到目标板（开发调试）	申请链接 · 使用文档
生产烧写工具	量产 / 裸片烧写（一拖二 / 一拖八）	代理商处 · 一拖二使用文档 · 一拖八使用文档
音频工具	音频打包、格式转换、MIDI 等	百度网盘（提取码 `3jey`），详见 README 3.4 节

此外，ISD_CONFIG.INI 是烧录配置的核心文件，其配置项说明见杰理文档中心的 ISD 配置说明。

首次烧录流程

flowchart TD
    Start([开始]) --> Connect["连接硬件<br/>开发板通过 USB / USB 升级工具连到 PC"]
    Connect --> Mode{"进入编程模式"}
    Mode -->|"方式一"| Btn["按住烧录按键<br/>复位或重新上电"]
    Mode -->|"方式二"| Tool["USB 升级工具<br/>进入编程模式"]
    Btn --> Open["启动 USB 升级工具上位机"]
    Tool --> Open
    Open --> Select["选择编译生成的固件文件"]
    Select --> Flash["点击下载按钮<br/>等待烧录完成"]
    Flash --> Verify["校验成功"]
    Verify --> End([完成])

Source: README.md

提示：编译前请确保 USB 升级工具正确连接且目标板已进入编程模式；SDK 同时支持双备份固件 OTA 升级（见 README.md）。

快速开始：从克隆到固件

sequenceDiagram
    participant Dev as 开发者
    participant Git as Gitee 仓库
    participant Mk as sdk/Makefile
    participant Tool as PI32V2 工具链
    participant Post as 后处理脚本
    participant Burn as USB 升级工具

    Dev->>Git: git clone https://gitee.com/Jieli-Tech/AD23N.git
    Dev->>Mk: cd sdk && make -j4
    activate Mk
    Mk->>Tool: clang -target pi32v2 -flto -Oz 编译源码
    Tool-->>Mk: 目标文件 (objs/)
    Mk->>Tool: lto-wrapper 链接 (SYS_LIB_DIR r3)
    Tool-->>Mk: app/post_build/sh59/sdk.elf
    Mk->>Post: download.bat / download.sh 后处理
    Post-->>Dev: 固件文件
    deactivate Mk
    Dev->>Burn: 选择固件并烧录
    Burn-->>Dev: 烧录完成

各步骤要点：

克隆：git clone https://gitee.com/Jieli-Tech/AD23N.git，然后进入 sdk/ 目录（README 4.1 节）。
工程入口：SDK 根目录的 AD23N_mbox_flash.cbp 对应小音箱 / 语音玩具 / MIDI 琴应用，应用代码位于 sdk/app/src/mbox_flash/。
编译：Windows 双击 make_prompt.bat 后执行 make -j4；并行任务数越大编译越快（-j 参数）。
产物：固件在 app/post_build/sh59/ 下生成。
烧录：用 USB 升级工具选择固件，目标板进入编程模式后下载。

常见错误与排查

编译错误速查表

错误提示	解决方法
`clang: command not found`	未安装杰理编译工具链，或环境变量未配置；确认 `C:/JL/pi32/bin`（Windows）或 `/opt/jieli/pi32v2/bin`（Linux）存在且 Makefile 能找到
`cannot find -lxxx`	缺少对应的 `.a` 库文件，检查 `include_lib/liba/` 目录是否完整、命名规则是否与当前宏配置匹配
`make: command not found`	Windows 下使用 `sdk/make_prompt.bat` 打开编译命令环境（该脚本已设置 `make` 路径与环境变量）
链接错误	检查 Makefile target 是否匹配当前芯片型号；Linux 下检查 `ulimit -n` 是否大于 8096

Source: README.md

环境与调试 FAQ

Q: 如何创建一个新的工程？ A: 基于现有的 .cbp 工程和 app/src/ 中的应用代码进行修改，配置对应用例即可。
Q: 如何切换不同的芯片型号？ A: 在配置中选择对应的芯片型号；SDK 已为全系列预配置了统一的编译入口（Makefile 中通过 CPU_SH59 等宏区分平台）。
Q: Windows 下编译报错 make 不是有效命令？ A: 使用 sdk/make_prompt.bat 进入预配置命令行环境。
Q: 如何加快编译速度？ A: 使用 -j 参数并行编译，如 make -j4。
调试技巧：可通过 UART 输出串口调试日志；利用空闲 GPIO 输出调试波形测量时序。

Source: README.md

配置与扩展点

应用功能开关：编辑 sdk/app/src/mbox_flash/app_config.h 配置目标应用的功能开关（见 README「九、配置说明」）。
功能宏裁剪：修改 sdk/Makefile 中的 DEFINES（如 HAS_*_DECODER、HAS_USB_EN）可裁剪固件功能，需与 include_lib/liba/ 预编译库的命名规则匹配。
平台适配：Linux 用户需重写 download_bat.c 脚本适配 Linux 环境；macOS 需自行配置交叉编译工具链。

性能与运维提示

并行编译：make -jN 的 N 建议取 CPU 核心数（Linux 可用 make -j$(nproc)），可显著缩短构建时间。
LTO 链接资源：-flto 链接阶段文件描述符占用高，Linux 下 ulimit -n 建议大于 8096，否则链接失败。
版本一致性：SDK Release 代码必须配合对应命名规则的 lib.a 库编译；升级 SDK 版本时请同步核对工具链与库版本（版本历史见 AD23N_SDK_发布版本信息.pdf）。
安全启动：默认开启 ROM_SECURE_BOOT，量产固件需走生产烧写工具流程。

在线文档中心（AD23）
杰理编译工具链下载与安装
USB 升级工具使用文档
ISD_CONFIG.INI 配置说明
sdk/Makefile（工具链与编译参数）
README.md（环境搭建章节）
SDK 手册：doc/AD23N_SDK手册_v1.0.pdf · 芯片用户手册：doc/AD23N用户手册V1.1.pdf