kernel_flutter_build.py 完整使用手册

一、脚本功能

1. 内核编译

   • 支持 full / incremental / fast / deb 四种模式
   • 自动启用 ccache 加速
   • 支持 distcc 分布式编译
   • 低内存环境自动降线程 + 创建 Swap

2. Flutter 集成（可选）

   • 不再安装/编译 Flutter SDK
   • 通过 --flutter-bundle 直接引用已编译的 Linux Flutter 产物
   • 产物无效或未提供时，自动回退到原生 Linux 桌面

3. 镜像生成（可选）

   • --build-iso：生成可启动 ISO 镜像
   • --build-img：生成可启动 raw 磁盘镜像（.img）

4. 产物管理

   • 所有最终产物默认输出到 /output/
   • 自动生成 build_manifest.json 产物清单
   • 编译状态持久化到 ./kernel_flutter_build/.build_state.json

---

二、参数速查表

参数	简写	默认值	说明
--kernel-version	-v	6.12	要编译的 Linux 内核版本
--mode	-m	incremental	编译模式：full / fast / incremental / deb
--config	-c	auto	内核配置：auto / menuconfig / localmodconfig / 配置文件路径
--arch	-a	auto	目标架构，默认自动检测
--mirror		tsinghua	内核源码下载镜像：tsinghua / ustc / kernel_org
--work-dir	-w	./kernel_flutter_build	工作目录（源码、缓存、状态文件）
--output-dir	-o	/output	最终产物输出目录
--distcc-hosts			distcc 分布式编译主机，空格分隔
--flutter-bundle	-f		已编译的 Linux Flutter bundle 目录
--build-iso			生成可启动 ISO
--output-iso			指定 ISO 输出路径
--build-img			生成可启动 raw 磁盘镜像
--output-img			指定 IMG 输出路径
--img-size		8	IMG 大小，单位 GB
--force-download			强制重新下载内核源码
--force-reconfig			强制重新配置内核
--skip-deps			跳过依赖安装
--clean			执行 make clean
--mrproper			执行 make mrproper 彻底清理

---

三、常用命令示例

1. 首次完整编译内核

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode full

2. 日常增量编译

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode incremental

3. 快速验证（仅编译内核镜像）

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode fast

4. 生成 deb 包

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode deb

5. 生成可启动 ISO 镜像

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode full --build-iso

6. 生成可启动 raw 磁盘镜像

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode full --build-img

7. 同时生成 ISO + IMG

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode full --build-iso --build-img

8. 嵌入 Flutter 应用并生成 ISO

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode full \
    --flutter-bundle /path/to/your_app/build/linux/arm64/release/bundle \
    --build-iso

9. 指定输出目录

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode full \
    --output-dir /mnt/build_output

10. 指定 IMG 大小

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode full \
    --build-img --img-size 16

11. 使用自定义内核配置

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode full \
    --config /path/to/your_kernel_config

12. 启动 menuconfig 手动配置

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode full --config menuconfig

13. 分布式编译

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode full \
    --distcc-hosts "192.168.1.100 192.168.1.101"

14. 彻底清理后重新编译

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode full --mrproper

15. 跳过依赖安装（依赖已装过时）

sudo python3 kernel_flutter_build.py --kernel-version 6.12 --mode incremental --skip-deps

---

四、输出目录结构

执行 --build-iso --build-img 后，/output/ 目录大致如下：

/output/
├── linux-image-6.12.0-1custom_arm64.deb
├── linux-headers-6.12.0-1custom_arm64.deb
├── linux-libc-dev-6.12.0-1custom_arm64.deb
├── flutter_app/                                # --flutter-bundle 有效时
├── custom-ubuntu-6.12-arm64.iso                # --build-iso
├── custom-ubuntu-6.12-arm64.img                # --build-img
└── build_manifest.json

build_manifest.json 示例：

{
  "build_time": "2026-07-27 14:30:00",
  "elapsed_seconds": 1234.56,
  "kernel_version": "6.12",
  "arch": "arm64",
  "config_hash": "a1b2c3d4e5f67890",
  "build_count": 3,
  "outputs": {
    "kernel_debs": [
      "/output/linux-image-6.12.0-1custom_arm64.deb",
      "/output/linux-headers-6.12.0-1custom_arm64.deb"
    ],
    "flutter_app": "/output/flutter_app",
    "iso": "/output/custom-ubuntu-6.12-arm64.iso",
    "img": "/output/custom-ubuntu-6.12-arm64.img"
  }
}

---

五、编译模式说明

模式	行为	适用场景
full	全量编译内核 + 模块 + 生成 deb 包	首次编译或配置变更后
incremental	复用 .o 文件增量编译 + deb 包	日常开发迭代
fast	仅编译内核镜像，不生成模块/deb	快速验证配置
deb	同 full，强调生成 deb 包	发布/安装包用途

---

六、Flutter bundle 说明

bundle 目录通常位于 Flutter 项目编译后路径：

/path/to/project/build/linux/x64/release/bundle
/path/to/project/build/linux/arm64/release/bundle

脚本会校验：

• 目录是否存在
• 是否包含可执行文件
• 是否包含 lib/ 或 data/ 目录

校验失败时自动回退到原生桌面，不会中断编译。

---

七、注意事项

1. 必须 root 权限：脚本会安装依赖、创建 Swap、挂载 loop 设备等，需要用 sudo 执行。
2. 磁盘空间：建议至少 20GB 空闲空间，生成 IMG 时建议额外 16GB 以上。
3. 内存：低于 4GB 会自动启用低内存优化和 Swap。
4. IMG 启动：默认 GRUB 使用 /dev/sda1 作为根分区，若虚拟机磁盘设备名不同，可能需要在 GRUB 命令行临时修改或使用 UUID。
5. ARM64 EFI：IMG 生成依赖 grub-efi-arm64-bin，首次运行会自动安装。
6. 断点续传：内核源码下载支持断点续传，失败会自动切换镜像源。