SerenityOS 官方文档导航指南从构建、测试到内核与浏览器的完整技术路线图【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenitySerenityOS 是一个从零开始构建、自成一体的类 Unix 操作系统The Serenity Operating System 。本文以仓库中的 Documentation/README.md 为骨架将其索引的全部官方文档整理成一份可检索、可跳转的技术导航并逐节补充仓库源码级的背景说明帮助你在阅读 BuildInstructions.md 时知道去哪找高级选项、在研究 Meta/serenity.sh 时知道对应哪些文档。读完本文你将获得一条从环境准备、构建运行、测试调试到深入内核与 LibWeb 的完整学习路径并了解每份文档在仓库中的准确相对位置方便后续在 README.md 的 Get in touch and participate 一节加入 Discord 社区提问。文档总览与使用前提官方文档存放在仓库根目录的Documentation/下包含构建运行、编辑器配置、开发规范、文件格式、浏览器LibWeb、内核等多个主题的子目录。文档的时效性说明明确提醒SerenityOS 开发节奏很快部分文档可能过时若发现错误可提交 PR 修正若有文档未解答的问题可先查阅 FAQ.md再前往社区提问。同时Links.md 汇总了互联网上其他有用的页面清单。从仓库源码可以印证文档所述的开发模式构建入口脚本 Meta/serenity.sh 提供了build、install、image、run、gdb、test、rebuild等子命令见 Meta/serenity.sh文档索引中列出的构建与运行条目正是这些命令的配套说明。构建与运行从零到 QEMU 启动基础构建核心入口是 BuildInstructions.md它覆盖了从依赖安装到首次启动的全流程一键命令Meta/serenity.sh run会完成编译、安装输出到仓库内Build/architecture/Root、制作磁盘镜像并用 QEMU 启动系统。首次运行还会下载数据库文件并构建交叉编译工具链之后会明显加快。仅编译不运行Meta/serenity.sh build用于只验证代码能否编译通过。架构选择默认构建宿主架构支持x86_64、aarch64、riscv64可通过SERENITY_ARCH环境变量切换例如SERENITY_ARCHaarch64 Meta/serenity.sh run。默认账号anon用户密码为foo且默认无需密码即可su到root作为开发便利若需收紧可从wheel组移除anon。对照 Meta/serenity.sh 的实现可以看到run命令依次执行build_target、build_target install、build_image再build_target run与文档描述完全一致若传入额外参数还会将其作为内核命令行写入SERENITY_KERNEL_CMDLINE环境变量。依赖与平台差异文档按系统给出了详细的依赖清单Debian / Ubuntubuild-essential cmake curl libmpfr-dev libmpc-dev libgmp-dev e2fsprogs ninja-build qemu-system-gui qemu-system-x86 qemu-utils ccache rsync unzip texinfo libssl-dev zlib1g-dev可选fuse2fs以无 root 构建镜像。Arch / Manjarobase-devel cmake curl mpfr libmpc gmp e2fsprogs ninja qemu-desktop qemu-system-aarch64 ccache rsync unzip。SerenityOS 本机自举需要bash cmake curl e2fsprogs gawk genext2fs git ninja patch python3 qemu rsync等 ports用 GCC 构建还需gcc、gmp、mpcports且因 Shell 的 POSIX 兼容性未完成需要/bin/sh指向/usr/local/bin/bash的符号链接可在自定义脚本中加入ln -sf /usr/local/bin/bash mnt/bin/sh。版本下限主机编译器需支持 C26 特性实测过 gcc-14 与 Clang 1719QEMU 需 6.2CMake 需 3.25.0Serenity 相关补丁已上游合入 CMake低于该版本时构建脚本会尝试从源码编译 CMake。若此前用旧版 CMake 构建过需手动删除Build/*/CMakeCache.txt。WindowsWSL2、macOS、其他 Linux/*NIX 分别有专属文档BuildInstructionsWindows.md、BuildInstructionsMacOS.md、BuildInstructionsOther.md。Ports安装第三方软件SerenityOS 没有二进制包管理器第三方软件以port形式从源码构建。文档给出的操作是进入Ports/name目录例如 Ports/curl运行./package.sh下次启动系统即可使用。文档还列出了构建 ports 的常见附加依赖autoconf、automake、bison、flex、gettext、gperf、help2man、imagemagick、libtool、lzip、meson、nasm、python3-packaging、qt6-base-dev、rename、zip以及个别 ports 的特殊依赖如openjdk-17-jdk编译 OpenJDK、p7zip-full用于 msttcorefonts、rake构建 mruby并提醒部分依赖需要/usr/bin/python到/usr/bin/python3的符号链接。高级构建磁盘镜像、架构、CMake 选项与 SuperBuildAdvancedBuildInstructions.md 覆盖了基础文档之外的进阶场景内容相当密集自定义磁盘镜像在项目根创建sync-local.sh在构建阶段向镜像文件系统写入/修改/删除文件例如把键盘布局写进mnt/etc/Keyboard.ini[Mapping]节的Keymapsde即德国键盘完整键盘映射列表见 Base/res/keymaps/。这种方式比在系统内运行keymap程序更能跨镜像重建持久生效。Ninja 专用目标ninja limine-image、ninja grub-image、ninja grub-uefi-image、ninja extlinux-image各类 x86-64 启动镜像、ninja raspberry-pi-imageAArch64 树莓派镜像、ninja check-styleCI 风格检查、ninja install-ports、ninja lint-shell-scripts、ninja all_generated、ninja configure-components。这些目标需在Build/architecture目录下直接运行。CMake 构建选项包括ENABLE_ADDRESS_SANITIZER/ENABLE_KERNEL_ADDRESS_SANITIZER、ENABLE_UNDEFINED_SANITIZER/ENABLE_KERNEL_UNDEFINED_SANITIZER、ENABLE_MEMORY_SANITIZER、ENABLE_FUZZERS系列、ENABLE_EXTRA_KERNEL_DEBUG_SYMBOLS、ENABLE_KERNEL_LTO、ENABLE_MOLD_LINKER、ENABLE_JAKT、INCLUDE_WASM_SPEC_TESTS、SERENITY_TOOLCHAINGNU 或 Clang、SERENITY_ARCH、BUILD_component、BUILD_EVERYTHING、SERENITY_CACHE_DIR、ENABLE_NETWORK_DOWNLOADS、ENABLE_ACCELERATED_GRAPHICS等。组件级component_name_DEBUG调试宏清单见 Meta/CMake/all_the_debug_macros.cmake。CMake 缓存操作三种方式——cmake path/to/binary/dir -DVARValue、ccmake、cmake-gui布尔选项以ON/OFF切换例如cmake -B Build/x86_64 -DPROCESS_DEBUGON。SuperBuild 结构Serenity 用宿主工具以 Serenity C 编写的 Lagom生成目标构建的代码与数据。Meta/serenity.sh run等价于配置Meta/CMake/Superbuild下的 superbuild 目录它通过 ExternalProject 分别驱动lagom宿主构建与主目标构建再执行cmake --build Build/superbuild-x86_64与ninja -C Build/x86_64 setup-and-run。Lagom 的详细介绍见 Meta/Lagom/ReadMe.md。组件配置ninja configure-components依赖whiptail在newt/libnewt包中提供交互式界面选择构建类型与启停组件之后自动执行 CMake 重配置并清理旧产物。Clang 工具链运行 Toolchain/BuildClang.sh 构建 Clang 工具链注意用MAKEJOBS限制并行度以防机器卡死随后以SERENITY_TOOLCHAINClang或Meta/serenity.sh run x86_64 Clang使用该工具链还会产出 Serenity 感知的 clang-format / clang-tidy / clangdCLANG_ENABLE_CLANGDON可启用 clangd装入Toolchain/Local/clang/bin。运行环境VirtualBox、VMware、裸机与树莓派除 QEMU 外SerenityOS 还支持多种运行载体VirtualBoxVirtualBox.md 提供安装指引。文档索引对应的配图 VirtualBox_Creation_Reference.png 展示了创建虚拟机的参考界面虚拟机名、内存等配置项可作为实际操作时的对照。VMwareVMware.md。裸机BareMetalInstallation.md。树莓派RunningOnRaspberryPi.md。Spice 集成SpiceIntegration.md 说明 QEMU Spice 显示/输入后端的使用。SSH 服务SSHServer.md 讲解在系统内搭建 SSH 服务器该文件也位于 Documentation 目录下可一并阅读。运行测试宿主测试与目标测试RunningTests.md 系统介绍了 SerenityOS 的两类测试宿主测试Host Tests通过 Lagom 在构建机上以宿主平台编译 SerenityOS 用户态库并运行。两种构建方式完整构建传-DBUILD_LAGOMON如cmake -GNinja -S Meta/CMake/Superbuild -B Build/superbuild-x86_64 -DBUILD_LAGOMON或仅 Lagom 构建cmake -GNinja -S Meta/Lagom -B Build/lagom -DBUILD_LAGOMON。随后ninjaninja test即可test-js在非 SerenityOS 宿主上需设置SERENITY_SOURCE_DIR指向仓库根。失败时建议用CTEST_OUTPUT_ON_FAILURE1 ninja test或ctest --output-on-failure查看输出。Sanitizer 支持CI 使用 AddressSanitizer 与 UndefinedSanitizer通过-DENABLE_ADDRESS_SANITIZERON -DENABLE_UNDEFINED_SANITIZERON启用可用UBSAN_OPTIONShalt_on_error1让 UB 错误直接判定失败。注意 sanitizer 构建显著更慢且会干扰ccache。目标测试Target Tests测试安装到系统的/usr/Tests或/bin。构建并启动镜像后在系统内运行/home/anon/Tests/run-tests-and-shutdown.sh设置$DO_SHUTDOWN_AFTER_TESTS会在测试后执行shutdown -n。CI 的 self-test 模式由 /etc/SystemServer.ini 中的TestRunnerttyS0条目Executable/home/anon/Tests/run-tests-and-shutdown.sh、StdIO/dev/ttyS0、SystemModesself-test等驱动通过export SERENITY_RUNci与export SERENITY_KERNEL_CMDLINEgraphics_subsystem_modeoff system_modeself-test可本地复现 CI 的自测启动流程。对照 Meta/serenity.sh 的test命令实现可确认这一流程正是脚本所做的。故障排查与性能调优Troubleshooting.md 针对构建与运行两个阶段给出了高频问题解法构建问题CMake 过旧需 ≥ 3.16QEMU 缺失或过旧qemu-system-i386 -version可用 Toolchain/BuildQemu.sh 自行构建工具链过期构建会打印如GNU version (13.1.0) does not match expected compiler version (13.2.0)运行Meta/serenity.sh rebuild-toolchain x86_64若 CMake 缓存了旧版本信息则用Meta/serenity.sh rebuild x86_64从干净构建目录重来GCC 过旧需 ≥ 14或通过cmake -DCMAKE_C_COMPILERgcc-14 -DCMAKE_CXX_COMPILERg-14指定编译器名OpenSSL 旧版重协商被禁用时需在/etc/ssl/openssl.cnf配置MinProtocol TLSv1.2、CipherString DEFAULTSECLEVEL1、Options UnsafeLegacyRenegotiation。运行问题Linux 下 KVM 可显著提速脚本检测/dev/kvm可用即自动启用HiDPI 慢启动、Kernel Image too big for memory slot、Your computer does not support long mode、does not support PAE、KVM doesnt support guest debugging可升级内核到 5.10 或设SERENITY_DISABLE_GDB_SOCKET1等均有对应处理方式。编辑器与语言服务器配置无论用哪种编辑器都建议先读基础构建文档。官方为以下编辑器/工具提供了专属配置指南均位于 Documentation 目录ClangdConfiguration.md所有编辑器通用CLionConfiguration.md附带 CLionCodeStyleSettings.xml 代码风格文件EmacsConfiguration.mdHelixConfiguration.mdNvimConfiguration.mdQtCreatorConfiguration.mdVimConfiguration.mdVSCodeConfiguration.md开发规范与核心设计文档贡献与编码风格贡献指南CONTRIBUTING.md位于仓库根目录文档索引以../CONTRIBUTING.md相对引用实际从仓库根出发即该文件。编码风格CodingStyle.md。通用模式Patterns.md。UI 文本规范HumanInterfaceGuidelines/Text.mdHuman Interface Guidelines 子目录位于 Documentation/HumanInterfaceGuidelines。手册页编写WritingManPages.md。核心运行时设计EventLoopEventLoop.md对应 Userland/Libraries/LibCore/EventLoop 等实现。High DPIHighDPI.md。智能指针SmartPointers.md仓库中OwnPtr、RefPtr、WeakPtr、NonnullRefPtr等实现在 AK/。字符串格式化StringFormatting.md配合 AK/Format.h 与 AK/String.h 阅读更佳。从 Serenity 导出文件TransferringFiles.md。文件与数据格式man5/man4 手册文档索引指向的格式手册位于 Base/usr/share/man/man5 与 Base/usr/share/man/man4覆盖应用文件.afBase/usr/share/man/man5/af.md位图字体.fontBase/usr/share/man/man5/font.md剪贴板数据Base/usr/share/man/man5/clipboard.md拖放数据Base/usr/share/man/man5/drag-and-drop.mdGUI 标记语言.gmlBase/usr/share/man/man5/GML.md其子目录 Base/usr/share/man/man5/GML 还细分了语法、布局、各控件Button、Label、TextEditor 等的用法HackStudio 创建后脚本.postcreateBase/usr/share/man/man5/postcreate.mdIPC 协议.ipcBase/usr/share/man/man4/ipc.md浏览器 / LibWeb 专题文档为 Ladybird 浏览器与 LibWeb 引擎单列了一组主题子目录 Documentation/BrowserLadybird 构建BuildInstructionsLadybird.md配合 Ladybird/ 目录下的 Qt 与 AppKit 实现。进程架构Browser/ProcessArchitecture.md。从加载到绘制Browser/LibWebFromLoadingToPainting.md。新增 IDL 文件Browser/AddNewIDLFile.md。LibWeb 代码风格Browser/Patterns.md。CSS 生成文件Browser/CSSGeneratedFiles.md。内核专题内核相关文档位于 Documentation/Kernel覆盖硬件与子系统实现细节AHCILocking.mdProcFSIndexing.mdRAMFS.mdIOWindow.mdGraphicsSubsystem.mdDevelopmentGuidelines.md内核源码主体在 Kernel/ 目录其中 Kernel/FileSystem、Kernel/Bus、Kernel/Devices 等子目录与上述文档一一对应可作为阅读时的源码参照。架构移植RISC-VRISC-V.md 介绍了 SerenityOS 向 RISC-V 架构移植的现状与构建方法与 Meta/serenity.sh 中支持的riscv64目标及SERENITY_ARCHriscv64用法相互印证。应用程序文档系统内所有应用程序与工具的手册页统一托管于 man pages 站点文档原文指向 https://man.serenityos.org/同时仓库内 Base/usr/share/man 保留了对应手册源文件可直接本地查阅。常用系统组件手册还包括 Base/usr/share/man/man5/SystemServer.md、Base/usr/share/man/man5/Shell.md、Base/usr/share/man/man5/Network.md 等。常见问题速览FAQ.md 澄清了几个关键认知项目没有预编译 ISO 镜像面向的是从源码构建的技术用户没有二进制包管理器第三方软件一律以 Ports 目录下的 port 形式从源码编译且 ABI 无稳定性保证git pull后构建失败通常是工具链需要重建CI 通过则本地也应可通过项目坚持自行实现而非引入现成库以最大化可篡改性hackability与乐趣MP3 相关专利已于 2017 年前后全部到期因此仓库内可以以 2-clause BSD 许可实现 MP3而 H.264/H.265、JPEG 2000 等仍可能受专利覆盖故不在 monorepo 中实现只能通过 ffmpeg 等第三方 ports 获得。写在最后如何规划你的 SerenityOS 学习路线综合文档索引可以归纳出一条推荐的进阶路径先读BuildInstructions.md用Meta/serenity.sh run跑通首个 QEMU 实例按需深入需要定制镜像、切换架构或调试宏时查 AdvancedBuildInstructions.md构建或运行报错时查 Troubleshooting.md跑测试按 RunningTests.md 理解宿主/目标两类测试并验证自己的改动写代码前按 CodingStyle.md、Patterns.md 与对应编辑器配置文档武装开发环境钻研子系统按主题进入 Documentation/BrowserLibWeb/Ladybird或 Documentation/Kernel内核深入源码。各文档均以仓库根目录起算的相对路径给出可随时在仓库内直接打开对应文件继续阅读。【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考