环境搭建与工具链安装
本文介绍 AC82N GP-MCU SDK 的开发环境搭建流程与工具链安装细节，涵盖操作系统要求、JL Toolchain（杰理工具链）的安装与验证、烧录工具、Makefile/Code::Blocks 双构建路径，以及常见环境问题排查。
Purpose and Scope
本页面面向首次接触 AC82N SDK 的嵌入式开发者，提供从零开始搭建可编译、可烧录开发环境所需的全部步骤与底层原理说明，包括：
- 支持的操作系统与推荐构建方式（Windows / Linux / macOS）
- JL Toolchain 交叉编译工具链的获取、安装路径约定与验证方法
- 固件烧录工具（USB Updater、Production Burner）的用途
sdk/Makefile的工具链发现机制、编译参数与构建产物- 环境相关的常见错误与解决方案
本页面不涵盖：应用层代码结构（见项目结构页）、外设驱动开发（见各外设示例页）、OTA 升级机制（见升级模块文档）。这些主题属于其他目录页的范畴。
Overview
AC82N 是杰理科技（Jieli-Tech）推出的 GP-MCU（通用 MCU）系列芯片，其 SDK 采用预编译库 + 源码示例的发布模式——仓库包含应用源码与示例工程，但核心驱动以 lib.a 静态库形式提供，必须配合对应的预编译库才能完成编译（README-en.md）。
SDK 的目标芯片平台为 cd09，覆盖 AC822B / AC823B / AC825A / AC826B 四个型号，面向高精度测量与低功耗产品（体脂秤、血压计、血氧仪等）。芯片使用杰理自研的 PI32 内核，因此不能使用通用的 ARM GCC 或 x86 工具链，必须安装杰理定制的 JL Toolchain——一套基于 Clang/LLVM 的交叉编译工具链。
环境搭建的核心设计意图：
- 工具链位置约定统一：Makefile 通过固定的目录约定（Windows
C:/JL/pi32/bin、Linux/opt/jieli/pi32/bin）发现工具链，避免在每次构建时指定路径。 - LTO 链接模型：工具链使用
lto-wrapper/lto-ar进行链接级优化，-flto贯穿编译与链接全过程，这是 PI32 内核代码密度优化（-Oz）的关键。 - 平台自适应：Makefile 通过
OS环境变量区分 Windows/Linux，自动切换编译器名称、后处理脚本（download.bat/download.sh）与编码处理工具。
Architecture
下图展示了 AC82N SDK 开发环境从宿主机到目标板的整体架构：
flowchart TD
subgraph sg_Host["宿主机开发环境"]
IDE["Code::Blocks (Windows)<br/>AC82N_gp_mcu.cbp"]
VSCODE["VS Code<br/>Ctrl+Shift+B 构建任务"]
CLI["命令行<br/>make all / make clean"]
end
subgraph sg_Toolchain["JL Toolchain (PI32 交叉编译)"]
CLANG["clang<br/>-target pi32"]
LD["lto-wrapper<br/>链接与 LTO 优化"]
AR["lto-ar / llvm-ar"]
OBJDUMP["objdump / objcopy<br/>后处理"]
end
subgraph sg_SDK["AC82N SDK 仓库"]
MAKEFILE["sdk/Makefile<br/>工具链发现 + 编译参数"]
SOURCE["apps/gp_mcu 源码<br/>cpu/demo 示例"]
LIBA["预编译库<br/>cpu/cd09/liba/*.a"]
end
subgraph sg_Output["构建与烧录"]
ELF["cpu/cd09/tools/sdk.elf"]
SCRIPT["download.bat / download.sh<br/>自动下载脚本"]
BURNER["USB Updater<br/>isd_download.exe"]
BOARD["目标板<br/>AC82N (cd09)"]
end
IDE -->|"调用"| MAKEFILE
VSCODE -->|"调用"| MAKEFILE
CLI -->|"调用"| MAKEFILE
MAKEFILE -->|"定位 TOOL_DIR"| CLANG
MAKEFILE -->|"定位 TOOL_DIR"| LD
MAKEFILE -->|"定位 TOOL_DIR"| AR
SOURCE --> MAKEFILE
LIBA --> MAKEFILE
CLANG -->|"-flto 编译"| ELF
LD -->|"链接"| ELF
OBJDUMP -->|"生成下载文件"| SCRIPT
ELF --> SCRIPT
SCRIPT -->|"自动执行"| BURNER
BURNER -->|"USB/UART 烧录"| BOARD
架构要点说明：
- 宿主机层：三种入口（Code::Blocks、VS Code、命令行）最终都收敛到
sdk/Makefile定义的构建规则，保证任何平台下构建行为一致。Code::Blocks 工程文件AC82N_gp_mcu.cbp同样基于 Makefile 的编译参数生成。 - 工具链层：JL Toolchain 是唯一受支持的编译器集合。
clang以-target pi32目标编译，lto-wrapper负责链接阶段的全程序优化，objdump/objcopy用于生成下载所需格式。 - SDK 层：仓库源码（
apps/、cpu/demo/）+ 预编译静态库（lib.a）共同输入 Makefile；预编译库缺失会直接导致链接失败（cannot find -lxxx）。 - 输出层：编译产物
sdk.elf生成后，后处理脚本（Windows 为download.bat，Linux 为download.sh）自动触发，最终由 USB Updater（isd_download.exe）或量产烧录器写入目标板。
环境要求与工具链安装
操作系统支持矩阵
SDK 对三类宿主操作系统提供了不同程度的支持（README-en.md）：
| 操作系统 | 支持状态 | 推荐构建方式 | 说明 |
|---|---|---|---|
| Windows | ✅ 完全支持 | Code::Blocks IDE | 官方推荐，双击 AC82N_gp_mcu.cbp 打开工程后按 Ctrl+F9 构建 |
| Linux | ✅ 完全支持 | 命令行 Makefile | 工具链解压到 /opt/jieli 后即可 make all |
| macOS | ⚠️ 需手动配置 | 命令行 Makefile | 交叉编译工具链必须手动配置路径，Makefile 默认不覆盖 |
设计意图：Windows 上 Code::Blocks 是首选，因为官方工具链安装包默认安装到
C:\JL，且tools/make_prompt.bat为命令行构建提供了预配置的构建环境（解决 Windows 下make命令缺失问题）。
安装 JL Toolchain（杰理工具链）
工具链是编译 PI32 内核固件的唯一编译器集合，官方安装文档位于杰理开发者工具环境页面（README-en.md）。
Windows 安装步骤：
- 从官方链接下载并安装 JL Toolchain
- 确认安装目录为
C:\JL\pi32\bin（Makefile 中硬编码的TOOL_DIR，见下文） - 打开命令行执行
clang --version验证安装
Linux 安装步骤：
# 1. 从 pkgman.jieliapp.com 获取工具链下载链接
# http://pkgman.jieliapp.com/doc/all
# 2. 下载后解压到 /opt/jieli 目录（注意目录层次！）
sudo tar -xzf jl_toolchain_xxx.tar.gz -C /opt/jieli
# 3. 验证 /opt/jieli/pi32/bin/clang 存在
ls -l /opt/jieli/pi32/bin/clang
# 4. 验证工具链可用
clang --version
⚠️ 目录层次是关键：Makefile 约定工具链必须位于
/opt/jieli/pi32/bin下的clang可执行文件。解压时若出现/opt/jieli/xxx/pi32/bin/clang的层次，会导致 Makefile 找不到编译器（sdk/Makefile 明确注释了"保证 /opt/jieli/common/bin/clang 存在（注意目录层次）"）。
烧录工具安装
固件烧录需要以下工具（README-en.md）：
| 工具 | 用途 | 获取方式 |
|---|---|---|
| USB Updater | 将固件烧录到目标开发板 | 淘宝申请（isd_download.exe），文档见强制升级工具 |
| Production Burner | 量产 / 裸片烧录 | 通过代理商获取，文档见量产烧录器 |
系统资源要求
Linux 下链接阶段需要大量文件描述符，Makefile 头部明确建议：
# 确认 ulimit -n 的结果足够大（建议大于 8096），
# 否则链接可能会因为打开文件太多而失败
ulimit -n 8096
设计意图：PI32 工具链在 LTO 链接时会同时打开大量中间文件与归档库，默认的 1024 文件描述符上限不足以支撑链接过程，因此需要在构建前提升
ulimit -n。这是 Linux 环境下最常见的构建失败根因。
构建系统详解：sdk/Makefile 的工具链发现机制
sdk/Makefile 是整个环境配置的"事实来源"，它通过 OS 环境变量实现平台自适应（sdk/Makefile）：
# 工具路径设置
ifeq ($(OS), Windows_NT)
# Windows 下工具链位置
TOOL_DIR := C:/JL/pi32/bin
CC := clang.exe
CXX := clang.exe
LD := lto-wrapper.exe
AR := llvm-ar.exe
MKDIR := mkdir_win -p
RM := rm -rf
SYS_LIB_DIR := C:/JL/pi32/libc
SYS_INC_DIR := C:/JL/pi32/include/libc
EXT_CFLAGS := # Windows 下不需要 -D__SHELL__
export PATH:=$(TOOL_DIR);$(PATH)
## 后处理脚本
FIXBAT := tools/utils/fixbat.exe # 用于处理 utf8->gbk 编码问题
POST_SCRIPT := cpu/cd09/tools/download.bat
RUN_POST_SCRIPT := cpu\\cd09\\tools\\download.bat
else
# Linux 下工具链位置
TOOL_DIR := /opt/jieli/pi32/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
SYS_INC_DIR := $(TOOL_DIR)/../include
EXT_CFLAGS := -D__SHELL__ # Linux 下需要这个保证正确处理 download.c
export PATH:=$(TOOL_DIR):$(PATH)
## 后处理脚本
FIXBAT := touch # Linux下不需要处理 bat 编码问题
POST_SCRIPT := cpu/cd09/tools/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)
关键机制解读：
- 路径拼接：最终
CC等变量被拼成完整路径（$(TOOL_DIR)/$(CC)），因此工具链必须精确位于约定目录，否则报clang: command not found。 - PATH 注入：
export PATH:=$(TOOL_DIR):$(PATH)将工具链目录注入构建环境的 PATH，使链接器、脚本调用的子工具都能被找到。 - 平台差异点：
- Windows 的归档器是
llvm-ar.exe，Linux 是lto-ar（两者均支持 LTO 对象归档）； - Windows 需要
fixbat.exe将生成脚本从 UTF-8 转为 GBK 编码，Linux 直接用touch占位； - Linux 额外导出
OBJDUMP/OBJCOPY/OBJSIZEDUMP供后处理脚本使用； - Linux 额外定义
-D__SHELL__，用于在download.c中正确区分 Shell 环境。
- Windows 的归档器是
编译参数与宏定义
CFLAGS 体现了 PI32 架构的代码密度优化策略（sdk/Makefile）：
CFLAGS := \
-target pi32 \
-integrated-as \
-fno-builtin \
-mllvm -pi32-memreg-opt \
-mllvm -pi32-mem-offset-adj-opt \
-mllvm -pi32-const-spill \
-mllvm -pi32-enable-jz \
-mllvm -pi32-tailcall-opt \
-mllvm -inline-threshold=5 \
-mllvm -pi32-enable-itblock=1 \
-Oz \
-flto \
-g \
-Os \
-fallow-pointer-null \
-nostrictpi32 \
-fprefer-gnu-section \
-Wframe-larger-than=256 \
-Wuninitialized \
-fms-extensions \
-fdiscrete-bitfield-abi
DEFINES := \
-DCONFIG_RELEASE_ENABLE \
-DCONFIG_CPU_CD09 \
-DCONFIG_CBUF_IN_MASKROM \
-D__GCC_PI32_LTO__
要点：
-target pi32：指定交叉编译目标为 PI32 内核，这是区别于宿主 clang 的关键参数；-mllvm -pi32-*系列：启用 LLVM 后端针对 PI32 的专用优化（内存寄存器分配、偏移调整、常量溢出、条件跳转、尾调用、IT 块）；-Oz与-Os：以代码尺寸为优化目标（MCU Flash 容量受限）；-flto：链接期优化贯穿编译与链接，与lto-wrapper/lto-ar配合；- 宏定义锁定芯片平台：
CONFIG_CPU_CD09指定 cd09 平台，CONFIG_CBUF_IN_MASKROM指示环形缓冲区代码位于 MaskROM，__GCC_PI32_LTO__启用 LTO 特性宏。
构建产物与自动下载
# 输出文件设置
OUT_ELF := cpu/cd09/tools/sdk.elf
构建成功后生成 cpu/cd09/tools/sdk.elf，随后 Makefile 自动执行后处理脚本（Windows download.bat / Linux download.sh）完成下载（README-en.md）。这意味着一次 make all 不仅完成编译，还会触发烧录流程。
核心流程：从环境准备到固件烧录
sequenceDiagram
participant Dev as 开发者
participant Env as 构建环境 (Shell)
participant MK as Makefile
participant TC as JL Toolchain (clang/lto-wrapper)
participant Post as 后处理脚本 (download.sh/bat)
participant Burner as USB Updater
Dev->>Env: 安装工具链到约定目录 (C:/JL 或 /opt/jieli)
Dev->>Env: (Linux) ulimit -n 8096
Dev->>Env: make all -j`nproc` (或 Code::Blocks 构建)
Env->>MK: 解析 Makefile (OS 判断)
MK->>MK: 拼接 TOOL_DIR 下完整工具路径
MK->>MK: export PATH 注入工具链目录
MK->>TC: clang -target pi32 -flto 编译各 .c 文件
TC->>TC: lto-wrapper 链接 + LTO 全程序优化
TC-->>MK: 生成 cpu/cd09/tools/sdk.elf
MK->>Post: 执行后处理脚本
Post->>Post: 处理编码/格式 (fixbat 或 objcopy)
Post->>Burner: 调用烧录工具/脚本下载
Burner->>Dev: 固件写入目标板
流程说明：
- 准备阶段：工具链必须安装到 Makefile 约定的固定路径。Linux 下解压到
/opt/jieli并保证/opt/jieli/pi32/bin/clang存在；Windows 下安装到C:\JL。 - 环境调优：Linux 需提升文件描述符上限（
ulimit -n 8096），否则链接阶段报Too many open files。 - 构建触发：三种入口等价——命令行
make all、Code::Blocks（内部调用相同规则）、VS Code 任务。 - 编译链接：clang 以
-target pi32编译所有源文件（含-flto），lto-wrapper完成链接与跨编译单元优化。 - 后处理与下载：
download.sh/download.bat自动运行，将sdk.elf转换并写入目标板；若需要手动烧录，则用 USB Updater 打开固件执行下载。
使用示例
快速开始：克隆并构建
以下命令序列是 Linux 环境下的标准流程（README-en.md）：
# 1. 克隆仓库并进入 SDK 目录
git clone https://gitee.com/Jieli-Tech/AC82N.git
cd AC82N/sdk
# 2. （Linux 必需）提升文件描述符上限
ulimit -n 8096
# 3. 并行构建（-j`nproc` 使用全部 CPU 核）
make all -j`nproc`
# 4. 清理构建产物
make clean
# 5. 查看详细编译过程
make all VERBOSE=1
构建成功后
cpu/cd09/tools/sdk.elf生成，下载脚本自动运行（README-en.md）。
Windows 命令行构建
# Windows 下通过预配置脚本打开构建 Shell（解决 make 不在 PATH 的问题）
tools/make_prompt.bat
# 然后在弹出的命令行中执行
make all -j8
手动烧录（USB Updater）
1. 连接硬件：通过 USB 或 UART 连接开发板到 PC
2. 进入编程模式：按住编程键，然后复位或重新上电
3. 打开 USB Updater：启动 isd_download.exe
4. 选择固件：选择编译生成的固件文件
5. 开始烧录：点击下载按钮并等待完成
配置选项
工具链路径与环境变量
| 配置项 | 平台 | 默认值 | 说明 |
|---|---|---|---|
TOOL_DIR | Windows | C:/JL/pi32/bin | 工具链二进制目录，Makefile 硬编码 |
TOOL_DIR | Linux | /opt/jieli/pi32/bin | 工具链二进制目录，Makefile 硬编码 |
SYS_LIB_DIR | Windows | C:/JL/pi32/libc | 系统库（libc）搜索路径 |
SYS_LIB_DIR | Linux | $(TOOL_DIR)/../lib | 系统库搜索路径（相对工具链目录） |
SYS_INC_DIR | Windows | C:/JL/pi32/include/libc | 系统头文件搜索路径 |
SYS_INC_DIR | Linux | $(TOOL_DIR)/../include | 系统头文件搜索路径 |
EXT_CFLAGS | Linux | -D__SHELL__ | Linux 下额外宏定义；Windows 为空 |
构建目标
| 目标 | 命令 | 说明 |
|---|---|---|
| 全部（构建+下载） | make all | 编译并自动执行下载脚本 |
| 清理 | make clean | 清除编译临时文件（objs/ 等） |
| 详细输出 | make all VERBOSE=1 | 显示完整编译命令行 |
| 并行构建 | make all -j\nproc`` | 多核并行加速 |
关键编译宏
| 宏定义 | 用途 |
|---|---|
CONFIG_RELEASE_ENABLE | 启用发布模式配置 |
CONFIG_CPU_CD09 | 指定目标芯片平台 cd09（AC822B/823B/825A/826B） |
CONFIG_CBUF_IN_MASKROM | 环形缓冲区实现位于 MaskROM |
__GCC_PI32_LTO__ | 启用 PI32 GCC 兼容的 LTO 特性 |
失败模式、边缘情况与排查
常见构建错误对照表
| 错误信息 | 根因 | 解决方案 |
|---|---|---|
clang: command not found | 工具链未安装或不在 PATH | 安装 JL Toolchain；确认 TOOL_DIR 目录下存在 clang；Linux 检查 /opt/jieli/pi32/bin/clang |
Too many open files | Linux 文件描述符上限不足 | 执行 ulimit -n 8096（README-en.md） |
cannot find -lxxx | 缺少预编译库文件 | 检查 cpu/cd09/liba/ 下是否存在对应 .a 文件（README-en.md） |
make: command not found | Windows 下 make 未配置 | 使用 tools/make_prompt.bat 打开预配置构建 Shell（README-en.md） |
其他环境陷阱
- 目录层次错误（Linux）：工具链解压后若出现多级嵌套目录（如
/opt/jieli/jl_toolchain_xxx/pi32/bin），Makefile 无法定位 clang。需保证/opt/jieli/pi32/bin/clang直接存在。 - PATH 污染：若宿主系统安装了其他 clang，且其路径优先于工具链目录，
clang --version可能验证通过但实际编译目标错误。Makefile 通过export PATH:=$(TOOL_DIR):$(PATH)将工具链目录置于最前以规避此问题。 - 并行度选择：
-j\nproc`` 在资源受限的虚拟机/CI 中可能因内存不足导致 LTO 链接崩溃，可降低并行度。 - 编码问题（Windows）：生成的后处理脚本需要从 UTF-8 转为 GBK，若
fixbat.exe缺失，download.bat可能无法正确执行。
烧录失败排查
- 烧录前必须确认开发板已进入编程模式（按住编程键 + 复位/重新上电），否则 USB Updater 无法识别设备（README-en.md）。
- 首次烧录优先使用 USB Updater 的
isd_download.exe；量产场景改用 Production Burner 以提高吞吐。
性能与操作注意事项
- LTO 链接内存开销：
-flto全程序优化在链接阶段占用较多内存与文件描述符，这是ulimit -n 8096建议的由来；多核并行（-j）可显著缩短编译时间，但需平衡内存。 - 增量构建：Makefile 会维护
objs/中间目录，未修改的源文件不会重编译；make clean可强制全量重建。 - CI/CD 适配：Linux 环境适合作为 CI 构建机（无 GUI 依赖），只需在镜像中预置工具链并执行
ulimit -n 8096 && make all。 - 版本一致性：预编译库（
lib.a）与源码必须配套发布，升级 SDK 版本时建议先make clean再全量构建，避免旧中间产物与新的库文件不匹配。
扩展点
- 新增芯片平台：若适配新 SoC，需在
DEFINES中修改CONFIG_CPU_XXX宏，并在cpu/下新增对应目录与预编译库。 - 自定义下载流程：后处理脚本
cpu/cd09/tools/download.sh（Linux）与download.bat（Windows）是可替换的钩子，可在 Makefile 的POST_SCRIPT/RUN_POST_SCRIPT变量处切换。 - VS Code 集成：仓库预配置了 VS Code 构建任务（
Ctrl+Shift+B选择all或clean），开发者可在.vscode/tasks.json中扩展自定义任务（README-en.md）。
相关链接
- 项目结构概览 — SDK 目录布局与各模块职责
- 构建与烧录指南 — 完整构建命令与烧录流程（若存在）
- sdk/Makefile — 工具链配置与构建规则的权威来源
- README-en.md — 官方英文说明（环境、构建、烧录章节）
- 杰理开发者工具环境文档 — JL Toolchain 官方安装指南
- 强制升级工具文档 — USB Updater 使用说明
- 量产烧录器文档 — 量产烧录流程