Roc 编译器嵌入指南在 Zig 程序中内嵌编译并执行 .roc 模块【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc本文以 src/compile/README.md 为骨架系统讲解 Roc 编译模块compile的嵌入能力如何在另一个 Zig 程序中创建Coordinator驱动编译管线把.roc源码降到 LIR低层中间表示、构建 LIR 镜像并通过LirInterpreter在进程内直接执行。读完本文你将掌握标准嵌入序列canonical sequence、仅类型检查的轻量流程、运行时内存所有权规则、自定义文件系统与宿主函数host functions的接入方式以及 URL 解析包的注册方法并能对照仓库源码与测试用例验证每一步的真实行为。compile 模块Roc 编译管线的编排核心src/compile/目录承载 Roc 编译器编译模块的核心逻辑输入 Roc 源码经过多个阶段处理后产出可执行文件或库。其关键职责包括编译管线Compilation Pipeline管理模块在编译器各阶段间的流转Tokenizing词法分析Parsing语法分析Canonicalizing规范化Type Checking类型检查Code Generation代码生成当前仓库中尚未实现模块缓存Module Caching管理已编译模块的缓存加速后续构建包构建Package Building构建完整包构建环境Build Environment管理构建上下文与环境compile 模块扮演编排者角色协调不同编译阶段并在其间高效调度构建过程。这一编排在源码层面体现为明确的文件划分coordinator.zig状态编排核心、app_header.zig应用头解析、cache_*.zig缓存键/配置/管理器/模块/报告/清理、compile_package.zig/compile_module.zig/compile_build.zig包、模块、构建三元组、module_discovery.zig模块发现、package_*.zig包解析与来源、messages.zig/channel.zig消息与通道等统一由 mod.zig 聚合导出。从 coordinator.zig 顶部的架构注释可以看出编译采用 actor 模型Coordinator是编译管线中所有可变状态的唯一持有者从而从设计上消除竞态——单线程状态变更状态无需加锁worker 保持纯粹接收任务、返回结果通信通过有界通道完成。Worker 各自持有独立的 arena经任务队列task queue注入任务、经 MPSC 结果通道result channel回收结果Builtins 等只读数据共享访问。嵌入方案总览Coordinator LIR 镜像 解释器Roc 可以被嵌入到另一个 Zig 程序中在进程内完成.roc文件的编译与执行。嵌入的驱动者是Coordinator进程内执行路径则使用lir.LirImage与eval.LirInterpreter。Coordinator.init的完整签名见 coordinator.zig如下pub fn init( gpa: Allocator, mode: Mode, max_threads: usize, target: roc_target.RocTarget, builtin_modules: *const BuiltinModules, compiler_version: []const u8, cache_manager: ?*CacheManager, roc_ctx: CoreCtx, ) Allocator.Error!Coordinator各参数含义参数说明gpa通用目的分配器负责协调器自身的状态分配mode运行模式如.single_threaded示例与测试均使用或.multi_threadedmax_threads工作线程数量上限target编译目标平台通常使用roc_target.RocTarget.detectNative()探测宿主机builtin_modules预初始化的内建模块集合eval.BuiltinModules.init(gpa)创建compiler_version编译器版本字符串参与缓存键计算cache_manager可选的缓存管理器无文件系统场景可传nullroc_ctx核心上下文CoreCtx提供文件系统与 I/O 抽象嵌入 API 的形状shape是稳定的实现细节可能在版本间变化因此嵌入代码应依赖上述公开方法而非内部字段。标准嵌入序列Canonical Sequence原文档给出了完整的 7 步嵌入序列。为便于对照阅读embedding_smoke.zig 在文件头注释中明确指出该端到端冒烟测试驱动了嵌入者预期调用的每一个方法discoverAppFromPath→coordinatorLoop→iterReports→finishCheckedProgram→lowerCheckedModulesToLir→platformEntrypoints→fillHeaderInBuffer→viewMappedImage→runEntrypoint如果该测试被破坏意味着公开 API 面发生了会破坏外部嵌入者的变化该测试本身就是文档其结构与 README 中展示的标准序列一一对应。下面逐步展开。第 1 步Builtins 与 Coordinator 初始化const compile import(compile); const lir import(lir); const eval import(eval); const check import(check); const base import(base); // 1. Builtins Coordinator var builtins try eval.BuiltinModules.init(gpa); defer builtins.deinit(); var coord try compile.coordinator.Coordinator.init( gpa, .single_threaded, 1, target, builtins, version, null, ); defer coord.deinit(); coord.enable_hosted_transform true; // if you have host functions coord.setIo(my_io); // optional: virtualise the filesystemcoord.enable_hosted_transform若平台模块中存在托管 lambdahosted lambda需在start()之前置为true规范化阶段会自动转换它们见下文宿主函数一节。从源码可见enable_hosted_transform字段在 coordinator.zig 定义、默认初始化为false。coord.setIo(...)可选用于虚拟化文件系统。在 coordinator.zig 中setIo是setCoreCtx的向后兼容别名——两者均设置self.roc_ctx嵌入文档契约即使用setIo这一名称。第 2 步发现并编译try coord.start(); try coord.discoverAppFromPath(arena, .{ .entry_path app_path }); try coord.coordinatorLoop();discoverAppFromPath实现见 coordinator.zig读取应用.roc文件的头部app_header.parseAppHeader注册应用包、平台包与非平台包然后入队解析任务。其选项结构pub const AppDiscoveryOptions struct { /// Path to the app .roc file, accessible via the configured Io. entry_path: []const u8, /// Optional override for the app modules source_dir_override. source_dir_override: ?[]const u8 null, };需要注意discoverAppFromPath只支持相对路径形式的平台/包引用URL 形式会返回error.UnsupportedPlatformSpec或error.UnsupportedPackageSpec见下文URL 解析包一节。coordinatorLoop()会驱动前端直到耗尽全部任务。第 3 步最终化可执行产物try coord.finalizeExecutableArtifacts();用户诊断user diagnostics由显式的 checked-error/crash 事实表示永远不会阻止产物发布——即诊断结果不构成 lowering 的开关。在源码中这一步对应finishCheckedProgram(.executable_artifacts)见 coordinator.zig它会先prepareExecutableArtifacts()准备可执行产物再evaluatePreparedModules()求值已就绪的模块embedding_smoke.zig 中同样以finishCheckedProgram(.executable_artifacts)调用并断言!coord.hasUserErrors()。第 4 步渲染或收集诊断var it coord.iterReports(); while (it.next()) |entry| { // entry.package_name, entry.module_name, entry.report }嵌入者可以用这些诊断信息选择命令退出状态或展示方式但不得用它来门控 lowering。第 5 步降低到 LIRconst root coord.executableRootCheckedArtifact(); const imports try coord.collectImportedArtifactViews(arena, root); const relations try coord.collectRelationArtifactViews(arena, root); const lir_roots try lir.CheckedPipeline.selectPlatformEntrypointRoots(arena, root.root_requests.runtime_requests); const lowered try lir.CheckedPipeline.lowerCheckedModulesToLir( runtime_alloc, .{ .root check.CheckedArtifact.loweringViewWithRelations(root, relations), .imports imports, }, .{ .requests lir_roots }, .{ .target_usize base.target.TargetUsize.native, .post_check_executor coord.postCheckExecutor(), }, );这里的分配器必须持有单一连续缓冲详见下文Runtime Arena一节。postCheckExecutor()复用协调器持有的持久编译 worker用于无图graph-free的 post-check 任务。它是一个刻意设计为同步借用的能力只能在coordinatorLoop()排空前端之后、协调器关闭之前获取与使用前端与 post-check 工作共享同一套任务/结果通道因此两个阶段重叠属于不变量违规invariant violation。第 6 步在连续缓冲中构建 LIR 镜像const entrypoints try lowered.platformEntrypoints(runtime_alloc); const entrypoint_names try lowered.platformEntrypointNames(arena, root); const image_header try runtime_alloc.create(lir.LirImage.Header); try lir.LirImage.fillHeaderInBuffer( image_header, runtime_buffer.ptr, // start of the contiguous backing buffer runtime_fba.end_index, // bytes used so far lowered.lir_result, lowered.target_usize, entrypoints, ); var view try lir.LirImage.viewMappedImage( image_header, runtime_buffer.ptr, runtime_fba.end_index, lowered.target_usize, ); defer view.deinit();fillHeaderInBuffer见 lir_image.zig只安装偏移元数据offset metadata不拷贝数据它把root_procs、platform_entrypoints、boxy_worker_procs、store、layouts、boxy_tables等数组引用以base_ptr为基准换算为偏移并写入 header。若lowered.static_data_values非空会直接返回error.InvalidLirImage。viewMappedImage见 lir_image.zig则把 header 校验后原位重建为可读的ProgramView它检查mapped_size是否容纳得下 header、magic与format_version是否匹配、image_size是否超出mapped_size等任何不一致都会以error.InvalidLirImage/error.UnsupportedLirImageVersion报告。镜像内容是指针宽度无关的消费方在调用时自行指定target_usize因此同一份镜像字节可被原生解释器与 32 位代码生成后端以不同宽度复用。第 7 步通过解释器执行var interp try eval.LirInterpreter.init( gpa, view.store, view.layouts, my_roc_ops, .preserve, ); defer interp.deinit(); _ try interp.runEntrypoint(view, 0, args, result_buf);LirInterpreter.init见 interpreter.zig接收 store、layouts、宿主RocOps与求值策略如.preserverunEntrypointinterpreter.zig以入口点序号此处为0即第一个provides声明、参数与结果缓冲执行程序。embedding_smoke.zig 中展示了等价的执行收尾以initWithBoxyTables初始化解释器为无宿主函数的最小应用传入emptyHostedFunctions然后runEntrypoint(view, 0, null, ptrCast(ret_buf))。仅类型检查流程Type-check-only flow对于 LSP、模糊测试fuzzing或任何只需要诊断信息的消费方在标准序列的第 3 步之后即可停止——完全跳过finalizeExecutableArtifacts、LIR lowering 与执行try coord.start(); try coord.discoverAppFromPath(arena, .{ .entry_path app_path }); try coord.coordinatorLoop(); var it coord.iterReports(); while (it.next()) |entry| { // render entry.report } const had_errors coord.hasUserErrors();hasUserErrors见 coordinator.zig返回前端完成后是否存在用户错误。embedding_smoke.zig 中iterReports遍历后断言每个 entry 的severity既非.fatal也非.runtime_error并断言!coord.hasUserErrors()正是该流程的测试化印证。Runtime Arena镜像分配器的连续缓冲约束fillHeaderInBuffer与viewMappedImage通过ptr - base_ptr指针差计算偏移因此镜像分配器必须拥有单一连续的虚拟内存区域。std.heap.ArenaAllocator通过分配新页面增长不能使用——它算出的偏移将是错误的要么静默产生损坏的镜像要么触发error.InvalidLirImage。正确做法是使用std.heap.FixedBufferAllocator覆盖一块堆上分配的连续缓冲const RUNTIME_ARENA_SIZE 128 * 1024 * 1024; // 128 MiB const runtime_buffer try gpa.alignedAlloc(u8, 16, RUNTIME_ARENA_SIZE); defer gpa.free(runtime_buffer); var runtime_fba std.heap.FixedBufferAllocator.init(runtime_buffer); const runtime_alloc runtime_fba.allocator();尺寸建议典型的应用至少预留 128 MiB——即使是一个 hello world在 lowering 所有可达模块之后也需要超过 16 MiB。Linux/macOS 上匿名虚拟内存是过量提交overcommit的所以预留一个宽裕的缓冲并不会真正占用物理内存只有实际触碰到的页面才会。请选择一个能舒适容纳你预期最大程序的数值。embedding_smoke.zig 正是以 128 MiB 的gpa.alignedAlloc(u8, .16, RUNTIME_ARENA_SIZE)复现了这一模式。内存所有权宿主侧的 decref 义务Roc 返回给宿主的引用计数refcounted值——通过ret_ptr写出的RocStr、RocList或RocBox或作为参数传给宿主函数的这些类型——内存归宿主所有。解释器在eval返回时不会自动执行 tear-down这是刻意设计嵌入者常常希望在释放返回值之前先检查它。宿主在使用完毕后必须显式decref返回的引用计数值否则宿主分配器的泄漏检查会报告追溯到解释器内rocAllocFn的泄漏// After interp.runEntrypoint(...) returns, if the entrypoints return type // is a refcounted value (e.g. RocStr returned via ret_ptr), decref before // tearing down. RocStr.decref takes the value by copy and a *RocOps; its // a no-op for small (stack) strings. const result_str: RocStr as(*const RocStr, ptrCast(alignCast(result_buf))).*; defer result_str.decref(my_roc_ops);同样的规则适用于宿主函数参数宿主在调用期间拥有收到的每个*RocStr或其他引用计数指针。可以随意读取但若要把值保存下来稍后使用应先调用相应的incref辅助函数。自定义文件系统通过CoreCtx提供 I/O vtable并用coord.setIo(...)传入setIo即setCoreCtx的兼容别名见 coordinator.zig。默认的CoreCtx.default(gpa, arena, std_io_arg)见 CoreCtx.zig在非 freestanding 目标上使用 OS vtable文件读写落到std.fs.cwd()。CoreCtx的 vtable 覆盖了编译所需的全套文件系统能力readFile/readFileInto/writeFile/fileExists/stat/listDir/dirName/baseName/joinPath/canonicalize/makePath/rename/getEnvVar/fetchUrl/deleteFile等见 CoreCtx.zig 的 freestanding 变体。对于完全没有文件系统的嵌入者例如 wasmCoordinator并不强制要求文件系统——只要传入的每个路径都能通过所配置的Io得到服务即可Coordinator.init的cache_manager参数此时可以传null。测试场景也可使用CoreCtx.testingCoreCtx.zig其每个 I/O 调用都会 panic可在测试中逐个覆写 vtable 字段以提供 mock 行为。宿主函数Host Functions在coord.start()之前设置coord.enable_hosted_transform true。平台模块中的托管 lambda 体hosted lambda bodies会在规范化canonicalization期间自动转换。执行时RocOps.hosted_fns.fns是一个位置数组——解释器按fns[dispatch_index]调用。dispatch 索引就是该托管函数在平台头hosted区段中的位置因此数组顺序必须与该区段的书写顺序一致hosted { roc_stdout_line: Stdout.line!, roc_stderr_line: Stderr.line! }上述声明给出Stdout.line!索引 0、Stderr.line!索引 1无论它们声明在哪个模块中。roc glue生成的胶水代码采用相同的编号因此生成的 glue 与手写数组是一致的。平台模块自身的声明不带模块名平台不能导入自身hosted { roc_helper: helper! }。顺序错误是静默的调用错误的函数而不是响亮的——尤其是重新排列hosted区段时要格外谨慎。没有hosted区段的平台没有任何绑定声明post-check lowering 会按过程的确定性顺序键deterministic order key排列其余内容。URL 解析包Coordinator.discoverAppFromPath不会下载 URL 指定的包——它只支持相对路径。需要 URL 支持时按以下四步调用compile.app_header.parseAppHeader(io, gpa, arena, path)获取原始头部实现见 app_header.zig用自己的缓存策略把 URL 解析为本地路径改用coord.ensurePackage/coord.registerInlinePackage注册包而不是discoverAppFromPathensurePackage见 coordinator.zigregisterInlinePackage见 coordinator.zig。Roc CLI 完全遵循这一模式。url_package_test.zig 给出了一个无网络场景的集成测试先在本地包缓存中预置一个此前下载解压的 URL 依赖包cache/fake_hash/main.roc与Util.roc再让本地消费包main.roc以package [Consumer] { util: url }引用它验证 URL 依赖能仅凭热缓存完成构建。CLI 侧的完整工作示例见 main.zig 的buildLirImageWithBuildEnvREADME 中以其旧称buildLirImageWithCoordinator提及它先用compile.app_header.parseAppHeader解析应用头见 main.zig再经 lowering 与镜像构建得到共享内存中的 LIR 镜像。小结Roc 的 compile 模块将词法分析、解析、规范化、类型检查到尚未实现的代码生成串联为一条清晰的编译管线并以 actor 模型下的Coordinator统一编排状态与任务调度。对嵌入者而言标准序列初始化Coordinator→ 发现并编译 → 最终化产物 → 收集诊断 → 降低到 LIR → 构建镜像 → 解释执行构成了稳定、可测试的进程内编译执行契约而仅类型检查流程则为 LSP 与模糊测试等诊断类消费者提供了轻量捷径。落地时请牢记三条硬性规则镜像分配器必须使用覆盖单一连续缓冲的FixedBufferAllocator建议 128 MiB 起步、宿主必须显式decref收到的引用计数值、托管函数数组必须与平台头hosted区段顺序一致。若需支持 URL 依赖则绕过discoverAppFromPath自行解析头部并借助ensurePackage/registerInlinePackage注册——这与 Roc CLI 自身的实现路径完全一致。【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Roc 编译器嵌入指南：在 Zig 程序中内嵌编译并执行 .roc 模块
Roc 编译器嵌入指南在 Zig 程序中内嵌编译并执行 .roc 模块【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc本文以 src/compile/README.md 为骨架系统讲解 Roc 编译模块compile的嵌入能力如何在另一个 Zig 程序中创建Coordinator驱动编译管线把.roc源码降到 LIR低层中间表示、构建 LIR 镜像并通过LirInterpreter在进程内直接执行。读完本文你将掌握标准嵌入序列canonical sequence、仅类型检查的轻量流程、运行时内存所有权规则、自定义文件系统与宿主函数host functions的接入方式以及 URL 解析包的注册方法并能对照仓库源码与测试用例验证每一步的真实行为。compile 模块Roc 编译管线的编排核心src/compile/目录承载 Roc 编译器编译模块的核心逻辑输入 Roc 源码经过多个阶段处理后产出可执行文件或库。其关键职责包括编译管线Compilation Pipeline管理模块在编译器各阶段间的流转Tokenizing词法分析Parsing语法分析Canonicalizing规范化Type Checking类型检查Code Generation代码生成当前仓库中尚未实现模块缓存Module Caching管理已编译模块的缓存加速后续构建包构建Package Building构建完整包构建环境Build Environment管理构建上下文与环境compile 模块扮演编排者角色协调不同编译阶段并在其间高效调度构建过程。这一编排在源码层面体现为明确的文件划分coordinator.zig状态编排核心、app_header.zig应用头解析、cache_*.zig缓存键/配置/管理器/模块/报告/清理、compile_package.zig/compile_module.zig/compile_build.zig包、模块、构建三元组、module_discovery.zig模块发现、package_*.zig包解析与来源、messages.zig/channel.zig消息与通道等统一由 mod.zig 聚合导出。从 coordinator.zig 顶部的架构注释可以看出编译采用 actor 模型Coordinator是编译管线中所有可变状态的唯一持有者从而从设计上消除竞态——单线程状态变更状态无需加锁worker 保持纯粹接收任务、返回结果通信通过有界通道完成。Worker 各自持有独立的 arena经任务队列task queue注入任务、经 MPSC 结果通道result channel回收结果Builtins 等只读数据共享访问。嵌入方案总览Coordinator LIR 镜像 解释器Roc 可以被嵌入到另一个 Zig 程序中在进程内完成.roc文件的编译与执行。嵌入的驱动者是Coordinator进程内执行路径则使用lir.LirImage与eval.LirInterpreter。Coordinator.init的完整签名见 coordinator.zig如下pub fn init( gpa: Allocator, mode: Mode, max_threads: usize, target: roc_target.RocTarget, builtin_modules: *const BuiltinModules, compiler_version: []const u8, cache_manager: ?*CacheManager, roc_ctx: CoreCtx, ) Allocator.Error!Coordinator各参数含义参数说明gpa通用目的分配器负责协调器自身的状态分配mode运行模式如.single_threaded示例与测试均使用或.multi_threadedmax_threads工作线程数量上限target编译目标平台通常使用roc_target.RocTarget.detectNative()探测宿主机builtin_modules预初始化的内建模块集合eval.BuiltinModules.init(gpa)创建compiler_version编译器版本字符串参与缓存键计算cache_manager可选的缓存管理器无文件系统场景可传nullroc_ctx核心上下文CoreCtx提供文件系统与 I/O 抽象嵌入 API 的形状shape是稳定的实现细节可能在版本间变化因此嵌入代码应依赖上述公开方法而非内部字段。标准嵌入序列Canonical Sequence原文档给出了完整的 7 步嵌入序列。为便于对照阅读embedding_smoke.zig 在文件头注释中明确指出该端到端冒烟测试驱动了嵌入者预期调用的每一个方法discoverAppFromPath→coordinatorLoop→iterReports→finishCheckedProgram→lowerCheckedModulesToLir→platformEntrypoints→fillHeaderInBuffer→viewMappedImage→runEntrypoint如果该测试被破坏意味着公开 API 面发生了会破坏外部嵌入者的变化该测试本身就是文档其结构与 README 中展示的标准序列一一对应。下面逐步展开。第 1 步Builtins 与 Coordinator 初始化const compile import(compile); const lir import(lir); const eval import(eval); const check import(check); const base import(base); // 1. Builtins Coordinator var builtins try eval.BuiltinModules.init(gpa); defer builtins.deinit(); var coord try compile.coordinator.Coordinator.init( gpa, .single_threaded, 1, target, builtins, version, null, ); defer coord.deinit(); coord.enable_hosted_transform true; // if you have host functions coord.setIo(my_io); // optional: virtualise the filesystemcoord.enable_hosted_transform若平台模块中存在托管 lambdahosted lambda需在start()之前置为true规范化阶段会自动转换它们见下文宿主函数一节。从源码可见enable_hosted_transform字段在 coordinator.zig 定义、默认初始化为false。coord.setIo(...)可选用于虚拟化文件系统。在 coordinator.zig 中setIo是setCoreCtx的向后兼容别名——两者均设置self.roc_ctx嵌入文档契约即使用setIo这一名称。第 2 步发现并编译try coord.start(); try coord.discoverAppFromPath(arena, .{ .entry_path app_path }); try coord.coordinatorLoop();discoverAppFromPath实现见 coordinator.zig读取应用.roc文件的头部app_header.parseAppHeader注册应用包、平台包与非平台包然后入队解析任务。其选项结构pub const AppDiscoveryOptions struct { /// Path to the app .roc file, accessible via the configured Io. entry_path: []const u8, /// Optional override for the app modules source_dir_override. source_dir_override: ?[]const u8 null, };需要注意discoverAppFromPath只支持相对路径形式的平台/包引用URL 形式会返回error.UnsupportedPlatformSpec或error.UnsupportedPackageSpec见下文URL 解析包一节。coordinatorLoop()会驱动前端直到耗尽全部任务。第 3 步最终化可执行产物try coord.finalizeExecutableArtifacts();用户诊断user diagnostics由显式的 checked-error/crash 事实表示永远不会阻止产物发布——即诊断结果不构成 lowering 的开关。在源码中这一步对应finishCheckedProgram(.executable_artifacts)见 coordinator.zig它会先prepareExecutableArtifacts()准备可执行产物再evaluatePreparedModules()求值已就绪的模块embedding_smoke.zig 中同样以finishCheckedProgram(.executable_artifacts)调用并断言!coord.hasUserErrors()。第 4 步渲染或收集诊断var it coord.iterReports(); while (it.next()) |entry| { // entry.package_name, entry.module_name, entry.report }嵌入者可以用这些诊断信息选择命令退出状态或展示方式但不得用它来门控 lowering。第 5 步降低到 LIRconst root coord.executableRootCheckedArtifact(); const imports try coord.collectImportedArtifactViews(arena, root); const relations try coord.collectRelationArtifactViews(arena, root); const lir_roots try lir.CheckedPipeline.selectPlatformEntrypointRoots(arena, root.root_requests.runtime_requests); const lowered try lir.CheckedPipeline.lowerCheckedModulesToLir( runtime_alloc, .{ .root check.CheckedArtifact.loweringViewWithRelations(root, relations), .imports imports, }, .{ .requests lir_roots }, .{ .target_usize base.target.TargetUsize.native, .post_check_executor coord.postCheckExecutor(), }, );这里的分配器必须持有单一连续缓冲详见下文Runtime Arena一节。postCheckExecutor()复用协调器持有的持久编译 worker用于无图graph-free的 post-check 任务。它是一个刻意设计为同步借用的能力只能在coordinatorLoop()排空前端之后、协调器关闭之前获取与使用前端与 post-check 工作共享同一套任务/结果通道因此两个阶段重叠属于不变量违规invariant violation。第 6 步在连续缓冲中构建 LIR 镜像const entrypoints try lowered.platformEntrypoints(runtime_alloc); const entrypoint_names try lowered.platformEntrypointNames(arena, root); const image_header try runtime_alloc.create(lir.LirImage.Header); try lir.LirImage.fillHeaderInBuffer( image_header, runtime_buffer.ptr, // start of the contiguous backing buffer runtime_fba.end_index, // bytes used so far lowered.lir_result, lowered.target_usize, entrypoints, ); var view try lir.LirImage.viewMappedImage( image_header, runtime_buffer.ptr, runtime_fba.end_index, lowered.target_usize, ); defer view.deinit();fillHeaderInBuffer见 lir_image.zig只安装偏移元数据offset metadata不拷贝数据它把root_procs、platform_entrypoints、boxy_worker_procs、store、layouts、boxy_tables等数组引用以base_ptr为基准换算为偏移并写入 header。若lowered.static_data_values非空会直接返回error.InvalidLirImage。viewMappedImage见 lir_image.zig则把 header 校验后原位重建为可读的ProgramView它检查mapped_size是否容纳得下 header、magic与format_version是否匹配、image_size是否超出mapped_size等任何不一致都会以error.InvalidLirImage/error.UnsupportedLirImageVersion报告。镜像内容是指针宽度无关的消费方在调用时自行指定target_usize因此同一份镜像字节可被原生解释器与 32 位代码生成后端以不同宽度复用。第 7 步通过解释器执行var interp try eval.LirInterpreter.init( gpa, view.store, view.layouts, my_roc_ops, .preserve, ); defer interp.deinit(); _ try interp.runEntrypoint(view, 0, args, result_buf);LirInterpreter.init见 interpreter.zig接收 store、layouts、宿主RocOps与求值策略如.preserverunEntrypointinterpreter.zig以入口点序号此处为0即第一个provides声明、参数与结果缓冲执行程序。embedding_smoke.zig 中展示了等价的执行收尾以initWithBoxyTables初始化解释器为无宿主函数的最小应用传入emptyHostedFunctions然后runEntrypoint(view, 0, null, ptrCast(ret_buf))。仅类型检查流程Type-check-only flow对于 LSP、模糊测试fuzzing或任何只需要诊断信息的消费方在标准序列的第 3 步之后即可停止——完全跳过finalizeExecutableArtifacts、LIR lowering 与执行try coord.start(); try coord.discoverAppFromPath(arena, .{ .entry_path app_path }); try coord.coordinatorLoop(); var it coord.iterReports(); while (it.next()) |entry| { // render entry.report } const had_errors coord.hasUserErrors();hasUserErrors见 coordinator.zig返回前端完成后是否存在用户错误。embedding_smoke.zig 中iterReports遍历后断言每个 entry 的severity既非.fatal也非.runtime_error并断言!coord.hasUserErrors()正是该流程的测试化印证。Runtime Arena镜像分配器的连续缓冲约束fillHeaderInBuffer与viewMappedImage通过ptr - base_ptr指针差计算偏移因此镜像分配器必须拥有单一连续的虚拟内存区域。std.heap.ArenaAllocator通过分配新页面增长不能使用——它算出的偏移将是错误的要么静默产生损坏的镜像要么触发error.InvalidLirImage。正确做法是使用std.heap.FixedBufferAllocator覆盖一块堆上分配的连续缓冲const RUNTIME_ARENA_SIZE 128 * 1024 * 1024; // 128 MiB const runtime_buffer try gpa.alignedAlloc(u8, 16, RUNTIME_ARENA_SIZE); defer gpa.free(runtime_buffer); var runtime_fba std.heap.FixedBufferAllocator.init(runtime_buffer); const runtime_alloc runtime_fba.allocator();尺寸建议典型的应用至少预留 128 MiB——即使是一个 hello world在 lowering 所有可达模块之后也需要超过 16 MiB。Linux/macOS 上匿名虚拟内存是过量提交overcommit的所以预留一个宽裕的缓冲并不会真正占用物理内存只有实际触碰到的页面才会。请选择一个能舒适容纳你预期最大程序的数值。embedding_smoke.zig 正是以 128 MiB 的gpa.alignedAlloc(u8, .16, RUNTIME_ARENA_SIZE)复现了这一模式。内存所有权宿主侧的 decref 义务Roc 返回给宿主的引用计数refcounted值——通过ret_ptr写出的RocStr、RocList或RocBox或作为参数传给宿主函数的这些类型——内存归宿主所有。解释器在eval返回时不会自动执行 tear-down这是刻意设计嵌入者常常希望在释放返回值之前先检查它。宿主在使用完毕后必须显式decref返回的引用计数值否则宿主分配器的泄漏检查会报告追溯到解释器内rocAllocFn的泄漏// After interp.runEntrypoint(...) returns, if the entrypoints return type // is a refcounted value (e.g. RocStr returned via ret_ptr), decref before // tearing down. RocStr.decref takes the value by copy and a *RocOps; its // a no-op for small (stack) strings. const result_str: RocStr as(*const RocStr, ptrCast(alignCast(result_buf))).*; defer result_str.decref(my_roc_ops);同样的规则适用于宿主函数参数宿主在调用期间拥有收到的每个*RocStr或其他引用计数指针。可以随意读取但若要把值保存下来稍后使用应先调用相应的incref辅助函数。自定义文件系统通过CoreCtx提供 I/O vtable并用coord.setIo(...)传入setIo即setCoreCtx的兼容别名见 coordinator.zig。默认的CoreCtx.default(gpa, arena, std_io_arg)见 CoreCtx.zig在非 freestanding 目标上使用 OS vtable文件读写落到std.fs.cwd()。CoreCtx的 vtable 覆盖了编译所需的全套文件系统能力readFile/readFileInto/writeFile/fileExists/stat/listDir/dirName/baseName/joinPath/canonicalize/makePath/rename/getEnvVar/fetchUrl/deleteFile等见 CoreCtx.zig 的 freestanding 变体。对于完全没有文件系统的嵌入者例如 wasmCoordinator并不强制要求文件系统——只要传入的每个路径都能通过所配置的Io得到服务即可Coordinator.init的cache_manager参数此时可以传null。测试场景也可使用CoreCtx.testingCoreCtx.zig其每个 I/O 调用都会 panic可在测试中逐个覆写 vtable 字段以提供 mock 行为。宿主函数Host Functions在coord.start()之前设置coord.enable_hosted_transform true。平台模块中的托管 lambda 体hosted lambda bodies会在规范化canonicalization期间自动转换。执行时RocOps.hosted_fns.fns是一个位置数组——解释器按fns[dispatch_index]调用。dispatch 索引就是该托管函数在平台头hosted区段中的位置因此数组顺序必须与该区段的书写顺序一致hosted { roc_stdout_line: Stdout.line!, roc_stderr_line: Stderr.line! }上述声明给出Stdout.line!索引 0、Stderr.line!索引 1无论它们声明在哪个模块中。roc glue生成的胶水代码采用相同的编号因此生成的 glue 与手写数组是一致的。平台模块自身的声明不带模块名平台不能导入自身hosted { roc_helper: helper! }。顺序错误是静默的调用错误的函数而不是响亮的——尤其是重新排列hosted区段时要格外谨慎。没有hosted区段的平台没有任何绑定声明post-check lowering 会按过程的确定性顺序键deterministic order key排列其余内容。URL 解析包Coordinator.discoverAppFromPath不会下载 URL 指定的包——它只支持相对路径。需要 URL 支持时按以下四步调用compile.app_header.parseAppHeader(io, gpa, arena, path)获取原始头部实现见 app_header.zig用自己的缓存策略把 URL 解析为本地路径改用coord.ensurePackage/coord.registerInlinePackage注册包而不是discoverAppFromPathensurePackage见 coordinator.zigregisterInlinePackage见 coordinator.zig。Roc CLI 完全遵循这一模式。url_package_test.zig 给出了一个无网络场景的集成测试先在本地包缓存中预置一个此前下载解压的 URL 依赖包cache/fake_hash/main.roc与Util.roc再让本地消费包main.roc以package [Consumer] { util: url }引用它验证 URL 依赖能仅凭热缓存完成构建。CLI 侧的完整工作示例见 main.zig 的buildLirImageWithBuildEnvREADME 中以其旧称buildLirImageWithCoordinator提及它先用compile.app_header.parseAppHeader解析应用头见 main.zig再经 lowering 与镜像构建得到共享内存中的 LIR 镜像。小结Roc 的 compile 模块将词法分析、解析、规范化、类型检查到尚未实现的代码生成串联为一条清晰的编译管线并以 actor 模型下的Coordinator统一编排状态与任务调度。对嵌入者而言标准序列初始化Coordinator→ 发现并编译 → 最终化产物 → 收集诊断 → 降低到 LIR → 构建镜像 → 解释执行构成了稳定、可测试的进程内编译执行契约而仅类型检查流程则为 LSP 与模糊测试等诊断类消费者提供了轻量捷径。落地时请牢记三条硬性规则镜像分配器必须使用覆盖单一连续缓冲的FixedBufferAllocator建议 128 MiB 起步、宿主必须显式decref收到的引用计数值、托管函数数组必须与平台头hosted区段顺序一致。若需支持 URL 依赖则绕过discoverAppFromPath自行解析头部并借助ensurePackage/registerInlinePackage注册——这与 Roc CLI 自身的实现路径完全一致。【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考