环境搭建与工具链

本文介绍杰理 fw-AD1x-4578_AC104_SDK（AD14N / AD15N / AC104N / AD17N / AD18N 系列通用 MCU SDK）的开发环境搭建流程与配套工具链：包括主机平台支持、杰理编译工具链的安装与验证、烧录工具与音频工具的获取、三种编译方式（Code::Blocks / Makefile / VS Code）的使用，以及编译命令速查、常见错误排查与生产烧录流程。

Purpose and Scope

本页聚焦于从零搭建可用的开发环境并完成首次编译烧录这条主链路，覆盖：

• 各操作系统（Windows / Linux / macOS）的环境要求与差异
• 杰理编译工具链（基于 clang 的 pi32 交叉编译工具链）的安装、路径约定与验证
• USB 升级工具、生产烧写工具、音频工具等辅助工具的获取
• SDK 工程入口（.cbp 与 Makefile）的对应关系与选择原则
• 三种编译方式的完整操作步骤与命令速查表
• 常见编译错误、故障排查与提速手段

以下主题属于兄弟页面，本页仅作指引、不展开：

• 工程结构与目录约定：sdk/app/、sdk/include_lib/、sdk/tools/ 等目录的详细说明，参见「工程结构」页面。
• 应用层开发：voice_toy / mbox_mg / mcu 各应用子模块的功能与开发方式，参见「应用与示例」页面。
• 固件配置：app_config.h 功能开关、app_modules.h 平台配置，参见「配置说明」页面。
• 烧录与升级细节：ISD_CONFIG.INI 参数、OTA 双备份升级等，参见「烧录与升级」页面。

Overview

fw-AD1x-4578_AC104_SDK 是珠海杰理科技股份有限公司发布的通用 MCU SDK，覆盖 AD14N（sh54）、AD15N（sh55）、AD17N（sh57）、AD18N（ch58）及小音箱专用芯片 AC104N。SDK 采用 Release 源码 + 预编译静态库（lib.a） 的交付模式：sdk/app/ 下提供应用源码，sdk/include_lib/liba/ 下按平台提供预编译库，二者通过配套的编译工具链链接为最终固件。

工具链的核心是杰理编译工具链——一套面向 pi32 CPU 平台的交叉编译环境，其可执行文件位于 pi32/bin/clang。它不是一个通用 GCC 工具链，而是杰理针对其自研 CPU 平台定制的 clang 派生版本，因此不能使用系统自带的 clang/gcc 替代。整个开发链路可以概括为：

flowchart LR
    A["主机操作系统<br/>Windows / Linux / macOS"] --> B["杰理编译工具链<br/>pi32/bin/clang"]
    B --> C["SDK 源码<br/>sdk/app + include_lib"]
    C --> D["Makefile / .cbp 工程"]
    D --> E["固件产物<br/>post_build/ 目录"]
    E --> F["USB 升级工具<br/>或生产烧写工具"]
    F --> G["目标芯片<br/>AD14N/AD15N/AD17N/AD18N/AC104N"]

整个环境搭建的核心设计意图是降低平台差异成本：Windows 用户通过 sdk/tools/make_prompt.bat 获得预配置的命令行环境（免去手动配置 PATH 的麻烦），Linux 用户通过 -j 并行参数获得与 Windows 一致的编译体验；同时所有平台共用同一套工具链与 Makefile 体系，保证固件产物的一致性。

Architecture

开发环境整体架构

flowchart TD
    subgraph sg_Host["主机环境（三选一）"]
        Win["Windows<br/>Code::Blocks 或 make_prompt.bat"]
        Lin["Linux<br/>Makefile 命令行"]
        Mac["macOS<br/>需自行配置交叉工具链"]
    end

    subgraph sg_Toolchain["杰理编译工具链"]
        Clang["pi32/bin/clang<br/>（clang 派生编译器）"]
        Make["make + utils 工具集<br/>（sdk/tools/utils）"]
    end

    subgraph sg_SDK["SDK 仓库（fw-AD15N）"]
        Src["sdk/app/src 应用源码"]
        Libs["sdk/include_lib/liba 预编译库<br/>ARCH/pi32_lto + sh54/sh55/sh57/ch58"]
        Projects["*.cbp 工程文件 / Makefile.adxx_*"]
        PostBuild["sdk/app/post_build<br/>isd_download.exe + isd_config.ini"]
    end

    subgraph sg_Output["产物与烧录"]
        Firmware["编译生成的固件"]
        UsbTool["USB 升级工具"]
        ProdTool["生产烧写工具（一拖二/一拖八）"]
    end

    Win --> Clang
    Lin --> Clang
    Mac --> Clang
    Clang --> Projects
    Src --> Projects
    Libs --> Projects
    Projects --> Firmware
    Firmware --> PostBuild
    Firmware --> UsbTool
    Firmware --> ProdTool

组件职责说明

设计意图

1. 预编译库与源码分离：SDK 交付 Release 版本代码，算法与平台底层以 lib.a 形式提供，既保护了核心 IP，又让用户只需关注 app/src 应用层。
2. 按平台隔离构建入口：每个芯片平台（sh54/sh55/sh57/ch58）都有独立的 .cbp 与 Makefile，避免了多平台代码混编带来的链接错误——这也是「链接错误时先检查是否选错芯片工程」这一 FAQ 的根本原因。
3. 环境封装优先于全局安装：Windows 下通过 make_prompt.bat 注入环境变量，而不是要求用户修改系统 PATH，显著降低了新手配置成本。

环境搭建步骤

前提条件（按操作系统）

SDK 官方对不同主机平台给出了差异化支持策略，核心约束如下：

该差异表直接决定了后续所有编译方式的选择：Windows 用户优先走 Code::Blocks 或 make_prompt.bat；Linux 用户走 Makefile 命令行；macOS 用户则需要额外完成工具链的 PATH 注入。

安装杰理编译工具链

工具链安装是环境搭建的核心步骤，官方指引如下：

1. 下载并安装杰理编译工具链：官方下载链接
2. Linux 用户可从此处下载：pkgman.jieliapp.com
   • 下载后解压到 /opt/jieli 目录
   • 确保 /opt/jieli/pi32/bin/clang 存在
3. 安装完成后验证：

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

Source: README.md

设计意图：工具链统一安装在 /opt/jieli/pi32/bin/ 下，pi32 是杰理自研 CPU 平台的架构名。SDK 的 Makefile 与 Code::Blocks 工程均按此约定路径查找编译器，因此路径约定是环境是否可用的关键——若 clang 找不到（报 clang: command not found），首先要检查的正是该路径是否被正确加入 PATH 或工具链是否解压到了预期位置。

安装烧录工具

固件生成后需要两类烧录工具：

音频工具

打包、音频文件转换、MIDI 等通用音频工具：下载链接，提取码：3jey。这些工具用于准备音频素材（如将音频转为 SDK 支持的 .a 格式、生成 MIDI 资源），属于内容制作链路，与编译链路相对独立。

克隆仓库

环境就绪后，克隆 SDK 并进入工程目录：

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

Source: README.md

工程入口与芯片对应关系

SDK 在 sdk/ 根目录预置了 9 个应用工程，每个工程绑定唯一的芯片平台与应用类型：

选择原则：先确定目标芯片（决定平台目录 sh54/sh55/sh57/ch58），再确定应用类型（voice_toy / mcu / mbox_mg），即可唯一确定工程文件。错误的选择会在链接阶段暴露（例如芯片平台库不匹配），这也是「链接错误时检查工程选择」这一提示的由来。

编译流程与命令参考

从源码到固件的构建流水线

flowchart TD
    Start([开始]) --> Choose{"选择构建入口"}
    Choose -->|"Windows 推荐"| CB["Code::Blocks<br/>打开 .cbp → Build Ctrl+F9"]
    Choose -->|"命令行"| MK["make_prompt.bat 或 Linux shell<br/>make -f Makefile.adxx_xxx all -j4"]
    Choose -->|"VS Code"| VS["Ctrl+Shift+B 选择编译目标"]
    CB --> Compile["交叉编译<br/>pi32/bin/clang 编译 app 源码"]
    MK --> Compile
    VS --> Compile
    Compile --> Link["链接预编译库 lib.a<br/>include_lib/liba/ 按平台匹配"]
    Link --> Post["post_build 处理<br/>isd_download.exe / 下载脚本"]
    Post --> FW["生成固件"]
    FW --> Burn["USB 升级工具烧录<br/>或生产烧写工具"]
    Burn --> End([完成])

构建流水线分为四个阶段：

1. 选择入口：三种方式（Code::Blocks / Makefile / VS Code）最终都调用同一套编译体系，产物一致。
2. 交叉编译：clang 将 app/src 下的 C 源码编译为 pi32 平台目标文件——这是与通用 GCC 工具链的关键区别，普通编译器无法完成该步骤。
3. 链接：将目标文件与 include_lib/liba/ 下对应平台的 .a 静态库链接。链接器按 Makefile/.cbp 中声明的平台选择库目录（sh54/sh55/sh57/ch58），选错平台即报链接错误。
4. 编译后处理与烧录：post_build/ 目录中的 isd_download.exe、isd_config.ini 与下载脚本负责固件后处理与下载，最终通过 USB 升级工具或生产烧写工具写入芯片。

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

1. 确保已安装杰理编译工具链
2. 双击对应的 .cbp 工程文件打开 Code::Blocks
3. 点击 Build → Build（Ctrl+F9）
4. 编译成功后在 post_build/ 目录下生成固件

方式二：Makefile 命令行

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

# 选择对应的 Makefile 进行编译
make -f Makefile.ad15n_voice_toy all -j4
make -f Makefile.ad15n_mcu all -j4

Source: README.md

Linux 用户使用相同 Makefile 体系，但需自行修改 download_bat.c 脚本适配：

# Linux 用户 (需要自行修改download_bat.c脚本适配)
cd sdk
make -f Makefile.ad15n_voice_toy all -j`nproc`

Source: README.md

提示：编译前请确保 USB 升级工具正确连接且目标板已进入编程模式。所有支持的 target 名称见 Makefile 开头的注释。

设计意图：make_prompt.bat 的核心价值是环境变量封装——它一次性设置好 make 的路径与工具链 PATH，用户无需理解底层环境配置即可编译。这也是 FAQ 中「Windows 下报错 make 不是有效命令」的标准解法。

方式三：VS Code 编译

仓库已预配置 VS Code 任务，按 Ctrl+Shift+B 即可弹出编译目标选择列表。该方式与 Makefile 方式共用构建后端，适合偏好 IDE 且不使用 Code::Blocks 的开发者。

编译命令速查表

以下命令在 sdk/ 目录下执行：

命令命名规律：Makefile.<芯片>_<应用类型>，如 ad15n_voice_toy 表示 AD15N 语音玩具工程，与 .cbp 文件的命名一一对应，便于在两种编译方式间无缝切换。

首次烧录流程

sequenceDiagram
    participant Dev as 开发者
    participant Board as 目标板
    participant Tool as USB 升级工具

    Dev->>Board: USB 连接开发板
    Dev->>Board: 按住烧录按键并复位/重新上电（进入编程模式）
    Dev->>Tool: 启动 USB 升级工具
    Dev->>Tool: 选择编译生成的固件文件
    Dev->>Tool: 点击下载
    Tool->>Board: 写入固件
    Board-->>Dev: 烧录完成

烧录要点：

1. 连接硬件：将开发板通过 USB 或 USB 升级工具 连接到 PC
2. 进入编程模式：方式一（USB）按住烧录按键后复位/重新上电；方式二（USB/UART）通过 USB 升级工具进入
3. 打开 USB 升级工具：启动烧录上位机
4. 选择固件：选择编译生成的固件文件
5. 开始烧录：点击下载按钮，等待烧录完成

注意：烧录前请确保 USB 升级工具正确连接且目标板已进入编程模式。关于 ISD_CONFIG.INI 配置详见 ISD 配置说明。

量产场景请使用杰理生产烧写工具（一拖二 / 一拖八），支持裸片烧写，详见 一拖二烧写器使用说明 与 一拖八烧写器使用说明。

故障排查与常见错误

常见编译错误对照表

该表揭示了工具链环境的三大故障源：工具链缺失/路径错误、库文件缺失、构建入口选择错误。前两类属于环境问题，第三类属于工程配置问题，排查顺序应遵循"先环境后工程"。

平台相关边界情况

• Linux 编译：Makefile 命令行编译在 Linux 下可用，但需要重写 download_bat.c 脚本适配 Linux 环境——该脚本在 Windows 下负责调用下载工具，Linux 下需替换为对应的串口/USB 下载逻辑。这是 Linux 平台与 Windows 平台编译体验的已知差异。
• macOS 编译：官方不提供一键脚本，需自行配置交叉编译工具链（包括安装、PATH 注入与验证），对用户要求最高。
• 工具链版本匹配：SDK 为 Release 版本，需配合对应命名规则的库文件（lib.a）编译——工具链版本与 SDK 版本不匹配时可能出现链接器无法识别库格式的错误。

性能与运维建议

• 并行编译提速：使用 -j 参数指定并行任务数，如 make -j4（数字为并行任务数）；Linux 下可直接使用 -j`nproc`` 自动取 CPU 核心数。多核机器上并行编译可显著缩短大型工程的构建时间。
• 增量构建：Makefile 体系天然支持增量编译，只重新编译变更部分；全量重建使用 make clean 后重新 make all。
• 固件输出位置：编译产物在 post_build/ 目录下生成，该目录同时包含 isd_download.exe 与 isd_config.ini，是固件下载配置（如烧录地址、下载方式）的集中管理位置。
• 日志与调试：串口日志可通过 UART 输出调试信息；也可利用空闲 GPIO 输出调试波形测量时序（GPIO Debug 手法）。

扩展点与自定义

• 新增应用工程：基于现有的 .cbp 工程和 app/src/ 中的应用代码进行修改，配置对应用例即可，无需从零搭建构建系统。
• 切换芯片平台：选择对应的 .cbp 工程或 Makefile 即可——SDK 已为每个芯片平台预配置独立的编译入口，平台切换不涉及工具链变更（同一套 clang 工具链服务于全部平台）。
• 编译后处理定制：sdk/app/post_build/ 中的下载脚本与 isd_config.ini 可针对量产/特殊烧录场景定制，例如调整固件下载参数。
• 功能开关配置：编辑 sdk/app/src/<应用>/app_config.h 可配置目标应用的功能开关；不同 CPU 平台的配置位于 sdk/app/src/<应用>/<平台>/app_modules.h——这些开关在编译期生效，属于"配置即裁剪"的设计模式。

Related Links

• 工程结构 — sdk/app、sdk/include_lib、sdk/tools 等目录的详细说明
• 应用与示例 — voice_toy / mbox_mg / mcu 各应用子模块功能
• 配置说明 — app_config.h 功能开关与 app_modules.h 平台配置
• 烧录与升级 — ISD_CONFIG.INI、生产烧写（一拖二/一拖八）、OTA 双备份升级

外部资源：

• 杰理在线文档中心（AD14 系列）
• 杰理编译工具链下载
• Linux 工具链下载（pkgman.jieliapp.com）
• USB 升级工具使用文档
• SDK 手册
• SDK 版本历史
• 问题反馈（Gitee Issues）