HAX-Compile

HBOS（HeBitOS）HAX 编译产物仓库：存放编译好的 .hax 应用程序，以及配套的 HPT 软件仓库（Packages 索引 + pool/ 载荷）， 并附带完整的构建与使用教程。

HAX（HBOS Application eXecutable，扩展名 .hax）是 HBOS 的应用程序格式： 一个带 .haxmeta 自描述元数据的标准 ELF64 用户态程序。本仓库解决"编译好的 应用放哪、怎么装进 HBOS"的问题——源码在 HBOS 与 HIVE 仓库，这里发布二进制。

目录结构

HAX-Compile/
├── bin/                 编译好的 .hax 程序（每包一个，可直接分发/下载）
├── repo/                HPT 软件仓库（供 HBOS 里的 hpt 客户端使用）
│   ├── Packages         包索引：name|version|arch|size|sha256|file|depends|desc
│   └── pool/            <name>_<version>_<arch>.hax 载荷
├── manifest.json        包清单（新增/修改包先改这里）
├── Makefile             收集、生成仓库、校验、从源码重建、上传部署
├── scripts/             setup-server.sh（服务器一次性安装）与 deploy.sh（上传）
└── tools/               hpt_repo.py（索引生成器）与 verify_repo.py（校验）

当前包含 13 个包（架构 x86_64）：calc、clock、files、hexview、 hpt、imgview、settings、shortcuts、taskmgr、tui、wdemo、 widgets（来自 HIVE），以及 leapyear（HBOS 核心的多文件应用示例）。

在 HBOS 中安装使用

1. 在宿主机托管本仓库

任选一种方式，把 repo/ 目录通过 HTTP 暴露出来：

# 方式 A：用 HPT-server（推荐，支持 HTTPS）
git clone https://github.com/HeBitOS/HPT-server
make -C HPT-server
HPT-server/build/hpt-server --root repo --bind 0.0.0.0 --port 8080

# 方式 B：python 自带静态服务器（仅 HTTP，最简单）
python3 -m http.server 8080 --directory repo

2. 在 HBOS 里配置源并安装

在 HBOS 的终端（或图形桌面的终端窗口）中执行（假设宿主机 IP 是 10.0.2.2， 即 QEMU 默认网关）：

run hpt init
run hpt source http 10.0.2.2 8080 /
run hpt update
run hpt search calc          # 搜索
run hpt install calc         # 安装
run hpt list --installed     # 查看已安装
run hpt verify               # 校验所有已安装包
run hpt run calc             # 运行

HTTPS 源需要先安装 CA 证书（HPT-server 用自有证书时）：

run hpt ca /packages/hpt-root-ca.pem
run hpt source https repo.example 8443 /
run hpt update

说明：hpt install 会把包安装到 HBOS 的 /bin/<name>，之后直接 run calc 或从桌面启动器点击即可。包安装前会强制校验 SHA-256 与大小， 索引与载荷不一致会拒绝安装。

3. 不通过 HPT，直接加载 .hax

把 bin/<name>.hax 拷进 HBOS 的 /bin（例如通过 fat32-copy 或 HBFS 工具），run <name> 即可运行；GUI 类应用会出现在桌面启动器。

从源码重新构建

本仓库默认只收集已编译产物，不依赖源码树。要从源码重新编译全部应用：

# 前提：HBOS 与 HIVE 源码树就在旁边（../hbosv2 或 ../HBOS、../HIVE）
make build

# 只重新生成仓库索引（产物已存在时）
make repo

make build 等价于：

make -C ../hbosv2 hax-apps        # 编译 HBOS 核心应用（含多文件应用与库）
make -C ../hbosv2/HIVE repo       # 编译 HIVE 全部应用并生成 HIVE 仓库

默认 make 会依次执行：收集 bin/ → 生成 repo/ → 校验。

新增一个包

1. 在 HBOS 或 HIVE 的 app/ 下添加应用源码（支持单文件、多文件目录、 独立库三种结构，见下节），构建出 <name>.hax。
2. 在 manifest.json 的 packages 里追加一行：

   {"name": "myapp", "version": "0.1.0", "depends": [], "description": "我的应用"}

   （depends 填依赖的包名，如 ["libfoo"]；描述不能含 | 和换行。）
3. 重新收集并生成仓库：

   make

4. make verify 通过后提交 bin/、repo/ 与 manifest.json。

约束：包名必须与 .hax 内 .haxmeta 段的应用名一致（HAX_APP("myapp", ...) 宏声明），否则 hpt_repo.py 会拒绝生成索引。载荷上限 2 MiB。

多结构 HAX 应用（构建系统支持）

从 HBOS 的多结构构建改造起，HAX 应用不再局限于单个 .c 文件。app/ 下支持 三种结构（详见 HBOS 仓库的 Makefile）：

app/<name>.c         单文件应用（原有方式，向后兼容）
app/<name>/          多文件应用：目录内全部 *.c 编译后链接为一个 <name>.hax
app/lib/<lib>/       独立库：编译一次为 build/app/lib/<lib>.o，可被多个应用共享

库依赖通过 deps 文件声明（每行一个库名，# 为注释）：

app/<name>.c   → 同名 app/<name>.deps
app/<name>/    → app/<name>/deps
app/lib/<lib>/ → app/lib/<lib>/deps（库之间的依赖）

库头文件放在 app/lib/<lib>/ 下，源码里 #include <lib/xxx.h> 引入； HAX_APP(...) 元数据声明每个应用只能出现一次（惯例放在 main.c）。 本仓库里的 leapyear 就是多文件 + 独立库的示例：

app/leapyear/main.c   入口与主循环（含 HAX_APP 声明）
app/leapyear/leap.c   第二翻译单元：输入解析
app/leapyear/deps     声明依赖独立库 leaputil
app/lib/leaputil/     独立库：闰年判定（可被其他应用复用）

上传到服务器（自建 HPT 软件源，已选定方案）

方案已选定：自建 hpt-server，跑在自己的 E5 服务器上（与 OJ 等共用一台， 建议给 HPT 源单独一个端口，默认 8080）。

一次性安装（服务器上执行）

# 在你的 E5 服务器（root 身份）克隆脚本并运行：
ssh root@e5.example.com
git clone https://github.com/HeBitOS/HAX-Compile
cd HAX-Compile
sudo bash scripts/setup-server.sh            # 默认 /srv/hpt-repo，端口 8080
# 或按需：ROOT_DIR=/var/www/hpt PORT=8888 sudo bash scripts/setup-server.sh

脚本会：安装 build-essential pkg-config libssl-dev git curl → 编译并 make install 安装 HPT-server 到 /usr/local/bin → 创建仓库目录 → 注册并启动 systemd 服务 hpt-server → 健康检查。

每次更新（本机 HAX-Compile 里执行）

make deploy DEPLOY_HOST=root@e5.example.com
# 可选：REMOTE_ROOT=/var/www/hpt PORT=8888

流程：本机 make repo 生成最新索引 → rsync 增量上传 repo/ → 重启服务器上的 hpt-server 服务 → curl /healthz 健康检查。本地无服务器时可先 make deploy（不带 DEPLOY_HOST）进入本地测试模式，或 make serve 临时托管。

HBOS 侧配置软件源

run hpt init
run hpt source http 10.0.2.2 8080 /     # 或你的服务器公网 IP
run hpt update
run hpt search calc
run hpt install calc
run hpt run calc

HTTPS 源：HPT-server 支持 --cert/--key（自有 CA），HBOS 侧需先 run hpt ca /packages/hpt-root-ca.pem 安装根证书。第一版推荐先走 HTTP。

与 OJ 共用一台服务器的注意点：端口不要冲突（HPT 默认 8080）；若 OJ 也占 80/443，可把 HPT 源放到独立端口，或在 nginx 里按路径反代 repo/。

校验

make verify

校验内容：manifest 合法性（hpt_repo.py check）+ repo/Packages 中每个载荷的 存在性、大小与 SHA-256 一致性（tools/verify_repo.py）。

许可

本仓库遵循 GNU General Public License v3.0。编译产物来自 HBOS 与 HIVE， 两者同为 GPL-3.0。