企业官网建设流程全解析

Spinel 部署指南：5 步构建、安装与发布原生 Ruby 应用的完整教程

【免费下载链接】spinelRuby AOT compiler项目地址: https://gitcode.com/gh_mirrors/spin/spinel

🎯一分钟了解：Spinel 是一个Ruby AOT（提前编译）编译器，能把 Ruby 源码直接编译成独立原生可执行文件，生成的二进制不依赖 Ruby 运行时，启动仅需约 0.8 毫秒，基准测试中几何平均比启用 YJIT 的 CRuby 快约8.5 倍。本指南带你完成 Spinel 的构建、安装、发行与发布全流程。

为什么选择 Spinel？

Spinel 的核心价值可以概括为一句话：编译一次，随处分发原生二进制。

• 🚀性能：全程序类型推断 + 生成优化的 C 代码，递归 fib 快 44 倍、矩阵乘法快 33 倍（见 README.md 中的基准表）
• 📦零依赖分发：生成程序只需 libc + libm，目标机器无需安装 Ruby
• 🧩整包发行：依赖库（spin packages）的源码连同.c文件一起被编译进二进制
• 🎛双工具：spinel是 gcc 风格的单文件编译器，spin是 cargo 风格的项目管理器

编译流水线一览（源自 README.md）：

Ruby (.rb) → 解析 (libprism) → 全程序类型推断 (analyze) → C 代码生成 (codegen) → cc -O2 → 原生二进制

部署前准备：环境要求

Spinel 是一个自包含的单 C 二进制编译器，构建与运行都不需要安装 CRuby（CRuby 仅用于测试时做输出对照）。你只需要：

📌平台支持（详见 docs/portability.md）：

• ✅ Linux（x86-64、arm64）：gcc / clang
• ✅ macOS（Intel、Apple Silicon）：clang
• 🔄 *BSD：预期可用
• 🪟 Windows：请通过 WSL 使用（按 Linux 工具链构建）

第一步：构建 Spinel（make 三连）

克隆源码仓库（仓库地址：https://gitcode.com/gh_mirrors/spin/spinel），然后执行经典三步：

make deps # 拉取 libprism 等 vendored 依赖（一次性） make # 构建 spinel 编译器 + spin 项目工具 make test # 可选：运行 3600+ 特性测试（以 CRuby 为基准对照）

构建完成后会得到 bin/spinel 编译器本体，以及 tools/spin.rb 编译出的spin项目工具。常用构建目标一览：

• make bench— 与 CRuby 对比跑基准
• make clean— 清理构建产物
• make dist— 生成离线可构建的发行源码包spinel-<release>.tar.xz（内含 vendored 解析器，make一条命令即可离线构建）

💡 发行包采用日期标签命名（YYYY.MM.DD），spinel --version会显示所属版本、构建修订号与 C 编译器信息，例如spinel 2026.09.12 (112bae85) [gcc 13.3.0]。

第二步：安装到系统

构建成功后，一条命令即可完成系统级安装：

sudo make install # 安装到 /usr/local sudo make install PREFIX=~/.local # 或自定义前缀（无需 root）

make install会做这些事（见 Makefile 的 install 目标）：

1. 将spinel、spin、spinel_rbs_extract安装到<PREFIX>/lib/spinel/
2. 安装运行时库libspinel_rt.a（含单线程与线程两个版本）及全部头文件
3. 复制内置包packages/与 Ruby 核心方法builtins/
4. 在<PREFIX>/bin/创建spinel、spin及spinel-doctor、spinel-reduce等配套工具

卸载同样简单：make uninstall（记得带上相同的PREFIX）。

第三步：编译你的第一个原生二进制

对于单文件脚本，直接调用编译器即可——像用 gcc 一样简单：

./spinel app.rb # 编译生成 ./app 原生二进制 ./spinel app.rb -o myapp # 指定输出名 ./spinel app.rb -c # 只生成 C 源码（不编译） ./spinel app.rb -S # 把生成的 C 打印到标准输出

生成的二进制是完全独立的：无 Ruby 解释器、无链式辅助程序，可直接部署到任意同平台机器。更多命令行选项（如--rbs DIR类型种子、--int-overflow=wrap|raise|promote整数溢出策略）参见 README.md 的 "Single files" 一节。

第四步：用 spin 管理完整项目

当项目长大时，切换到spin项目工具（完整指南见 docs/spin.md）——它负责脚手架、依赖解析、驱动编译，你再也不用手写 Makefile：

spin new myapp # 脚手架：spin.toml + bin/myapp.rb + test/ cd myapp spin run # 编译并运行 bin/myapp.rb spin add hello --version "~> 1.1" # 从索引添加依赖 spin add mylib --path ../mylib # 或本地路径 / git 仓库 spin test # 快照测试（CRuby 为对照基准） spin build && ./build/bin/myapp # 构建最终二进制

项目结构（按扩展名参与构建，无需清单枚举）：

myapp/ spin.toml # 清单（名称、依赖） bin/myapp.rb # 每个 bin/*.rb 都是可执行入口 test/ # 每个 test/*.rb 都是快照测试 build/ # 可丢弃输出（spin clean 清理）

✅测试哲学：spin test采用快照对比——有.expected文件则比对输出，没有则在 CRuby 下跑同一文件直接 diff，天然兼作 CRuby 行为一致性检查。

第五步：发行与发布（Publishing）

发布库到 spin 包索引

如果你的项目是库，一条命令即可发布版本（见 docs/spin.md）：

spin publish

它会依次完成：校验版本（已提交、[package] name/version齐全）→强制运行spin test作为硬门槛→ 提交[[release]]条目（锁定完整 commit SHA）到索引。之后任何人都可以spin add mylib --version "~> 0.1"使用你的库。注意：一个版本只有一种写法（0.1与0.1.0视为同一版本，避免索引分裂）。

分发免编译器的源码包

spin pack会打出一个只需 C 编译器 + make的目录，接收方无需安装 spinel：

spin pack # 生成含生成 C 源码、运行时源码、依赖 C 源码和 Makefile 的目录

目标机器上make一下即得同样二进制。运行时以源码而非预编译库的形式随行，保证跨平台交叉构建的一致性。

发布编译器版本

官方发行以日期 tag（YYYY.MM.DD）为标记，make dist产出的 tarball 附带 vendored 解析器，无网络也能构建——这是发布 Spinel 本体的标准方式。

进阶：跨目标发行（WebAssembly）

除了本机原生二进制，Spinel 还支持把 Ruby 程序发行到浏览器 / Node / wasmtime：

spinel --target=wasm32-wasi app.rb # 生成 app.wasm wasmtime run app.wasm

需要 wasi-sdk（≥34）并先执行make wasm-rt构建目标运行时。注意 wasm32 目标下Integer为 32 位，且不支持Thread/Fiber，详见 docs/wasm.md。

常见问题（FAQ）

Q1：需要预装 Ruby 才能构建吗？不需要。CRuby 只在测试框架中作对照基准；构建与生成程序都只依赖 C 工具链。

Q2：gem install spinel为什么不存在？Spinel 以源码形式发行（make/make dist包），不走 RubyGems 分发渠道。

Q3：哪些 Ruby 特性不能用？AOT 模型下eval、method_missing、运行时define_method等动态元编程不支持；完整清单见 docs/limitations.md。

Q4：CI 里如何保证质量？make gate一次性跑完 test + bench + optcarrot 集成测试；spinel diff app.rb可直接对比 CRuby 与 Spinel 的输出差异，是提交 bug 报告的最佳起手式。

总结：部署路线一图流

📚延伸阅读：docs/README.md 文档总目录、docs/FFI.md 直接调用 C 函数、docs/thread.md 无 GVL 线程模型、docs/int-overflow.md 整数溢出策略。

现在就去构建你的第一个原生 Ruby 应用吧！从make到spin publish，Spinel 让 Ruby 应用像 C 程序一样被分发和部署。

【免费下载链接】spinelRuby AOT compiler项目地址: https://gitcode.com/gh_mirrors/spin/spinel