构建与源码结构

前置条件

编译

git clone https://github.com/ikunshare988/sakura-project.git
cd sakura-project

# BIOS 链 + 内核 + 用户态程序，产出 build\disk.img
powershell -NoProfile -ExecutionPolicy Bypass -File build.ps1

# 可选：额外构建 UEFI 加载器 BOOTX64.EFI 并拼进同一个磁盘映像
powershell -NoProfile -ExecutionPolicy Bypass -File build_efi.ps1

脚本会依次编译引导扇区、stage2、内核与用户态程序，测量链接产物确保不会碰到栈顶， 最后拼出 build\disk.img。

运行与门禁

# 带窗口运行，可操作桌面
qemu-system-x86_64 ^
  -drive "file=build\disk.img,format=raw,if=ide" ^
  -m 256M -vga std -no-reboot

# 无头自测：跑内建测试并输出串口日志
qemu-system-x86_64 ^
  -drive "file=build\disk.img,format=raw,if=ide" ^
  -m 256M -display none -serial file:gate.log -no-reboot

# 判定标准：gate.log 结尾应包含
  # Results: 0xdb/0xdb passed, 0 failed
#   [SHELL] desktop ready

sakura-project/
├── build.ps1                 整体构建脚本（引导链 / 内核 / 用户态 / 磁盘镜像）
├── build_efi.ps1             UEFI 链构建脚本
├── run-gate.ps1              无头 QEMU 门禁（串口断言 + ring3 存活判据）
├── make_vmware.ps1           生成可在 VMware 里启动的磁盘映像
├── AGENTS.md                 并行开发约定：构建目录 / 所有权 / 门禁 / 内存不变量
├── kernel/
│   ├── arch/x86_64/
│   │   ├── boot/             MBR 引导扇区、stage2、上下文切换、中断桩、链接脚本
│   │   └── uefi/             BOOTX64.EFI 加载器
│   ├── include/kernel/       全部内核头文件
│   └── src/
│       ├── mm/               物理内存、页表、内核堆
│       ├── sched.c           调度器（类分层 + 虚拟截止时间）
│       ├── ipc/              进程控制块、同步原语
│       ├── syscall/          系统调用分派与用户进程
│       ├── fs/               FatFs 接入、CanFS 兼容层、procfs
│       ├── net/              e1000 / ARP / IPv4 / ICMP / UDP / TCP / DHCP / NTP
│       ├── drivers/          块设备与总线驱动
│       ├── hw/               PCI / ATA / 键盘 / 鼠标 / HPET / RTC
│       ├── pm/               ACPI 解析、关机 / 重启 / 睡眠状态机
│       ├── security/         权限与会话
│       ├── crypto/           内核侧熵源与 DRBG
│       ├── desktop/          窗口管理、合成器、桌面组件
│       ├── apps/             内置 GUI 应用（当前仍在 ring0）
│       ├── gui/              控件与布局
│       └── pkg/              .ospkg 包管理器
├── userspace/
│   ├── libshittim/           最小 libc + 窗口 API + ring3 绘制基础（<gfx.h>）
│   └── programs/             browser / calculator / cryptotest / editor / explorer /
│                             filemanager / imageviewer / init / settings / shell /
│                             socktest / sysstorm / test
├── legacy/canfs/             CanFS 历史实现（运行时在 kernel/src/fs 的兼容层里）
├── specs/                    设计规格文档与审计报告
├── themes/                   TOML 主题
├── website/                  本官网（静态站 + 发布流水线脚本）
└── third_party/              外部组件（含许可证与来源登记）

仓库内 third_party/ 目录保留各组件的原始许可证文本 （third_party/<组件>/LICENSE*）；未 vendor 上游源码、 只发构建期派生物的组件，其许可证另存于 third_party/licenses/。 每一项的来源 URL、版本或 commit、SHA-256 与改动点都登记在 third_party/README，那是本清单的真相源。
引入策略：内核核心不引入外部实现；仅在非核心且实现复杂处允许宽松许可代码， 且不接受 GPL / LGPL 等传染性许可。任何新增组件都需单独确认后再入库。