Zero 构建指南：运行、构建、交叉编译与剖析 Zero 程序

【免费下载链接】zerolangThe Programming Language for Agents项目地址https://gitcode.com/gh_mirrors/zero54/zerolang点击查看免费下载本篇指南以 ZerolangZero编译器的构建子系统为核心系统讲解 graph 输入的约定、zero run本地开发循环、zero build产物构建、显式 LLVM 实验后端、--json面向工具的构建契约、目标target与能力capability检查、profile 与zero size剖析以及常见构建错误的排查路径。读完本文你将能够为 Zero 程序完成从「检查就绪」到「产出可执行文件/目标文件/LLVM IR」的完整构建闭环并能通过zero doctor、zero size、zero targets等手段解释产物大小、目标支持与失败原因。构建命令的输入约定一切从 graph 开始Zero 的构建体系是 graph 优先graph-first的大多数构建命令接受的输入是「graph 支持的输入」中的一种而不是把文本源码当作编译入口。根据 skill-data/builds.md 的 Inputs 约定可用的输入形态有三种一个直接的.graph或.program-graph产物artifact一个包含zero.toml或zero.json的包目录package directory一个直接指向zero.toml或zero.json的路径。当同一个包根目录下同时存在两种清单时Zero 优先使用zero.toml。日常开发中应只检入一种清单除非你的场景就是在测试「清单优先级」这一行为本身。从zero.graph编译从.0投影刷新对于包package而言zero check、zero build、zero run、zero test、zero size、zero mem等常规命令都从检入的zero.graph存储编译。zero.graph是包的语义图存储与编译输入而.0文件是人类可读的源码投影projection并非常规编译输入——这是理解整个构建模型的关键。当.0投影被人工编辑过后上述命令会先从源码刷新过期的存储stale store并在 stderr 上提示这一行为可以通过环境变量ZERO_STALEfail变成硬错误对应诊断码 RGP008见 native/zero-c/src/main.c 的诊断表。源码中可以看到该模式的实现入口zero在refresh_stale_manifest_graph_input阶段读取getenv(ZERO_STALE)若为fail则直接返回错误见 native/zero-c/src/main.c。这些命令永远不会回写.0文件。因此工作流上的取舍非常明确需要 CI 或评审在投影漂移时直接失败用zero verify-projection仅在需要重新生成人类可读投影时才用zero export当已经处于包目录内部时可以省略输入参数命令默认作用于当前目录。zero check # 默认输入为当前目录 zero run -- input.txt zero run examples/hello.graph zero run examples/cli-file.graph -- input.txt--之后的所有参数都会被传递给 Zero 程序本体而不是被zero自己解释。本地开发循环zero runzero run是主机host开发循环的主力命令用于观察程序的实际行为而不是产出文件。它与--参数传递配合适合「改图、跑一次、看输出」的快速迭代zero run zero run -- input.txt zero run examples/hello.graph zero run examples/cli-file.graph -- input.txt从 native/zero-c/src/cli_help.c 中可以看到zero run的完整用法它同样支持--backend direct|llvm|direct-emitter、--target target、--profile ...、--release profile与--out file。也就是说即使在「运行」阶段你也可以显式指定目标与 profile从而验证某个交叉目标或最小体积配置下的行为。产物构建zero build 与直接发射器当用户索要的是「一个构建产物」时使用zero build。它是可执行文件、目标文件、LLVM IR、交叉目标产物和 CI 输出的常规命令。Zero 使用**直接发射器direct emitters**来产出目标文件与可执行文件而不是经由中间 C 代码再编译被移除的 generated-C 后端不是一个可回退路径fallback。zero build --emit exe --out .zero/out/app zero build --emit obj --out .zero/out/app.o zero build --emit exe examples/hello.graph --out .zero/out/hello zero build --emit obj examples/hello.graph --out .zero/out/hello.o--emit支持exe、obj与llvm-ir--out指定产物路径。--backend可选值包括direct、llvm或具体的直接发射器名称zero在 native/zero-c/src/backend_family.c 中把请求解析为 direct 或 llvm 两类后端族未知请求会产出「unknown backend」诊断并提示可用的取值集合one of direct, llvm, or a direct emitter name。产物与目标的一次性组合zero build可以在同一命令中同时指定 emit 类型、目标与 profile例如把examples/memory-package交叉构建为 Linux musl 可执行文件并输出结构化 JSONzero build --json --target linux-musl-x64 examples/memory-package常用的 JSON 字段包括artifact产物路径、sizeBytes大小字节数、toolchain工具链事实、releaseTargetContract发布目标契约、选中的目标事实、链接器风格linker flavor以及 sysroot 状态。这些字段是工具CI 脚本、编辑器、Agent读取构建结果的稳定契约。LLVM 后端显式、实验性、不兜底Zero 的 LLVM 后端只在请求显式时使用并且是实验性的它不是默认后端它不具备 release 资格不参与发布契约文本 IR 可以通过--emit llvm-ir检查主机可执行文件的构建需要一个就绪的 clang 工具链。LLVM 后端当前能正确降低lower的代码子集是标量代码、直接调用、分支、循环、原始定长数组primitive fixed arrays、字节视图byte views、只读字符串以及std.mem中的原始辅助函数。zero build --backend llvm --emit llvm-ir examples/hello.graph --out .zero/out/hello.ll zero build --backend llvm --emit exe examples/hello.graph --out .zero/out/hello-llvm zero run --backend llvm examples/hello.graph从源码看LLVM 的可执行构建会做 clang 就绪性检查z_llvm_native_executable_ready会验证clang或ZERO_LLVM_CLANG指定的驱动是否可执行失败时给出诊断并附带backend_blocker事实见 native/zero-c/src/llvm_toolchain.c。因此若要在主机上--emit exe需要先准备好 clang 工具链纯文本 IR 产出则没有此依赖。--json面向工具的构建契约当工具需要读取精确的构建字段时使用--json。JSON 是「工具的契约」而不是人类阅读的默认体验——人类与交互式 Agent 应当优先使用简洁的文本输出仅在程序需要稳定结构化数据时再切 JSONzero build --json --target linux-musl-x64 examples/memory-package构建 JSON 报告 profile 与目标的就绪情况重要的字段包括profileSemantics、profileBudget、releaseTargetContract、targetToolchains、compileTime以及重复构建的哈希策略数据用于产物确定性见 docs/articles/cli-reference.md 的 Run And Build 一节。图优先包patch、export、import、status当 Agent 正在编写一个仓库图包repository graph package时应当直接 patch 包的 graph然后用常规的 build/run 命令。这些命令从zero.graph编译不要求.0投影必须存在zero patch --op addMain zero run zero build --out .zero/out/app当人类需要检入的.0投影时用zero export当人类编辑了投影之后下一次 graph 存储编译会自动刷新存储也可以显式运行zero import来刷新zero status报告当前使用的存储格式text 或 binary。派生的 final-MIR 缓存zero build、zero run、zero test、zero size、zero mem命令会在 native 缓存中维护一个派生的 final-MIR 缓存缓存键由图哈希、编译器版本、目标、emit 类型和后端请求共同决定。Agent不应该 patch.zmir文件JSON 输出会通过mappedFinalMir行报告缓存复用情况相关字段生成逻辑见 native/zero-c/src/main.c。独立的 .program-graph 交换产物如果另一个工具交给你一个独立的.program-graph文件普通的zero build和zero run都可以把它当作交换产物interchange artifact来校验。但不要为普通的包循环创建独立 graph 产物应使用包路径让编译器直接读取包内的zero.graph。目标与能力交叉编译之前的检查交叉构建之前先检查目标名称与能力事实zero targets zero check --target linux-musl-x64 examples/memory-package zero inspect --target linux-musl-x64 examples/memory-package文档化的 native 目标名称见 docs/articles/building-from-source.md包括darwin-arm64、darwin-x64linux-arm64、linux-musl-arm64、linux-musl-x64、linux-x64win32-arm64.exe、win32-x64.exe能力是目标事实不是默认假设Zero 不假设每个目标都能做文件系统、网络、进程、时间或随机数操作——这些是显式的目标事实target facts。从源码看能力集合来自memory、stdio、args、env、fs、net、proc、time、rand、web等条目主机目标额外享受args/env/fs/net/proc的主机能力见 native/zero-c/src/target.c 与 native/zero-c/src/target.c。诸如进程参数、环境变量、文件系统、网络、proc 这类「托管hostedAPI」是目标门控的一个非主机non-host目标可能拒绝那些在主机上能通过的代码。例如std.fs在一个无法提供文件系统支持的目标上zero check --target ...会报诊断TAR002而不是悄悄改变行为详见 docs/articles/target-capabilities.md。sysroot缺失时指明所需环境变量跨目标的 C 互操作必须使用显式的包元数据、vendor 输入或目标 sysroot编译器不会为外来目标悄悄复用主机头文件与库。zero在 native/zero-c/src/target.c 中实现 sysroot 检测需要 sysroot 的目标通过ZERO_SYSROOT_TARGET形式的环境变量定位路径变量名由目标的 zig target 名规范化而来并报告not-required / missing / host-leakage / present四种状态路径若落在/usr/include或/usr/lib会被判定为 host-leakage。构建 JSON 中的 sysroot 状态字段正是这一检测的输出缺失时它会告诉你需要设置哪一个ZERO_SYSROOT_*变量。剖析配置profile 与 zero sizeprofile 名称常见 profile 名称是debug、dev、release-fast、release-small、tiny与audit用法串见 native/zero-c/src/cli_help.czero build/zero run/zero size均接受--profile与--release。其中几个 profile 的语义契约如下扩展自 docs/articles/optimization.mdProfile适用场景契约debug需要诊断信息与本地符号保留诊断/调试元数据fast吞吐量优先于最小体积在当前直接代码生成能力内为速度优化small常规发布形态按需使用的 helper 与确定性产物tiny产物大小是首要约束最小运行时元数据与严格的 helper 预算zero build --profile release-small examples/hello.graph zero size --profile tiny examples/hello.graphzero size让「保留」可见用zero size解释产物中保留的函数、段、字面量、运行时 shim、导入、调试元数据以及优化提示。zero size --json输出sizeBreakdown、retentionReasons、optimizationHints等字段retentionReasons可以用来回答「为什么这个 helper / 字面量 / 调试元数据块还留在产物里」这类问题zero size --json examples/fixed-vec.graph zero size --json --target linux-musl-x64 examples/memory-package当问题专门针对显式 LLVM 后端时使用zero size --backend llvm报告会包含 LLVM 目标三元组、优化级别、保留的运行时/helper 事实、工具链就绪状态以及 direct 与 LLVM 的对比行。故障排查doctor 与构建诊断现象含义与处理zero doctor检查主机与目标就绪状态zero doctor --json报告llvmToolchain就绪状态用于显式 LLVM 主机构建LLVM JSON 中的backendLifecycle让工具区分「显式实验性就绪」与「release 支持」而不是把实验性能力当成正式契约BLD003请求了旧的后端标志old backend flag移除它即可BLD004backendBlocker.backend: llvm所选 LLVM 产物、目标、命令、MIR 子集或 clang 工具链尚未就绪缺失的 sysroot 事实指明需要设置的ZERO_SYSROOT_*变量不支持的目标显式失败而不是静默选择另一个后端BLD003与BLD004的诊断定义位于 native/zero-c/src/main.cBLD004的语义是「所选后端无法为这个源码、目标、对象格式、架构或产物种类构建」它在对象/可执行发射之前就进行 target-aware 可构建性检查并以结构化 blocker 事实报告后端限制。这正是 Zero 构建哲学的落点不支持的目标组合应该以诊断失败而不是无声回退。这也呼应了 docs/articles/cross-compilation.md 的结论Zero 交叉编译从图事实、目标事实与直接发射器出发不支持的目标或特性组合以诊断报错而不是静默兜底。结语Zero 的构建体系把「图优先」贯彻到了编译的每一步输入是 graph 或包清单编译源是zero.graph.0投影只服务人类审查zero build用直接发射器产出 exe/obj/LLVM IR显式 LLVM 后端有清晰的实验边界目标与能力是显式事实sysroot 与工具链就绪状态都可以通过 JSON 精确读取zero size让「为什么这个产物这么大」成为可回答的问题。掌握run、build、targets、size、doctor这条命令链就掌握了 Zero 程序从源码到产物的完整生命周期。更完整的命令分组与 JSON 契约可继续阅读 docs/articles/cli-reference.md交叉构建细节见 docs/articles/cross-compilation.mdprofile 与内存剖析见 docs/articles/optimization.md。赞分享【免费下载链接】zerolangThe Programming Language for Agents项目地址https://gitcode.com/gh_mirrors/zero54/zerolang点击查看免费下载相关推荐在 FreeBSD 上构建 .NET CoreCLRDocker 交叉编译、Linux 交叉编译与直接构建全指南在 FreeBSD 上构建 .NET CoreCLRDocker 交叉编译、Linux 交叉编译与直接构建全指南 本文基于 dotnet/runtime 仓库语言运行时标准库JIT编译编译器从源码构建 Velero 完整实战指南编译、交叉编译、镜像制作、测试与运行从源码构建 Velero 完整实战指南编译、交叉编译、镜像制作、测试与运行 本指南以 Velero 项目 v0.8.1 官方文档当时项目还叫 Heptio云原生灾备存储后端TVM Hexagon 后端运行时编译与部署指南从 x86 交叉编译到 Android/Hexagon 目标构建TVM Hexagon 后端运行时编译与部署指南从 x86 交叉编译到 Android/Hexagon 目标构建 本篇技术指南以 src/runtime/he编译器深度学习模型优化上一篇FlutterFire离线同步带宽优化减少Firebase数据传输量下一篇PHP_CodeSniffer标准对比PSR1/PSR2/PSR12与自定义标准选择策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考