PPysolate SpineREAD THE CODE · UNDERSTAND THE SYSTEM
课程与章节
IMPLEMENTATION / 14

构建与来源

实际 Wasm 的打包边界与使用条件。

本章目录

若编译、链接、静态库或环境变量还陌生，先读 程序怎样运行 与 工程基础。

想先理解 WSL、交叉编译、静态库、缓存和网络隔离，读 Ubuntu 构建与离线演示教学。本页保留操作步骤与来源说明。

Clone 后直接运行

仓库附带 artifacts/guest/spine.wasm.gz 与校验清单。Go 1.25+、Python 3.9+ 和 Git 就能开始：

make setup
make check
make check-all
make bench-analyze

make setup 只校验并解压本地文件，不下载或编译 CPython。Go 依赖首次安装仍需联网。内存实测入口 make bench-smoke 和 make bench-full 需要 Linux；实验源码、补丁、Guest 变体和历史记录见 实验目录。

Ubuntu 本机开发

开发与演示以 Linux x86_64 为目标。Guest 构建不需要旧 runtime 仓库、远程构建主机或容器。

准备 Go 1.25+、Python 3.11+、C 编译器、make、curl、tar、unzip。站点另需 Node 与 pnpm。脚本不调用 sudo，也不自动改系统配置。

在仓库根目录执行：

# 首次联网准备：下载锁定版本工具，编译 CPython 的 Host 构建解释器和 WASI 静态库。
make setup-build

# 用本仓库当前的 C bridge、Python bootstrap/pass 生成真正使用的 artifact。
make guest

make explain
make prepared

tools/build-inputs.lock.json 固定 CPython 3.14.0、WASI SDK 33.0、wasmtime、wasm-tools 和 wasi-vfs 的下载来源与 SHA-256。校验发生在获取外部构建输入时，不是请求热路径的 hash/receipt 管线。

tools/setup-build-inputs.py 默认把工具、源码和中间产物放在 Git 忽略的 build/inputs/。重复执行会复用下载和已有编译产物。SPINE_BUILD_INPUTS 可指定其他目录；构建和重建时必须指向同一目录。SPINE_BUILD_JOBS 默认 6，限制构建进程可用的逻辑 CPU 范围。上游构建驱动仍可能启动更多 make worker，不应把这个值理解成 worker 数量。

该流程已在 Ubuntu WSL2 完成源码编译、Guest 链接与真实 PLM/prepared-copy 演示。它不是完整桌面 CPython 发行版：当前 WASI 构建不提供 SSL、ctypes、SQLite 等可选模块，也不给 Guest 宿主网络或进程权限。

改什么，需要重建什么？

  • 改 Go runner、Host 工具或 demo：直接 go run / 目标 go test。
  • 改 examples/*.py：换程序输入，不用重建 Guest。
  • 改 guest/bootstrap.py、guest/plm.py、guest/prefix.py 或 guest/runtime.c：必须 make guest，再跑相关真实 Guest 测试。
  • 改 CPython 本身或工具链版本：才需要重新准备 CPython 构建输入。

日常 make guest 复用静态库，只编译 C bridge、链接和打包当前 Python 源码。无需再次从零编译 CPython，也不下载东西。输出固定为 dist/spine.wasm。构建失败就是失败，不能继续把旧 artifact 的结果当成新源码验证。

正式演示前的离线准备

先在联网环境下载 Go 模块与站点依赖：

go mod download
(cd site && pnpm install --frozen-lockfile)

# 快速检查 namespace 权限，不跑全套。
bash tools/offline-check.sh --probe-only

# 若现场可能改 Guest，可单独确认重建也能断网完成。
unshare --user --map-root-user --net make guest

# 最后统一验收：真实 Guest 测试、Python 单测、go vet、站点构建与演示。
make offline

Linux 用 unshare 创建仅属于该子进程及其后代的 user/network namespace，不改变主机网络。脚本先在隔离域内尝试连接固定 IP，要求内核返回 ENETUNREACH，再在同一隔离域运行检查。仅设置 GOPROXY=off 不算断网证明。

如果系统禁止非特权 user namespace，命令会明确失败，不回退成联网测试，也不自动 sudo。需要管理员处理对应限制。当前 WSL 已允许此能力，不需要额外安装 bubblewrap。

make offline 包含 make check，不需要紧接着再跑一遍。维护者在 WSL 记录过全套约 88 秒；开发中先跑修改点对应测试，收尾再跑全套。这个时间不是性能承诺。

macOS 原有 sandbox-exec 分支保留，但本轮开发与验收重点是 Ubuntu。

构建输入布局

build/inputs/
  tools/
    wasi-sdk/          clang、WASI sysroot 与链接器
    wasmtime/          CPython 交叉构建使用的 WASI 执行器
    wasi-vfs-lib/      libwasi_vfs.a
    wasi-vfs-cli/      文件系统打包器
    wasm-tools/        Wasm validator
  cpython/
    Include/          CPython C API 头文件
    Lib/              标准库源码
    cross-build/wasm32-wasip1/
      pyconfig.h
      libpython3.14.a
      Modules/...     mpdecimal、HACL、expat 静态库

CPython 的 WASI 配置禁用绝对 clock_nanosleep 路径，使用与 wazero 相容的相对睡眠路径。不继承旧项目的内部 import authority、certificate 或 receipt 机制。

历史上的 tools/rebuild-guest.py 是通过 SSH 同步、构建和取回的可选入口，依赖预先准备好的远程输入。Ubuntu 本机开发不需要它，也不应拿旧远程源码的构建结果验证当前 Guest 修改。

仓库与 artifact 边界

本项目从 interview worktree 的 spine/ 抽取，不继承旧 Git 历史、不 import 旧 runtime，保留原 MIT LICENSE。源码位于私有 GitHub 仓库；文档站只发布白名单文档与源码。

dist/spine.wasm、工具链和构建目录仍不进 Git。可直接使用的压缩 Guest、校验清单及许可存于 artifacts/guest/；实验专用源码快照与数据另存于 experiments/，均不随 Pages 上传。源码重建与使用已打包 artifact 是两条独立验证路径。

项目源码沿用 MIT。Guest 的 CPython、支持库与 wasi-vfs 许可随压缩产物保留；实验包也保留对应源码许可。具体版本和来源以各目录清单为准。