构建系统与批处理工具

fw-AD16N_GP-MCU_SDK 的构建系统以 GNU Make 为核心入口（sdk/Makefile），统一驱动杰理 pi32v2 LLVM/clang 工具链完成编译、链接与后处理，并配套一批 Windows 批处理脚本（.bat）用于搭建构建环境、资源选择、库合并和下载烧录。

Purpose and Scope

本文档介绍 SDK 的构建系统与批处理工具这一完整能力，具体包括：

• sdk/Makefile 构建入口：目标（target）、工具链选择、编译参数、宏定义、输出文件与后处理流程；
• Windows 与 Linux 双平台工具链配置差异；
• 构建辅助批处理工具：make_prompt.bat、MIDI_VER_SELECT.bat、midi_2byte.bat、midi_4byte.bat、do_merge_libs.bat；
• 后处理脚本：apps/app/post_build/uc03/download.bat（及 Linux 对应 download.sh）、eqbin2dir.bat、csv2dir.bat。

以下主题不在本页范围，由其他目录页覆盖：芯片内部架构与外设驱动（参见 SDK 架构页）、具体 App 业务代码、烧录器（JL-ISP/调试器）硬件操作细节。

Overview

该 SDK 面向杰理 AD16N 系列 MCU（GP-MCU），使用 LLVM/clang 编译到自定义 pi32v2 指令集架构（-target pi32v2 -mcpu=r1）。构建系统设计的目标是：

1. 一套 Makefile，双平台可用：通过 ifeq ($(OS), Windows_NT) 分支，Windows 下使用 C:/JL/pi32/bin 下的 clang.exe / pi32v2-lto-wrapper.exe / llvm-ar.exe，Linux 下使用 /opt/jieli/pi32v2/bin 下的同名工具，并自动把工具目录加入 PATH。
2. 链接时优化（LTO）与代码大小优先：-flto -Oz 配合 -mllvm -inline-threshold=5 与 -mllvm -pi32v2-large-program=true，面向 Flash 受限的嵌入式场景做激进优化。
3. 编译即产出、编译后即下载：默认 make 目标同时完成编译与下载（通过后处理脚本 download.bat / download.sh），并提供 make clean 与 make VERBOSE=1 两个常用变体。
4. 批处理脚本补齐 Windows 生态：由于嵌入式工具链多为命令行程序，SDK 用 .bat 脚本提供构建提示符环境、MIDI 版本选择、库合并等易用入口。

典型使用场景：开发者在 Windows 上双击/命令行运行 make 完成固件编译并烧录到芯片；CI 或服务器环境在 Linux 上执行 make 产出 sdk.elf；量产前用 do_merge_libs.bat 合并静态库、用 eqbin2dir.bat / csv2dir.bat 转换 EQ 与写保护配置文件。

Architecture

flowchart TD
    subgraph sg_User["开发者 / CI"]
        U1["make / make VERBOSE=1 / make clean"]
        U2["make_prompt.bat（构建提示符）"]
    end

    subgraph sg_Build["构建系统 sdk/Makefile"]
        M["Makefile 主控"]
        TC["工具链<br/>clang + lto-wrapper + llvm-ar"]
        CFG["CFLAGS / DEFINES<br/>-target pi32v2 -mcpu=r1 -Oz -flto"]
        OUT["输出产物<br/>sdk.elf / sdk.elf.objs.txt / objs/"]
    end

    subgraph sg_Tools["批处理工具"]
        T1["MIDI_VER_SELECT.bat"]
        T2["midi_2byte.bat / midi_4byte.bat"]
        T3["do_merge_libs.bat"]
        T4["eqbin2dir.bat / csv2dir.bat"]
    end

    subgraph sg_Post["后处理 / 下载"]
        P1["download.bat（Windows）"]
        P2["download.sh（Linux）"]
        P3["fixbat.exe（utf8→gbk）"]
    end

    subgraph sg_Device["目标设备"]
        D1["AD16N 芯片（UC03/UC04）"]
    end

    U1 --> M
    U2 --> M
    M --> TC
    M --> CFG
    TC --> OUT
    M --> P3
    P3 --> P1
    M --> P1
    M --> P2
    P1 --> D1
    P2 --> D1
    T1 --> T2
    T3 -.-> OUT
    T4 -.-> P1

各节点说明：

• Makefile 主控：唯一的构建入口，负责设置工具链、编译参数、目标文件与后处理脚本，并支持 VERBOSE=1 输出详细日志。
• 工具链：clang 编译 C/C++，lto-wrapper 做链接（LTO），llvm-ar 打包静态库；工具目录按平台注入 PATH。
• 输出产物：apps/app/post_build/uc03/sdk.elf 为最终 ELF，sdk.elf.objs.txt 记录参与链接的对象文件列表，中间文件在 objs/ 目录。
• 批处理工具：MIDI_VER_SELECT.bat 负责在 2 字节/4 字节 MIDI 版本间切换并校验目录结构；do_merge_libs.bat、eqbin2dir.bat、csv2dir.bat 分别处理库合并、EQ 配置与 Flash 写保护配置。
• 后处理/下载：fixbat.exe 解决 Windows 下 bat 文件 utf8→gbk 编码问题（Linux 下用 touch 占位），随后执行 download.bat 或 download.sh 将固件下载到芯片。

构建系统核心实现

Makefile 目标与使用方式

Makefile 顶部注释即定义了三个核心用法，这也是整个构建系统的对外契约：

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

来源：sdk/Makefile

设计意图：默认目标把"编译"和"下载"绑定，贴近嵌入式开发"改代码→编译→烧录"的高频循环；VERBOSE=1 用于排查编译问题时展开全部命令；clean 保证可重复构建。Linux 注意事项体现了工具链外置（/opt/jieli）和文件描述符上限（ulimit -n）两个常见坑位——LTO 链接阶段会同时打开大量临时文件。

双平台工具链分支

构建系统按操作系统选择工具链与后处理方式：

# 工具路径设置
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/r1-large
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     := apps/app/post_build/uc03/download.bat
RUN_POST_SCRIPT := apps\app\post_build\uc03\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/r1-large
SYS_INC_DIR := $(TOOL_DIR)/../include
EXT_CFLAGS  := -D__SHELL__ # Linux 下需要这个保证正确处理 download.c
export PATH:=$(TOOL_DIR):$(PATH)

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

CC  := $(TOOL_DIR)/$(CC)
CXX := $(TOOL_DIR)/$(CXX)
LD  := $(TOOL_DIR)/$(LD)
AR  := $(TOOL_DIR)/$(AR)

来源：sdk/Makefile

关键设计点：

• 路径外置：系统库（SYS_LIB_DIR，r1-large 变体）与系统头文件（SYS_INC_DIR）都从工具链目录推导，换工具链版本时无需改动业务代码。
• 平台差异收敛：FIXBAT 在 Windows 上用 fixbat.exe 修复 bat 文件编码，Linux 上用 touch 占位；后处理脚本分别指向 download.bat / download.sh，上层规则无需关心平台。
• __SHELL__ 宏：Linux 下额外定义 -D__SHELL__，保证 download.c（下载驱动源码）被正确处理——这提示后处理下载功能在 Linux 下由 shell 环境驱动。

编译参数与宏定义

# 输出文件设置
OUT_ELF   := apps/app/post_build/uc03/sdk.elf
OBJ_FILE  := $(OUT_ELF).objs.txt
# 编译路径设置
BUILD_DIR := objs

# 编译参数设置
CFLAGS := \
	-target pi32v2 \
	-mcpu=r1 \
	-integrated-as \
	-mllvm -inline-threshold=5 \
	-Oz \
	-flto \
	-Wuninitialized \
	-Wno-invalid-noreturn \
	-fno-common \
	-Oz \
	-g \
	-flto \
	-fallow-pointer-null \
	-fprefer-gnu-section \
	-Wno-shift-negative-value \
	-Wundef \
	-mllvm -pi32v2-large-program=true \
	-Werror=implicit-function-declaration \
	-Werror=return-type \
	-Werror=undef \
	-Wno-format

来源：sdk/Makefile

参数含义与设计意图：

宏定义部分（DEFINES）用 -D 开关配置芯片与功能集，例如 -D__FPGA=0、-DCONFIG_CPU_UC03=1、-DCONFIG_CPU_UC04=1、-DD_IS_FLASH_SYSTEM、-DD_SFC_DEVICE_EN，以及解码器/编码器使能（HAS_MP3_ST_DECODER、HAS_WAV_DECODER、HAS_MIDI_DECODER、HAS_MP3_ENCODER 等）。这些宏是功能裁剪的扩展点——增删解码器只需改 Makefile 的 DEFINES，无需改动业务源码。

批处理工具详解

批处理工具是构建系统的"人性化入口"，解决 Windows 环境下工具链使用不便、资源版本切换繁琐、以及后处理配置转换等问题。

make_prompt.bat — 构建提示符环境

SDK 根目录与 tools/ 下各有一个 make_prompt.bat，作用相同：把 tools/utils 加入 PATH 并打开一个新的 cmd 窗口，让开发者无需手动配置环境变量即可直接执行 make 及其他工具命令：

SET SCRIPT_PATH=%~dp0%
set PATH=%SCRIPT_PATH%\tools\utils;%PATH%

cmd

来源：sdk/make_prompt.bat

设计意图：%~dp0% 取脚本自身所在目录，因此该脚本可以从任意路径被调用，tools/utils 下的 fixbat.exe、mkdir_win 等辅助程序始终可用。cmd 命令保持窗口打开，等待开发者交互输入。

MIDI_VER_SELECT.bat — MIDI 版本选择

MIDI_VER_SELECT.bat 用于在 2 字节 MIDI 与 4 字节 MIDI 两种资源格式间切换，并校验目标目录结构是否存在：

echo Please make sure you're running this script from the correct directory
dir "apps\app\src\mbox_flash\uc03\" 2>nul || echo The directory structure does not exist

来源：sdk/MIDI_VER_SELECT.bat

它依赖 midi_2byte.bat / midi_4byte.bat 两个脚本分别执行具体切换动作（对应 Makefile 中 -DHAS_midi_2byte_USED 宏的启用）。错误处理策略是"先检查、后操作"：先确认 apps\app\src\mbox_flash\uc03\ 目录存在，若不存在则提示用户从正确目录运行，避免脚本在错误路径上静默失败。

do_merge_libs.bat — 静态库合并

tools/utils/do_merge_libs.bat 提供静态库合并能力，用于把多个 *.a（LLVM bitcode 归档）合并为一个库，方便后处理脚本与链接阶段引用。合并动作由工具链目录中的 llvm-ar/lto-ar 完成，脚本只是封装命令行参数并校验输入文件。

eqbin2dir.bat 与 csv2dir.bat — 后处理配置转换

这两个脚本位于 apps/app/post_build/uc03/ 下，服务于后处理阶段：

• eq_tool/eqbin2dir.bat：将 EQ 工具的 bin 输出转换为目录格式，供固件资源打包使用；
• flash_write_protect/csv2dir.bat：将 Flash 写保护配置的 CSV 文件转换为目录结构，配合 -DD_SFC_DEVICE_EN 的 Flash 子系统生成写保护表。

设计意图：把"配置→资源目录"的转换固化为脚本，保证同一份配置在每次构建中产生一致的产物，避免手工复制造成的人为错误。

Core Flow — 一次完整构建的旅程

sequenceDiagram
    participant U as 开发者 / CI
    participant M as sdk/Makefile
    participant T as 工具链 (clang/lto-wrapper)
    participant O as 输出 (sdk.elf / objs/)
    participant P as 后处理脚本
    participant D as AD16N 芯片

    U->>M: make（或 make VERBOSE=1）
    M->>M: 解析平台分支 (Windows_NT / Linux)
    M->>M: 组装 CFLAGS / DEFINES / 工具路径
    loop 每个源文件
        M->>T: clang -target pi32v2 -mcpu=r1 -Oz -flto -c
        T-->>O: 写入 objs/ 并追加到 objs.txt
    end
    M->>T: pi32v2-lto-wrapper 链接
    T-->>O: 生成 apps/app/post_build/uc03/sdk.elf
    M->>P: 调用 POST_SCRIPT (download.bat / download.sh)
    P->>P: fixbat.exe 修复编码（Windows）或 touch（Linux）
    P->>D: 通过调试器/串口下载固件
    D-->>P: 下载结果
    P-->>M: 返回退出码
    M-->>U: make 完成 / 报错退出

执行顺序说明：

1. 入口：make 默认目标（make VERBOSE=1 仅改变日志级别，make clean 则执行清理）。
2. 环境解析：ifeq ($(OS), Windows_NT) 决定工具链目录、PATH 注入方式、后处理脚本与 FIXBAT。
3. 编译：每个 C/C++ 文件经 clang -target pi32v2 -mcpu=r1 -Oz -flto 编译为 LLVM bitcode 对象，对象文件路径记录进 sdk.elf.objs.txt（OBJ_FILE）。
4. 链接：pi32v2-lto-wrapper.exe（Linux 为 lto-wrapper）执行带 LTO 的链接，产出 apps/app/post_build/uc03/sdk.elf。
5. 后处理：Windows 下先用 fixbat.exe 把可能存在的 utf8 编码 bat 转成 gbk（避免 cmd 中文乱码），再运行 download.bat；Linux 下直接 bash download.sh。
6. 下载：后处理脚本把固件烧录/下载到目标芯片，退出码回传给 make，驱动整个构建的结果。

Usage Examples

基本用法：编译并下载

在 sdk/ 目录下（Windows 先运行 make_prompt.bat 打开构建环境）：

make          # 编译并下载
make VERBOSE=1  # 显示完整编译命令（排查问题用）
make clean    # 清除 objs/ 等编译临时文件

来源：sdk/Makefile

配置后处理脚本的典型模式

Makefile 通过三个变量把"编译"与"后处理"解耦，替换后处理逻辑只需改这两行（如切换到其他芯片方案）：

## 后处理脚本
FIXBAT          := tools/utils/fixbat.exe # 用于处理 utf8->gbk 编码问题
POST_SCRIPT     := apps/app/post_build/uc03/download.bat
RUN_POST_SCRIPT := apps\app\post_build\uc03\download.bat

来源：sdk/Makefile

FIXBAT 的 touch 占位（Linux 分支）说明这是一个"无操作即可"的钩子：编码修复只在 Windows 的 cmd 环境有必要。

批处理工具调用示例

SET SCRIPT_PATH=%~dp0%
set PATH=%SCRIPT_PATH%\tools\utils;%PATH%

cmd

来源：sdk/make_prompt.bat

在打开的窗口中即可直接执行 make、do_merge_libs.bat、midi_2byte.bat 等命令，因为它们依赖的 tools/utils 已经在 PATH 中。

Configuration Options

Make 目标（Targets）

Makefile 关键变量

功能裁剪宏（DEFINES 节选）

构建产物与依赖关系

构建系统产出的关键文件及其关系：

Failure Modes、边界情况与并发

构建系统是单进程顺序执行的批处理流程（Make 串行规则 + 批处理脚本），本身无并发问题；其失败模式集中在环境与工具链层面：

边界情况提示：

• 平台差异宏：__SHELL__ 只在 Linux 分支定义（EXT_CFLAGS），Windows 分支显式留空。若在 Windows 下自行追加该宏，可能导致 download.c 走错分支，因此平台相关宏应保持由 Makefile 统一管理。
• r1-large 系统库：系统库固定选择 r1-large 变体，换芯片内存规格时需同步调整 SYS_LIB_DIR/SYS_INC_DIR，否则链接符号不匹配。
• make clean 的边界：RM := rm -rf（Windows 为 rm -rf 的移植版），只清理构建目录，不触及 post_build 下的脚本与资源，保证 clean 后仍可立即重建。

Performance 与运维注意事项

• 代码体积优先：-Oz（优化大小）+ -flto（链接时优化）+ -mllvm -inline-threshold=5（低内联阈值）是面向 Flash 容量的组合；-mllvm -pi32v2-large-program=true 允许更大规模程序链接。理解这一点对排查"为什么我改的代码没生效"很有用——LTO 下编译器可能跨 TU 内联/裁剪。
• 增量构建：BUILD_DIR := objs 收集中间对象，对象清单 sdk.elf.objs.txt 由构建过程维护；重复 make 时未变更的源文件不会重新编译。
• CI 建议：Linux 环境更适合 CI——无需 fixbat.exe，download.sh 由 bash 驱动；部署时务必先检查工具链目录与 ulimit -n，并确认 PATH 中已注入 /opt/jieli/pi32v2/bin（Makefile 的 export PATH 只对子进程生效）。
• 日志：make VERBOSE=1 输出完整命令行，是定位编译/链接错误的首要手段。

Extension Points

构建系统的扩展点集中在"声明式"位置，业务代码无需改动：

1. 功能裁剪（DEFINES）：增删 HAS_*_DECODER/HAS_*_ENCODER 宏即可启用或移除音频编解码能力，Makefile 是功能集的唯一事实来源。
2. 后处理脚本替换（POST_SCRIPT / RUN_POST_SCRIPT / FIXBAT）：切换芯片方案或下载工具时，只需替换 apps/app/post_build/uc03/ 下的脚本并更新这三个变量，编译主流程不动。
3. 工具链版本升级：修改 TOOL_DIR、SYS_LIB_DIR、SYS_INC_DIR 三处即可整体切换工具链；OBJDUMP/OBJCOPY/OBJSIZEDUMP 等辅助工具仅在 Linux 分支导出，供后续自定义分析规则使用。
4. 资源配置脚本：eqbin2dir.bat、csv2dir.bat 展示了"配置→目录"的转换模式，新增资源类型时可仿照这两个脚本挂入 post_build 流程。

Related Links

• sdk/Makefile — 构建系统核心入口
• sdk/make_prompt.bat — 构建提示符环境
• sdk/MIDI_VER_SELECT.bat — MIDI 版本选择
• sdk/tools/utils/do_merge_libs.bat — 静态库合并
• sdk/apps/app/post_build/uc03/download.bat — 后处理下载脚本（Windows）
• sdk/apps/app/post_build/uc03/eq_tool/eqbin2dir.bat — EQ 配置转换
• sdk/apps/app/post_build/uc03/flash_write_protect/csv2dir.bat — Flash 写保护配置转换

相关目录页：SDK 整体架构见「3.1 SDK 架构」；App 业务与资源组织见「3.3 应用层」。