附录
把 Racket 嵌进原生应用——嵌入式运行时的通用模式
你已经读完了一整本书的 Racket。这一篇回答一个收官问题:Racket 能不能不住在自己的 REPL 里,而是住进别人家的应用——一个 Swift 写的 macOS 应用、一个 C++ 写的 Windows 程序?答案是能。这一篇把「嵌入式运行时」的核心技术一次讲透:运行时怎么装进进程、值怎么跨过语言边界、粘合代码怎么不用手写。
为什么要“嵌”
假设你要写一个真正的桌面应用:界面要原生、要快、要符合平台的操作习惯;而业务逻辑——数据加工、领域规则、自动化流程——你想用 Racket 写。工程上有三条路。
第一条:外部进程。 Racket 程序独立运行,UI 程序通过管道或 socket 跟它说话。实现最简单,但代价是两个进程的生命周期要手动对齐:谁先启动、崩溃了谁拉起、升级时怎么搭配版本,全变成你要操心的事。
第二条:HTTP 服务。 Racket 起一个 Web 服务器(卷七第 53 章你亲手写过),UI 当客户端。这条路上手也不难,但每一次数值交互都隔着网络栈的编解码,本机回环也不例外;而且让用户机器上常驻一个监听端口的服务,分发和维护都变重了。
第三条:进程内嵌入。 把 Racket 运行时直接加载进应用的进程,让它和 UI 共享同一个内存空间、同一个生命周期。没有部署拓扑,没有网络往返,启动即可用——代价是你要真正理解「运行时」是什么。
这条路已经有人走通了:把整个 Racket VM 装进一个 iOS 应用,让 Swift 和 Racket 互相对话,是完全可行的事。下面把它的核心技术拆开讲。
运行时的三件套
先回答最底层的问题:Racket CS 被嵌进宿主程序时,真正要准备什么。
运行时库。 在 Unix 系统上,Racket CS 的静态库名是 libracketcs.a;macOS 也可以使用安装中提供的 Racket.framework;Windows 则使用带版本号的 libracketcs*.dll。文件名不是 libracketcs-<架构>-<平台>.a 这种约定式命名,具体路径应从目标 Racket 安装中取得。
头文件。 Racket CS 的嵌入 API 需要包含 chezscheme.h 和 racketcs.h。它们由 Racket 安装放在 include 目录中。不要把 BC 时代或其他内部头文件混进 CS 的最小嵌入接口。
Boot 文件。 Racket CS 启动仍需要 petite.boot、scheme.boot 和 racket.boot。这些文件和运行时库必须来自兼容的同一套安装;宿主程序需要在启动时把它们的位置传给 racket_boot。
工程上最稳妥的原则很简单:把目标 Racket 安装当成一个整体依赖,而不是自己猜库名、头文件和 boot 文件的组合。
启动:把 VM 拉起来
官方推荐的模块嵌入路径不是“先随便编一个 .zo,再把文件塞给 VM”,而是让 raco ctool 生成适合嵌入的模块载荷。例如:
raco ctool --c-mods app.c app.rkt
生成的 app.c 会包含 declare_modules(),把 app.rkt 以及它需要的模块声明嵌进宿主程序。一个精简的 Racket CS 启动骨架如下:
#include <string.h>
#include "chezscheme.h"
#include "racketcs.h"
#include "app.c"
int main(int argc, char **argv) {
racket_boot_arguments_t ba;
memset(&ba, 0, sizeof(ba));
ba.boot1_path = "./petite.boot";
ba.boot2_path = "./scheme.boot";
ba.boot3_path = "./racket.boot";
ba.exec_file = argv[0];
racket_boot(&ba);
declare_modules();
ptr mod = Scons(Sstring_to_symbol("quote"),
Scons(Sstring_to_symbol("app"), Snil));
racket_dynamic_require(mod, Sfalse);
return 0;
}
这里有三个容易踩坑的点:
racket_boot_arguments_t要先清零,再填写需要的字段。- 如果想把模块及其传递依赖一起嵌入,优先使用
raco ctool --c-mods;如果使用--mods生成原始编译载荷,则可以配合racket_embedded_load_file_region等 API 载入。 racket_embedded_load_file/racket_embedded_load_bytes的设计目标是载入已经为嵌入场景生成的编译代码,不是把任意.zo路径当成通用模块加载方案。
线程规则也要说精确。像 racket_dynamic_require、racket_eval、racket_apply 这些 racket_... API 会进入 Racket 的初始线程;直接调用 Chez 的 Scall* 等接口则不等价于“进入 Racket 线程”。宿主程序应该通过 Racket 提供的嵌入 API 和 FFI 回调边界与运行时交互,而不是自行假设“初始化 VM 的 OS 线程就是唯一可调用线程”。
跨过边界:值与内存
VM 跑起来了,接下来是让两边的值互相来往。这一层比想象中琐碎,因为两种语言对「数据」的世界观不同。
Racket 这边,一切皆值:列表、符号、精确有理数、结构体。宿主那边,Swift 有 Int64 和 String,C++ 有 int64_t 和 std::string——没有列表,没有符号,整数还有宽度。所以每一次跨界,值都要被编组(marshal):Racket 的整数变成宿主的定宽整数,字符串统一约定 UTF-8 编码,复合数据要么拆成平铺的字段,要么序列化成字节流再在另一侧重建。
底层的机制值得看一眼:宿主侧看到的 Racket 值通常是 C 类型 ptr。这里最重要的不是“谁来 free”,而是 Racket GC 可能在执行 racket_... API 时移动或回收对象。官方 C API 明确要求:不要把某个 Racket 值的裸引用跨越下一次执行 Racket 代码的调用长期保存。跨语言边界如果需要稳定持有数据,优先把它编组成宿主自己拥有的定宽整数、UTF-8 字节串或其他稳定表示;只有确实需要保留 Racket 对象时,才使用文档明确支持的生命周期/根管理机制。
把这些纪律集合起来,编组层的职责清单就三行:类型翻译、内存归属、错误传播。手写当然可行,但每个函数的两端各写一遍参数拆装,枯燥且容易错——所以现代方案都选了同一条路:不手写,生成它。
契约先行:让宏生成粘合层
这是全部模式里最值得你带走的一个,因为它把卷六学的宏系统变成了工程生产力。
思路是:**用一套声明式宏把「两端共享的接口」写成一份契约,再由宏展开生成两端的粘合代码。**一套典型的契约 DSL 长这样:
;; 数据结构:一次计算日志
(define-record OperationLog
[operator : String]
[operand1 : Float64]
[operand2 : Float64]
[result : Float64])
;; 过程:宿主可以调用的 RPC,签名即契约
(define-rpc (calculator-add [a : Float64] [b : Float64] : Float64)
(+ a b))
这两个「宏」在展开期做的事情,你在卷六全都写过雏形:用 syntax-class 解析字段语法,提取字段名、类型、可选性;据此生成 Racket 侧的 struct 和访问器;生成描述这份形状的元数据并注册到全局表——元数据就是后续一切代码生成的依据;最后生成序列化和反序列化代码。宿主侧的粘合层由工具从同一份元数据生成:calculator-add 在 Swift 侧变成一个普通的强类型函数 func calculatorAdd(a: Double, b: Double) -> Double,编组、传输、错误传播全部由生成的代码接管。
至于宿主与 Racket 之间到底采用“直接 C API 调用”、FFI 回调,还是再包一层消息协议,这是应用自己的架构选择。进程内嵌入并不要求 stdin/stdout 或文件描述符协议;如果你为了隔离、异步调度或生成式 RPC 额外设计消息层,再定义定宽整数、UTF-8、长度前缀、请求 id 等协议即可。
回头看这条技术路线,它其实是本书主线的一次收束:**宏系统是「协议工程学」的底座。**语言可定制(卷六)意味着接口描述本身也可以是一门为跨语言定制的小语言——契约即代码,粘合层即宏展开的产物。声明一份契约,两端独立进化:后端重构内部实现,契约不动,宿主一行不改;UI 换掉整个框架,Racket 后端浑然不觉。
分发:平台 × 架构的乘法
模式讲完,剩下的是工程现实:你的应用要跑在用户的机器上,而用户的机器是 x86_64 或 ARM64,是 macOS、Windows 或 Linux。
嵌入式方案的分发矩阵因此是「平台 × 架构 × 运行时」的三维乘法:每个目标都要有对应的运行时库和 boot 文件,宿主二进制也要按目标编译。Apple 平台的答案是 XCFramework——把各架构的静态库和头文件打成单个可分发的框架;其他平台则直接按目标链接对应的静态库。共同的思路是把「编译 Racket 运行时 → 编译应用字节码 → 集成进宿主 → 出应用包」写成 CI 流水线,每个目标一组产物,发布时一次性出齐。
对比一下这条路的两个时代:早些年嵌入一个 Lisp 运行时是 C 层的冒险,每一步都要自己摸索;今天它需要的全部原料——静态库、头文件、boot 文件——都是 Racket 发行版自带的产物,raco make 负责字节码,剩下的只是把它们装配起来。基础设施成熟的意义就在这里:让下一批人从「打通链路」直接跳到「解决问题」。
工程检查清单
把这一篇的模式收拢成一张清单,供你设计自己的嵌入方案时对照:
- 按官方平台方式链接运行时:Unix/macOS 静态库是
libracketcs.a,macOS 也可使用Racket.framework,Windows 使用对应的 Racket CS DLL。 - 头文件用
chezscheme.h+racketcs.h,boot 文件用petite.boot、scheme.boot、racket.boot,并让它们来自兼容的同一套 Racket 安装。 - 启动参数先清零:初始化
racket_boot_arguments_t后再填写 boot 路径与exec_file,然后调用racket_boot。 - 模块优先交给
raco ctool --c-mods:让工具把模块及传递依赖生成成适合嵌入的 C 载荷,再通过declare_modules和racket_dynamic_require使用。 - 不要长期保存裸
ptr:运行 Racket 代码可能触发 GC 和对象移动;跨边界优先复制成宿主稳定拥有的数据。 - 通过 Racket 嵌入 API/FFI 边界调用,不要把 Chez 的直接调用或某个固定 OS 线程误当成 Racket 的完整线程模型。
- 分发矩阵交给 CI:对每个平台和架构,用目标 Racket 安装实际构建、链接并在干净机器上做启动测试。
Racket 官方的 Inside: Racket C API 与 raco ctool --c-mods 文档应该是这类工程的第一手依据。第三方项目可以作为实现参考,但不要反过来把某个项目的私有封装当成 Racket 嵌入 API 本身。
结语
这本书从「写几行文字,电脑就会动」开始,一路走到了语言工场:你能造类型、造控制流、造语言,现在你也知道,这些语言和程序可以住进任何宿主、交付给任何用户。
Racket 的终极形态从来不是「又一个脚本语言」,而是应用逻辑的通用底座:宏系统让你定制语言,契约让你跨越边界,嵌入让你进入原生世界。工具已经在你手里,剩下的问题只有一个——你想造点什么?