如何用 Spinel 把 Ruby 编译成 WebAssembly浏览器与 wasmtime 部署完整指南【免费下载链接】spinelRuby AOT compiler项目地址: https://gitcode.com/gh_mirrors/spin/spinelSpinel 是一款 Ruby AOT提前编译器可将 Ruby 源码编译为独立原生可执行文件并支持--targetwasm32-wasi目标把整个 Ruby 程序编译成标准 WebAssembly 模块直接在 wasmtime、Node 或支持 WASI 的浏览器中运行。本指南带你从零完成编译、运行和部署并详解 wasm32 目标下的关键限制。为什么选择 WebAssembly 目标Ruby 应用通常依赖解释器运行时而 Spinel 采用整程序类型推断 → 生成 C → 系统编译器链接的路线Ruby (.rb) → libprism 解析 → 全程序类型推断 → 生成 C → clang (wasi-sdk) → .wasm编译到 wasm 时编译器照常运行在宿主上输出的 C 代码由 wasi-sdk 的 clang 针对目标编译产出name.wasm模块。这意味着无需目标机器安装 Ruby模块只依赖 WASI 引擎冷启动极快编译产物是纯 Wasm秒级加载部署简单一个.wasm文件 一个引擎wasmtime / 浏览器即可交付。详细文档见 docs/wasm.md。快速上手三步编译出 .wasm1. 准备工具链依赖说明wasi-sdk34指向WASI_SDK环境变量默认安装路径/opt/wasi-sdkwasm 运行时归档执行make wasm-rt构建lib/wasm32-wasi/libspinel_rt.a支持异常处理的引擎wasmtime 48-W exceptionsy、当前 Chrome / Firefox / Safari / Node关键点Ruby 的raise/rescue底层是 C 的setjmp/longjmpwasi-sdk 会将其降级到 wasm 的标准化exnref异常指令上因此引擎必须实现该提案见 docs/wasm.md 第 23-29 行。2. 编译你的程序# 一次性构建 wasm 运行时归档默认不构建 make wasm-rt # 编译 Ruby 程序为 WebAssembly spinel --targetwasm32-wasi app.rb # 生成 app.wasm # 用 wasmtime 运行 wasmtime run -W exceptionsy app.wasm若只想要 C 中间产物或指定输出路径也可使用-c与-o参数。CI 中的完整验证流程可以参考 Makefile 里的wasm-test目标Makefile它对测试用例逐条执行spinel --targetwasm32-wasi编译再用 wasmtime 运行并与期望输出比对。3. 浏览器中运行生成的模块是标准 WASI preview 1 模块可在带 WASI shim 的浏览器中加载Node 则可直接用node:wasi模块托管。wasm32 目标下有什么不一样这是部署前必须了解的坑清单全部来自官方文档 docs/wasm.mdInteger 变成 32 位wasm32 指针是 32 位sp_int随指针宽度变化因此Integer 范围为-2**31 .. 2**31-12**40在默认--int-overflowraise下会抛RangeError超范围的字面量则自动成为 Bignum。同一份代码在 64 位宿主机上编译会得到 64 位 Integer——若你的测试假设了 64 位请在文件首行标注# spinel: int64。相关机制详见 docs/int-overflow.md。不支持 Fiber、Enumerator#next、Threadwasm 核心指令没有栈切换Fiber.new会抛FiberError依赖它的对象外部枚举器、Enumerator.newYielder同样失败。使用Thread、Mutex、Queue的程序会在编译期被拒绝——wasm 线程需要 SharedArrayBuffer 和带线程的运行时归档而当前均不提供。无进程、信号、域名解析WASI 没有这些能力fork、spawn、反引号、system、Process.kill、Socket.getaddrinfo等不会变成链接错误而是像 POSIX 上那样返回Errno::ENOSYS/Errno::ENOTSUP/SocketError。preview 1 中无法打开 socket文件 I/O 只在宿主授权的目录内工作wasmtime 用--dir.授权当前目录。其他运行约束栈主线程栈是 8 MB 线性内存wasmtime 另对模块帧的原生栈设 512 KB 上限深度递归的程序请wasmtime run -W max-wasm-stack16777216提高GC运行时 slab 分配器一次性占用 64 MB 线性内存且不归还wasm 内存只增不减超出后每块走malloc函数体大小引擎对单个函数体有上限wasmtime 约 7.6 MB。含rescue的大方法会把所有活跃局部变量存到内存超大顶层程序可能超限——把这类代码移入独立方法即可修复FFIWASI 无dlopenffi_lib绑定不到东西C 函数必须在模块内包自带的 C 或用同一 sdk 编译后用--link链接的对象。内部机制一览wasm 目标由几个关键部分组成源码位置如下组成位置作用WASI 垫片lib/wasi/补齐 wasi-libc 缺失的 POSIX 头文件sys/wait.h、netdb.h、ucontext.h等失败桩实现lib/wasi/sp_wasi.c定义以errno失败返回的调用目标选择src/main.c选定编译器、归档、仿真宏与 sjlj 参数--print-build可打印全部运行时归档Makefilewasm-rt目标编译lib/wasm32-wasi/libspinel_rt.a编译器会设置_WASI_EMULATED_SIGNAL、_WASI_EMULATED_MMAN等仿真宏并用-mllvm -wasm-enable-sjlj -mllvm -wasm-use-legacy-ehfalse完成异常降级。常见问题Q为什么make之后直接编译 wasm 会失败Awasm 运行时归档lib/wasm32-wasi/libspinel_rt.a和各包的sp_*_wasi.o默认不构建需要显式执行make wasm-rt。Q浏览器能跑吗A可以。当前 Chrome、Firefox、Safari 和 Node 均已实现exnref异常指令带 WASI shim 的浏览器可直接加载模块。Q多线程的 Ruby 服务能部署到 wasm 吗A目前不行。含Thread等并发原语的程序在编译期即被拒绝参见上文目标差异部分。总结用 Spinel 把 Ruby 应用带上 WebAssembly 只需三步装好 wasi-sdk →make wasm-rt→spinel --targetwasm32-wasi app.rb。部署目标覆盖 wasmtime、Node 和主流浏览器。记住三件事wasm32 下Integer 是 32 位、没有 Fiber/Thread、没有网络 socket——先对照 docs/limitations.md 检查你的程序再动手编译就能一次通过。完整特性清单与限制请阅读 docs/wasm.md 与 docs/limitations.md。【免费下载链接】spinelRuby AOT compiler项目地址: https://gitcode.com/gh_mirrors/spin/spinel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/8 6:54:54 · 阅读 1.2k 如何用 Spinel 把 Ruby 编译成 WebAssembly：浏览器与 wasmtime 部署完整指南
如何用 Spinel 把 Ruby 编译成 WebAssembly浏览器与 wasmtime 部署完整指南【免费下载链接】spinelRuby AOT compiler项目地址: https://gitcode.com/gh_mirrors/spin/spinelSpinel 是一款 Ruby AOT提前编译器可将 Ruby 源码编译为独立原生可执行文件并支持--targetwasm32-wasi目标把整个 Ruby 程序编译成标准 WebAssembly 模块直接在 wasmtime、Node 或支持 WASI 的浏览器中运行。本指南带你从零完成编译、运行和部署并详解 wasm32 目标下的关键限制。为什么选择 WebAssembly 目标Ruby 应用通常依赖解释器运行时而 Spinel 采用整程序类型推断 → 生成 C → 系统编译器链接的路线Ruby (.rb) → libprism 解析 → 全程序类型推断 → 生成 C → clang (wasi-sdk) → .wasm编译到 wasm 时编译器照常运行在宿主上输出的 C 代码由 wasi-sdk 的 clang 针对目标编译产出name.wasm模块。这意味着无需目标机器安装 Ruby模块只依赖 WASI 引擎冷启动极快编译产物是纯 Wasm秒级加载部署简单一个.wasm文件 一个引擎wasmtime / 浏览器即可交付。详细文档见 docs/wasm.md。快速上手三步编译出 .wasm1. 准备工具链依赖说明wasi-sdk34指向WASI_SDK环境变量默认安装路径/opt/wasi-sdkwasm 运行时归档执行make wasm-rt构建lib/wasm32-wasi/libspinel_rt.a支持异常处理的引擎wasmtime 48-W exceptionsy、当前 Chrome / Firefox / Safari / Node关键点Ruby 的raise/rescue底层是 C 的setjmp/longjmpwasi-sdk 会将其降级到 wasm 的标准化exnref异常指令上因此引擎必须实现该提案见 docs/wasm.md 第 23-29 行。2. 编译你的程序# 一次性构建 wasm 运行时归档默认不构建 make wasm-rt # 编译 Ruby 程序为 WebAssembly spinel --targetwasm32-wasi app.rb # 生成 app.wasm # 用 wasmtime 运行 wasmtime run -W exceptionsy app.wasm若只想要 C 中间产物或指定输出路径也可使用-c与-o参数。CI 中的完整验证流程可以参考 Makefile 里的wasm-test目标Makefile它对测试用例逐条执行spinel --targetwasm32-wasi编译再用 wasmtime 运行并与期望输出比对。3. 浏览器中运行生成的模块是标准 WASI preview 1 模块可在带 WASI shim 的浏览器中加载Node 则可直接用node:wasi模块托管。wasm32 目标下有什么不一样这是部署前必须了解的坑清单全部来自官方文档 docs/wasm.mdInteger 变成 32 位wasm32 指针是 32 位sp_int随指针宽度变化因此Integer 范围为-2**31 .. 2**31-12**40在默认--int-overflowraise下会抛RangeError超范围的字面量则自动成为 Bignum。同一份代码在 64 位宿主机上编译会得到 64 位 Integer——若你的测试假设了 64 位请在文件首行标注# spinel: int64。相关机制详见 docs/int-overflow.md。不支持 Fiber、Enumerator#next、Threadwasm 核心指令没有栈切换Fiber.new会抛FiberError依赖它的对象外部枚举器、Enumerator.newYielder同样失败。使用Thread、Mutex、Queue的程序会在编译期被拒绝——wasm 线程需要 SharedArrayBuffer 和带线程的运行时归档而当前均不提供。无进程、信号、域名解析WASI 没有这些能力fork、spawn、反引号、system、Process.kill、Socket.getaddrinfo等不会变成链接错误而是像 POSIX 上那样返回Errno::ENOSYS/Errno::ENOTSUP/SocketError。preview 1 中无法打开 socket文件 I/O 只在宿主授权的目录内工作wasmtime 用--dir.授权当前目录。其他运行约束栈主线程栈是 8 MB 线性内存wasmtime 另对模块帧的原生栈设 512 KB 上限深度递归的程序请wasmtime run -W max-wasm-stack16777216提高GC运行时 slab 分配器一次性占用 64 MB 线性内存且不归还wasm 内存只增不减超出后每块走malloc函数体大小引擎对单个函数体有上限wasmtime 约 7.6 MB。含rescue的大方法会把所有活跃局部变量存到内存超大顶层程序可能超限——把这类代码移入独立方法即可修复FFIWASI 无dlopenffi_lib绑定不到东西C 函数必须在模块内包自带的 C 或用同一 sdk 编译后用--link链接的对象。内部机制一览wasm 目标由几个关键部分组成源码位置如下组成位置作用WASI 垫片lib/wasi/补齐 wasi-libc 缺失的 POSIX 头文件sys/wait.h、netdb.h、ucontext.h等失败桩实现lib/wasi/sp_wasi.c定义以errno失败返回的调用目标选择src/main.c选定编译器、归档、仿真宏与 sjlj 参数--print-build可打印全部运行时归档Makefilewasm-rt目标编译lib/wasm32-wasi/libspinel_rt.a编译器会设置_WASI_EMULATED_SIGNAL、_WASI_EMULATED_MMAN等仿真宏并用-mllvm -wasm-enable-sjlj -mllvm -wasm-use-legacy-ehfalse完成异常降级。常见问题Q为什么make之后直接编译 wasm 会失败Awasm 运行时归档lib/wasm32-wasi/libspinel_rt.a和各包的sp_*_wasi.o默认不构建需要显式执行make wasm-rt。Q浏览器能跑吗A可以。当前 Chrome、Firefox、Safari 和 Node 均已实现exnref异常指令带 WASI shim 的浏览器可直接加载模块。Q多线程的 Ruby 服务能部署到 wasm 吗A目前不行。含Thread等并发原语的程序在编译期即被拒绝参见上文目标差异部分。总结用 Spinel 把 Ruby 应用带上 WebAssembly 只需三步装好 wasi-sdk →make wasm-rt→spinel --targetwasm32-wasi app.rb。部署目标覆盖 wasmtime、Node 和主流浏览器。记住三件事wasm32 下Integer 是 32 位、没有 Fiber/Thread、没有网络 socket——先对照 docs/limitations.md 检查你的程序再动手编译就能一次通过。完整特性清单与限制请阅读 docs/wasm.md 与 docs/limitations.md。【免费下载链接】spinelRuby AOT compiler项目地址: https://gitcode.com/gh_mirrors/spin/spinel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考