安装与使用文档

从空白系统到可自我演进的发行版,完整记录 OkraLinux 的自举流程与包管理用法。

概览

OkraLinux 是一个面向现代硬件和 LiveCD 场景的 Linux 操作系统项目。我们将内核、用户态包管理器和系统镜像构建拆分为独立项目,以保持清晰的依赖关系和可维护的开发边界。

本文档给出一条从空白系统逐步自举、最终可自我演进的完整路径。

整个项目由三部分组成:

  • KERNEL——基于 Linux 7.2,负责内核本身、OkraPM 内核接口和真正的内核模块、LiveCD 所需的内核配置,以及内核构建和启动相关能力。
  • okrapm——负责用户态软件包管理能力,包含 Lunar 包管理器、OAA 包格式和工具、OPSIS 安装脚本,以及仓库同步、解析和事务管理。
  • okra-linux(仓库尚未公开)——负责系统集成和发行介质,包含 rootfs 构建脚本、系统配置和 systemd 服务、LiveCD 与安装镜像生成,以及软件包清单和发行版默认内容。
关于 OAA OAA 即 Okra Application Artifact,是基于 tar 归档的应用包格式。此外还有传统的 .okra 包格式,两者可通过相同入口安装。
关于自举工具包 bootstrap-toolkit 是自举体系的总入口,收录包管理工具链、构建脚本与基础 OAA 软件包,用于在 aarch64 环境把一个空白系统逐步拉起为可自我演进的发行版。

架构与平台

组织公开资料中,自举工具包的定位是在 aarch64 环境把一个空白系统逐步拉起为可自我演进的发行版。当前 GitHub 上公开发布的基础 OAA 包,其仓库描述均标注为 aarch64。

架构 典型平台 公开 OAA 包
aarch64 ARM 服务器、单板计算机 已发布
x86_64 Intel / AMD 桌面与服务器 —
安装前请确认架构 请以对应仓库 Release 页面实际提供的附件为准。若目标架构暂无构建产物,该包无法直接安装。

自举流程

bootstrap-toolkit 仓库是 OkraLinux 自举体系的总入口,用于在一个空白系统上,逐步把发行版拉起为可自我演进的状态。

仓库地图

各组件的最新版本与职责如下:

组件 版本 说明
glibc 2.43 系统基座,所有动态程序都依赖它,必须最先安装
gcc 16.2.0 r2 自托管编译器,使用 OkraLinux glibc 构建,已完成自举闭环
make 4.4.1 构建工具,位于自举仓库的 oaa 目录内,无独立仓库
coreutils 9.6 一百零六个基础命令,文件与文本操作
bash 5.2.37 系统默认 shell
KERNEL Linux 7.2 Linux 内核、OkraPM 内核接口和真正的内核模块、LiveCD 所需的内核配置
okrapm — Lunar 包管理器、OAA 包格式和工具、OPSIS 安装脚本、仓库同步和事务管理
okra-linux — rootfs 构建、系统配置、systemd 服务、LiveCD/安装镜像生成和软件包清单

依赖顺序与构建顺序

  • 安装顺序:glibc 优先,其次 gcc;之后的 make、bash、coreutils 可任意顺序安装。
  • 构建顺序:若要从零重新编译,全部按上述顺序执行。每个 OAA 仓库内的 scripts 目录含对应构建脚本。

操作步骤

  1. 在目标系统安装工具链

    将 tools 目录内的文件复制到 /usr/bin 与 /usr/lib/okrapm,并赋予执行权限。

  2. 下载所需 OAA 包

    从各仓库的 Release 页面下载对应的 OAA 包。

  3. 依次安装基础组件

    glibc 先行,然后安装 gcc、make、bash、coreutils。

  4. 验证安装结果

    以下命令均应正常输出版本信息:

    bash
    gcc --version
    make --version
    bash --version
    ls
  5. 验证自举能力

    用安装好的 gcc 与 make 重新编译 GCC 自身源码。若能成功,即证明系统已具备自托管能力。详细命令见仓库的 docs 目录。

proot 环境注意事项

硬链接显示异常属正常现象 在 proot 容器内构建时,硬链接会显示为以 .l2s 开头的特殊链接文件。所有构建脚本已内置清理逻辑,直接运行即可,无需手动干预。

安全校验

所有 Release 附件均附带 sha256 校验文件。下载后务必执行校验:

bash
sha256sum -c package.oaa.sha256

OkraPM / Lunar

OkraPM 是 Okra Rolling Linux 的用户态软件包管理工具链,提供三个部分:

  • lunar:依赖解析、事务安装、软件仓库同步和系统升级。
  • oaa:OAA 包的构建、校验和安装入口。
  • .oaa、.okra:基于 tar 归档的应用包和传统 Okra 包格式。

从源码构建

依赖 CMake 3.16 或更高版本、C++17 编译器,以及系统 tar 工具。

bash
cmake -S . -B build
cmake --build build -j2
ctest --test-dir build --output-on-failure

构建完成后,Lunar 可执行文件位于 build/src/lunar/lunar。

OAA Shell 工具不需要编译,可直接从 oaatools/oaatools 使用,或安装到系统:

bash
make -C oaatools
sudo make -C oaatools install

安装后提供 oaa 命令,并将工具安装到 /usr/bin 和 /usr/lib/okrapm。

OAA 包格式

OAA 包通常使用以下目录布局:

text
package/
├── meta.yaml
├── rootfs/
│   ├── usr/bin/
│   └── etc/
└── scripts/
    ├── pre-install
    └── post-install

校验与安装

校验 OAA 包:

bash
oaa verify package.oaa

校验内容包含三项:

  1. .sha256 sidecar 文件(如果存在);
  2. meta.yaml 中的 checksum 字段(如果存在);
  3. tar 归档是否可以正常读取。

也可以使用 Lunar 执行同样的校验:

bash
lunar verify package.oaa

安装本地包:

bash
oaa install package.oaa
冲突保护 本地包安装会执行 SHA256 校验,并检查 payload 中的文件是否已存在。检测到文件冲突时安装会失败,不会覆盖已有文件。

传统 .okra 包也可以通过相同入口安装:

bash
lunar install package.okra

非 root 环境下,安装文件默认写入 Lunar 数据目录的 rootfs/ 子目录。可使用环境变量指定安装根目录:

bash
LUNAR_INSTALL_ROOT=/tmp/rootfs lunar install package.oaa

卸载

bash
oaa remove package-name
lunar remove package-name

卸载操作会更新 Lunar 系统状态。若安装事务失败,已写入的本地文件会被删除,系统状态也不会提交。

事务与回滚

Lunar 会从本地或远程仓库解析依赖,并按依赖顺序生成事务计划。安装、删除和升级都会经过事务提交;提交前自动创建系统快照。

预览事务而不执行:

bash
lunar plan install package-name
lunar plan remove package-name
lunar plan update

查看已安装软件:

bash
lunar list
lunar status
lunar info package-name

管理快照:

bash
lunar snapshot list
lunar snapshot create "before upgrade"
lunar rollback <snapshot-id>

软件仓库

同步所有已配置仓库:

bash
lunar sync

仓库管理:

bash
lunar repo list
lunar repo add <name> <url>
lunar repo enable <name>
lunar repo disable <name>
lunar repo remove <name>

本地仓库和远程仓库都由 Lunar 管理。远程仓库同步后,包元数据即可用于搜索、依赖解析和安装。

更新与系统升级

滚动更新已安装软件:

bash
lunar update

升级指定软件:

bash
lunar update package-name

系统基线升级命令为:

bash
lunar upgradle okra.systemversion
注意命令拼写 upgrade 是常见的使用习惯写法;当前的正式命令名为 upgradle。

OAA 工具命令

bash
oaa new <directory>
oaa build <directory> -o package.oaa
oaa inspect package.oaa
oaa list package.oaa
oaa extract package.oaa <destination>
oaa sha256 package.oaa
oaa verify package.oaa

使用 oaa install 和 oaa remove 时,工具默认查找 lunar。如果 Lunar 不在 PATH 中,可以指定路径:

bash
LUNAR_BIN=/path/to/lunar oaa install package.oaa

数据目录

默认 Lunar 数据目录为 /var/lib/lunar。开发和测试时可使用:

bash
LUNAR_DATA_DIR=/tmp/lunar lunar list

也可以通过命令行指定:

bash
lunar --root /tmp/lunar status

数据目录主要包含:

路径 用途
system.db 已安装对象和系统状态
repos/ 本地仓库数据
cache/downloads/ 下载缓存
snapshots/ 系统快照
rootfs/ 非 root 环境下的本地安装根目录

相关组件

组件 路径
C++ 核心库 lib/okrapmlib/
Lunar CLI src/lunar/
OAA 工具链 oaatools/
综合测试 tests/test_all.cpp