ToaruOS 技术文档

1. 安装指南

1.1 使用 Docker 构建

对于一般用户来说，建议在 GitHub 上 fork 仓库并使用 GitHub 的 CI 流水线进行构建。

如果你想在本地具有 Docker 的 Linux 主机上构建，可以使用提供的构建容器。首先克隆 ToaruOS 仓库，然后使用以下命令：

git clone https://github.com/klange/toaruos
cd toaruos
git submodule update --init kuroko
docker pull toaruos/build-tools:1.99.x
docker run -v `pwd`:/root/misaka -w /root/misaka -e LANG=C.UTF-8 -t toaruos/build-tools:1.99.x util/build-in-docker.sh

构建完成后，可以运行各种实用程序目标（如 make run 等）。尝试使用 make shell 在 QEMU 中通过串行端口运行 ToaruOS 的 shell。

1.2 构建过程内部

Makefile 使用 Kuroko 工具 auto-dep.krk 生成用户空间应用程序和库的附加 Makefile，自动解析基于 #include 指令的依赖。

以不确定的顺序，构建 C 库、内核、用户空间库和应用程序，将它们组合成压缩归档以用作 ramdisk，然后打包成 ISO9660 文件系统镜像。

1.3 项目布局

• apps - 用户空间应用程序，全部为第一方。
• base - Ramdisk 根文件系统暂存目录。包括 base/usr/include 中的 C 头文件，以及窗口管理器和窗口装饰器使用的图形资源。
• boot - BIOS 和 EFI 引导程序，带有交互式菜单。
• build - 平台端口辅助构建脚本。
• kernel - Misaka 内核。
• kuroko - Kuroko 解释器的子模块。
• lib - 用户空间库。
• libc - C 标准库实现。
• linker - 用户空间动态链接器/加载器，实现共享库支持。
• modules - 内核可加载驱动模块。
• util - 实用脚本，工具链（binutils/gcc）暂存目录。
• .make - 生成的 Makefile。

1.4 文件系统布局

根文件系统布局如下：

• bin: 第一方应用程序。
• cdrom: 光盘挂载点，如果可用。
• dev: 虚拟设备目录，由内核生成。
  • net: 网络接口设备。
  • pex: 数据包交换中心，列出可访问的 IPC 服务。
  • pts: PTY 副本，TTY 的端点。
• etc: 配置文件，启动脚本。
• home: 用户目录。
• lib: 第一方库
  • kuroko: Kuroko 模块。
• mod: 可加载内核模块。
• proc: 虚拟文件，呈现内核状态。
  • 1 等：每个进程的状态信息虚拟文件。
• src: 源文件，见“项目布局”部分。
• tmp: 通常挂载为读写 tmpfs。
• usr: 用户空间资源
  • bin: 第三方应用程序，通常在安装软件包之前为空。
  • include: 头文件，包括可能来自第三方软件包的。
  • lib: 第三方库。默认应该有 libgcc_s.so。
  • share: 各种资源。
    • bim: 文本编辑器的语法高亮显示和主题。
    • cursor: 鼠标光标精灵。
    • fonts: TrueType 字体文件。实时光盘包含 Deja Vu Sans 字体。
    • games: 游戏相关资源文件的临时存放地，如 Doom wad。
    • help: 帮助浏览器应用程序的文档文件。
    • icons: PNG 图标，按尺寸进一步划分为目录。
    • ttk: 窗口管理器和窗口装饰器精灵资源。
    • wallpapers: JPEG 壁纸。
• var: 运行时文件，包括软件包管理器清单缓存、PID 文件、一些锁文件等。

2. 项目的使用说明

ToaruOS 是一个针对 x86-64 个人计算机和 ARMv8 的实验性支持的完整操作系统。该项目旨在作为教育资源，提供主要桌面操作系统中功能的代表性微观模型。

系统包括内核、引导加载程序、动态共享对象链接器、C 标准库、自己的合成窗口系统、动态字节码编译的编程语言、高级代码编辑器以及数十个其他实用程序和示例应用程序。

ToaruOS 的使用涉及以下主要组件：

• Misaka 内核：操作系统的核心，提供基础功能。
• Yutani 窗口合成器：管理窗口缓冲区、布局和输入路由。
• Bim 文本编辑器：一个受 Vim 启发的文本编辑器，支持语法高亮显示。
• 终端：一个类似于 xterm 的终端模拟器，支持 24 位颜色。
• ld.so 动态链接器/加载器：加载动态链接 ELF 二进制文件。
• Esh Shell：支持管道、重定向、变量等。
• Kuroko 解释器：动态字节码编译的编程语言。

3. 项目 API 使用文档

ToaruOS 的 API 使用文档主要涉及内核 API、用户空间库 API 和系统调用的描述。由于项目的复杂性，具体的 API 文档通常在项目的源代码注释中详细描述，以便开发者在使用时进行参考。

以下是一些主要的 API 组件：

• 内核 API：提供底层数据结构和系统调用接口，用于设备驱动程序和系统级编程。
• 用户空间库 API：包括标准库函数、图形库、窗口管理器接口等。
• 系统调用接口：提供用户空间程序与内核之间交互的方法，如文件操作、进程管理、网络通信等。

4. 项目安装方式

项目的安装方式已在“安装指南”部分详细描述，主要包括使用 Docker 容器进行构建和在本地主机上手动构建两种方式。以下是简要的安装步骤：

• 克隆 ToaruOS 仓库。
• 更新子模块。
• 拉取 Docker 镜像（如果使用 Docker）。
• 在 Docker 容器中运行构建脚本。
• 构建完成后，使用 QEMU 或虚拟机软件运行 ToaruOS。