跳转到内容
语言参考Zig 0.17.0官方原文

一次 Zig 编译划分为多个模块。每个模块是 Zig 源文件的集合,其中一个文件为模块的根源文件。每个模块可以依赖任意数量的其他模块,形成有向图;模块之间允许循环依赖。如果模块 A 依赖模块 B,那么 A 中任意 Zig 源文件都可以通过模块名称调用 @import,导入 B 的根源文件。本质上,模块是导入某个 Zig 源文件的别名;该文件可以位于文件系统中完全不同的位置。

使用 zig build-exe 编译的简单 Zig 程序有两个关键模块:包含你的代码、称为“main”或“root”的模块,以及标准库。你的模块以 "std" 为名依赖标准库模块,因此可以写出 @import("std")。实际上,Zig 编译中的每个模块,包括标准库本身,都隐式以 "std" 为名依赖标准库模块。

“根模块”,即 zig build-exe 示例中由你提供的模块,具有特殊性质。它与标准库一样,隐式对所有模块(包括自身)开放,名称为 "root"。因此,@import("root") 始终等价于对你的“main”源文件执行 @import;该文件通常但不一定名为 main.zig。

源文件结构体

每个 Zig 源文件都隐式构成一个 struct 声明,可以想象文件内容整体包围在 struct { ... } 中。因此,文件顶层不仅允许声明,也允许字段:

TopLevelFields.zig
//! 由于此文件包含字段,表示它是预期会被实例化的类型,因此按照约定
//! 使用 TitleCase 而非 snake_case 命名。
foo: u32,
bar: u64,
/// 可以使用 `@This()` 引用该结构体类型。在包含字段的文件中,通常会在此
/// 为类型命名,以便本文件内其他声明引用。
const TopLevelFields = @This();
pub fn init(val: u32) TopLevelFields {
return .{
.foo = val,
.bar = val * 10,
};
}

这样的文件可以像其他 struct 类型一样实例化。文件内部可使用 @This 引用自身的“根结构体类型”。

文件与声明发现

Zig 关心一段代码是否经过语义分析,即编译器是否“查看”它。需要分析哪些代码,取决于从某个起点“发现”了哪些文件与声明。发现过程遵循以下简单递归规则:

  • 分析 @import 调用时,会分析被导入的文件。
  • 分析某个类型(包括文件)时,会分析其中的全部 comptime 和 export 声明。
  • 分析某个类型(包括文件)时,如果正在编译测试,且类型位于此次编译的根模块中,还会分析该类型中的全部 test 声明。
  • 分析对具名声明的引用(即使用)时,会分析被引用声明。声明与顺序无关,因此引用可以位于被引用声明之前、之后,甚至完全不同的文件中。

以上规则定义了 Zig 如何发现文件和声明。现在只需理解此过程从哪里开始。

起点是标准库根文件:每次 Zig 编译都从分析 lib/std/std.zig 开始。该文件包含导入 lib/std/start.zig 的 comptime 声明,而后者通过 @import("root") 引用“根模块”。因此,你提供的主模块根源文件实际上也是一个根,因为标准库始终会引用它。

有时需要确保发现特定声明,尤其是 test 或 export 声明。根据上述规则,常见策略是在 comptime 或 test 块中使用 @import:

force_file_discovery.zig
comptime {
// 只要本文件被发现,就会确保始终发现 'api.zig'。
// 当 'api.zig' 包含重要导出声明时,这很有用。
_ = @import("api.zig");
// 也可以让某个文件中的声明,仅在满足某个编译时条件时才导出。
// 此时可以在这里使用 `if` 语句:
if (builtin.os.tag == .windows) {
_ = @import("windows_api.zig");
}
}
test {
// 只要本文件被发现,且正在编译测试,就会确保发现 'tests.zig'。
// 当 'tests.zig' 包含必须运行的测试时,这很有用。
_ = @import("tests.zig");
// 也可以让某个文件中的测试,仅在满足某个编译时条件时运行。
// 此时可以在这里使用 `if` 语句:
if (builtin.os.tag == .windows) {
_ = @import("windows_tests.zig");
}
}
const builtin = @import("builtin");

根模块的特殊声明

根模块的根源文件始终可以通过 @import("root") 访问,因此包括 Zig 标准库在内的一些库,会将它作为程序向库暴露“全局”信息的位置。Zig 标准库会在此文件中查找若干声明。

入口点

构建可执行文件时,此文件中最重要的查找项是程序入口点。通常它是名为 main 的函数,std.start 在完成重要初始化工作后立即调用它。

另一种方式是提供名为 _start 的声明,例如 pub const _start = {};,以禁用默认的 std.start 逻辑,让根源文件按需导出底层入口点。

entry_point.zig
/// `std.start` 使用 `@import("root")` 导入本文件,并将此声明用作程序的
/// 用户提供入口点。它可以返回以下任意类型:
/// * `void`
/// * `E!void`,其中 `E` 为任意错误集合
/// * `u8`
/// * `E!u8`,其中 `E` 为任意错误集合
/// 返回 `void` 值会以状态码 0 退出。
/// 返回 `u8` 值会以指定状态码退出。
/// 返回错误值会打印错误返回追踪,并以状态码 1 退出。
pub fn main() void {
std.debug.print("Hello, World!\n", .{});
}
// 取消下方声明的注释会抑制通常的 std.start 逻辑,
// 从而忽略上面的 `main` 声明。
//pub const _start = {};
const std = @import("std");
命令行
$ zig build-exe entry_point.zig
$ ./entry_point
Hello, World!

如果此次 Zig 编译链接 libc,main 函数也可以选择使用 export fn,并匹配 C main 函数的签名:

libc_export_entry_point.zig
pub export fn main(argc: c_int, argv: [*]const [*:0]const u8) c_int {
const args = argv[0..@intCast(argc)];
std.debug.print("Hello! argv[0] is '{s}'\n", .{args[0]});
return 0;
}
const std = @import("std");
命令行
$ zig build-exe libc_export_entry_point.zig -lc
$ ./libc_export_entry_point
Hello! argv[0] is './libc_export_entry_point'

在某些情况下,std.start 还可以使用 wWinMain、EfiMain 等其他入口点声明。具体规则参见 lib/std/start.zig 逻辑。

标准库选项

标准库还会在根模块的根源文件中查找名为 std_options 的声明。如果存在,它应当是 std.Options 类型的结构体,使程序能够定制标准库的部分功能,例如 std.log 实现。

std_options.zig
/// 此声明允许程序覆盖标准库的某些行为。
/// 完整可用选项参见 `std.Options` 文档。
pub const std_options: std.Options = .{
// 默认情况下,安全构建模式中的标准库会为程序安装段错误处理器,
// 在发生段错误时打印有帮助的栈追踪。这里可以禁用,甚至可以在
// 不安全的构建模式中启用它。
.enable_segfault_handler = true,
// 这是 `std.log` 使用的日志函数。
.logFn = myLogFn,
};
fn myLogFn(
comptime level: std.log.Level,
comptime scope: @EnumLiteral(),
comptime format: []const u8,
args: anytype,
) void {
// 此处可以执行任意所需操作!
// ……不过这里还是调用默认实现。
std.log.defaultLog(level, scope, format, args);
}
const std = @import("std");

panic 处理器

Zig 标准库会在根模块的根源文件中查找名为 panic 的声明。如果存在,它应当是一个命名空间,其中的声明提供不同的 panic 处理器。

该命名空间的基础实现参见 std.debug.simple_panic。

可以通过 std.debug.FullPanic 轻松覆盖 panic 处理器输出消息的方式,同时保留默认启用、带格式化输出的安全检查 panic:

panic_handler.zig
pub fn main() void {
@setRuntimeSafety(true);
var x: u8 = 255;
// 让这个整数溢出!
x += 1;
}
pub const panic = std.debug.FullPanic(myPanic);
fn myPanic(msg: []const u8, first_trace_addr: ?usize) noreturn {
_ = first_trace_addr;
std.debug.print("Panic! {s}\n", .{msg});
std.process.exit(1);
}
const std = @import("std");
命令行
$ zig build-exe panic_handler.zig
$ ./panic_handler
Panic! integer overflow