跳转至

从源码构建

本文面向开发者：搭建工具链、构建桌面端与各板型固件、重新生成字体与图标资源。只刷机不需要看这里——release 刷机包见支持的板子。

编译依赖

  1. 安装 ESP-IDF v5.5.5（ESP32 固件）。
  2. 安装 PlatformIO Core（Seeed Wio Terminal 固件）。
  3. 安装 便携 MSYS2（desktop 后端的 MinGW 编译环境）： 
    curl -L -o tools/dl/msys2-base.tar.xz https://mirrors.tuna.tsinghua.edu.cn/msys2/distrib/x86_64/msys2-base-x86_64-20260611.tar.xz
mkdir -p tools/msys64 && tar -xf tools/dl/msys2-base.tar.xz -C tools/msys64 --strip-components=1
tools/msys64/usr/bin/bash.exe -lc "echo ok"   # 首次运行完成初始化
echo 'Server = https://mirrors.tuna.tsinghua.edu.cn/msys2/msys/$arch'  > tools/msys64/etc/pacman.d/mirrorlist.msys
echo 'Server = https://mirrors.tuna.tsinghua.edu.cn/msys2/mingw/$repo' > tools/msys64/etc/pacman.d/mirrorlist.mingw
tools/msys64/usr/bin/bash.exe -lc "pacman -Sy --noconfirm mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-ninja mingw-w64-ucrt-x86_64-SDL2 mingw-w64-ucrt-x86_64-cjson"
  4. 克隆 LVGL 源码：git clone --depth 1 -b release/v9.3 https://gitee.com/mirrors/lvgl.git third_party/lvgl
  5. 拓竹 POSIX 后端依赖（仅 Linux 桌面端与 Android 需要；Windows 桌面端用 winhttp/openssl、ESP32 用 IDF mbedTLS，均不涉及）： 
    git clone --depth 1 --recurse-submodules --shallow-submodules -b v3.6.5 \
  https://github.com/Mbed-TLS/mbedtls.git third_party/mbedtls
curl -L -o third_party/cacert.pem https://curl.se/ca/cacert.pem
    Android 端不用手动执行——tools/fetch-android-deps.sh 已包含这两项。

构建命令

# 桌面端（Windows：真实控制端 + 开发模拟器；Linux/macOS：桌面目标）
bash tools/build-desktop.sh
./src/ports/desktop/build/KlipperScreen-esp.exe              # 真实 Moonraker 控制端
./src/ports/desktop/build/klipper_remote_simulator.exe            # 布局模拟器
./src/ports/desktop/build/klipper_remote_simulator.exe 3000 x.bmp # 运行 3 秒后截图（开发用）

# ESP32 固件（多板型，脚本封装 idf.py）
bash tools/build-esp32.sh <board> build          # 只构建
bash tools/build-esp32.sh <board> flash COMx     # 构建并烧录
bash tools/build-esp32.sh all build              # 全部板型

Wio Terminal 使用独立的 PlatformIO 端口；网卡固件、下载模式和 USB 恢复细节见 Wio Terminal：

platformio run -d src/ports/wio_terminal -e wio-terminal
platformio run -d src/ports/wio_terminal -e wio-terminal -t upload --upload-port COM3
python tools/make_uf2.py `
  src/ports/wio_terminal/.pio/build/wio-terminal/firmware.bin `
  src/ports/wio_terminal/.pio/build/wio-terminal/firmware.uf2

board 取值：cyd_2432s028r / cyd_2432s028r_plus / e32r35t / esp32s3-st7789-320_240-ec11 / esp32-st7735s-128_160-ec11 / esp32-st7789-320_240-ec11 / esp32-ILI9341-320_240-ec11 / esp32-ST7796-320_240-ec11 / esp32s3-st7796-480_320-xpt2046-ec11 / esp32s3-ILI9488-480_320-xpt2046-ec11 / esp32s3-ILI9341-320_240-xpt2046-ec11 / jc8048w550 / esp32s3-JLC-SZP / esp32s3-retro-go / esp32c3-st7789-320_240-ec11。每板型有独立的构建目录与 sdkconfig（芯片目标不同，不能混用）。

在 Windows 上直接调 idf.py 要走 tools/idf.ps1 包装——Git Bash 会把 MSYSTEM 注入子进程，导致 idf.py 静默空转。

Android 端（APK）

Android 端口（src/ports/android）复用桌面端的整套 UI/核心代码：SDL2 安卓工程 + CMake 编 libmain.so（入口同为 src/ports/desktop/main.c），Gradle 打 APK。平时出包直接用 CI 的 android job（artifact android-apk-<ref>），本地构建：

  1. 装 JDK 17 + Android SDK（platform android-34、build-tools 34.0.0、任一 NDK、CMake 3.22.1，Android Studio 装齐即可）。
  2. 拉取原生依赖（SDL2 2.30.9 源码 + cJSON + SDLActivity 胶水层，均不入库）： 
    bash tools/fetch-android-deps.sh
  3. 构建（third_party/lvgl 与桌面端共用，同样要先拉）： 
    cd src/ports/android
bash gradlew assembleRelease          # NDK 非 AGP 默认版本时加 -PndkVersion=<版本>
# 产物：app/build/outputs/apk/release/app-release.apk

行为说明：方向完全跟随系统（fullSensor，系统开自动旋转则四向跟随、关闭则锁当前方向），系统旋转会触发 UI 按新分辨率整体重建；应用内不提供旋转设置（该设置项在 Android 上隐藏）。配置存应用私有目录；release 构建目前用 debug 密钥签名（可直接侧载，上架 release 前换正式密钥）；WiFi 由系统管理，设置页不显示「无线网络」入口（同 macOS）；「背光」「自动息屏」「屏幕方向」行在 Android 上不显示；本机 gcode 缩略图与检查更新为 Linux 上位机专属能力，Android 不提供；语言与主题切换均为动态重建，无需重启应用。

字体生成与替换

界面里所有字符串字面量的非 ASCII 字符会被自动提取，生成 CJK 子集字体。改了任何 UI 字符串后必须重新生成，否则新字显示为 □：

# 默认用 C:/Windows/Fonts/simhei.ttf，可 --font 换
python tools/fontgen/gen_fonts.py

图标生成与替换（assets/icons.h）

界面图标的 SVG 原件在 src/ui/assets/svg/。新增/替换 SVG 后重新生成：

# 首次：装依赖（Node 端 resvg + Python 端 pypng/lz4）
cd tools/icongen && npm install --registry=https://registry.npmmirror.com
python -m venv .venv && .venv/Scripts/python -m pip install pypng lz4
cd ../..
# 新增/替换 SVG 后重新生成：
node tools/icongen/gen_icons.mjs