跳转到内容
标准库Zig 0.17.1官方原文
源码std/zig.zig

第 1 行

Zig 编译器构建产物有一部分以源码形式分发。 这些源码位于此处。相关 API 按原样提供, 没有任何 API 保证。

std.zig.Allocator

别名

第 11 行

别名目标 std.mem.Allocator

std.zig.allocPrintCmd

函数

第 1376 行

已弃用

pub fn allocPrintCmd(gpa: Allocator, argv: []const []const u8, options: AllocPrintCmdOptions) Allocator.Error![]u8

参数

gpa: Allocator
argv: []const []const u8
options: AllocPrintCmdOptions

错误

OutOfMemory

std.zig.AllocPrintCmdOptions

容器

第 1369 行

已弃用

字段

cwd: ?[]const u8 = null
parent_env: ?*const std.process.Environ.Map = null
child_env: ?*const std.process.Environ.Map = null

std.zig.assert

别名

第 8 行

别名目标 std.debug.assert

std.zig.Ast

别名

第 30 行

别名目标 std.zig.Ast

std.zig.AstGen

别名

第 31 行

别名目标 std.zig.AstGen

std.zig.AstRlAnnotate

别名

第 37 行

别名目标 std.zig.AstRlAnnotate

std.zig.binNameAlloc

函数

第 182 行

返回 Zig 编译器生成的二进制文件的标准文件系统基本文件名。

pub fn binNameAlloc(allocator: Allocator, options: BinNameOptions) error{OutOfMemory}![]u8

参数

allocator: Allocator
options: BinNameOptions

错误

OutOfMemory

std.zig.BinNameOptions

容器

第 170 行

字段

root_name: []const u8
cpu_arch: std.Target.Cpu.Arch
os_tag: std.Target.Os.Tag
ofmt: std.Target.ObjectFormat
abi: std.Target.Abi
output_mode: std.lang.OutputMode
link_mode: ?std.lang.LinkMode = null
version: ?std.SemanticVersion = null

std.zig.build_zig_basename

常量

第 58 行

std.zig.buildExeSubprocess

函数

第 1858 行

假定 argv 包含 --listen=-,且子进程为 zig build-exe。

结果路径通过 gpa 分配。

pub fn buildExeSubprocess( gpa: Allocator, io: Io, options: BuildExeSubprocessOptions, ) BuildExeSubprocessError!BuildExeSubprocessResult

参数

错误

AlreadyReported

错误消息已记录。

Canceled Cancelable

调用方请求停止异步操作。

FailedButCacheIntact

错误消息已记录,源码文件已添加到 Cache.Manifest。

OutOfMemory Error

std.zig.BuildExeSubprocessError

错误集合

第 1842 行

错误

AlreadyReported

错误消息已记录。

Canceled Cancelable

调用方请求停止异步操作。

FailedButCacheIntact

错误消息已记录,源码文件已添加到 Cache.Manifest。

OutOfMemory Error

std.zig.BuildExeSubprocessOptions

容器

第 1826 行

字段

argv: []const []const u8
cache_root: Cache.Directory
root_name: []const u8
environ_map: ?*std.process.Environ.Map = null
cache_manifest: ?*Cache.Manifest = null
arch_os_abi: ?[]const u8 = null
cpu_features: ?[]const u8 = null
progress_node: std.Progress.Node = .none
skip_log_cmdline_on_compile_errors: bool = false
error_bundle: ?*ErrorBundle = null

若提供此项,则将编译错误发送到此处;否则打印到 stderr。 必须为已初始化的 ErrorBundle;更新之前会先将其清空。

std.zig.BuildExeSubprocessResult

容器

第 1849 行

字段

received_fs_inputs: bool
cache_hit: bool
path: Cache.Path

std.zig.BuildId

容器

第 280 行

字段

none
fast
uuid
sha1
md5
hexstring: HexString

std.zig.BuildId.eql

函数

第 288 行

pub fn eql(a: BuildId, b: BuildId) bool

参数

std.zig.BuildId.format

函数

第 356 行

pub fn format(id: BuildId, writer: *Writer) Writer.Error!void

参数

id: BuildId
writer: *Writer

错误

WriteFailed

详细诊断信息见 Writer 实现。

用法示例

test format {
    try std.testing.expectFmt("none", "{f}", .{@as(BuildId, .none)});
    try std.testing.expectFmt("fast", "{f}", .{@as(BuildId, .fast)});
    try std.testing.expectFmt("uuid", "{f}", .{@as(BuildId, .uuid)});
    try std.testing.expectFmt("sha1", "{f}", .{@as(BuildId, .sha1)});
    try std.testing.expectFmt("md5", "{f}", .{@as(BuildId, .md5)});
    try std.testing.expectFmt("0x", "{f}", .{BuildId.initHexString("")});
    try std.testing.expectFmt("0x1234cdef", "{f}", .{BuildId.initHexString("\x12\x34\xcd\xef")});
}

std.zig.BuildId.HexString

容器

第 299 行

字段

bytes: [32]u8
len: u8

std.zig.BuildId.HexString.toSlice

函数

第 304 行

结果为字节值,并非十六进制编码。

pub fn toSlice(hs: *const HexString) []const u8

参数

hs: *const HexString

std.zig.BuildId.initHexString

函数

第 311 行

输入为字节值,不是十六进制编码。 断言 bytes 可放入 HexString。

pub fn initHexString(bytes: []const u8) BuildId

参数

bytes: []const u8

std.zig.BuildId.parse

函数

第 321 行

将 UTF-8 文本转换为 BuildId。

pub fn parse(text: []const u8) !BuildId

参数

text: []const u8

用法示例

test parse {
    try std.testing.expectEqual(BuildId.md5, try parse("md5"));
    try std.testing.expectEqual(BuildId.none, try parse("none"));
    try std.testing.expectEqual(BuildId.fast, try parse("fast"));
    try std.testing.expectEqual(BuildId.uuid, try parse("uuid"));
    try std.testing.expectEqual(BuildId.sha1, try parse("sha1"));
    try std.testing.expectEqual(BuildId.sha1, try parse("tree"));

    try std.testing.expect(BuildId.initHexString("").eql(try parse("0x")));
    try std.testing.expect(BuildId.initHexString("\x12\x34\x56").eql(try parse("0x123456")));
    try std.testing.expectError(error.InvalidLength, parse("0x12-34"));
    try std.testing.expectError(error.InvalidCharacter, parse("0xfoobbb"));
    try std.testing.expectError(error.InvalidBuildIdStyle, parse("yaddaxxx"));
}

std.zig.builtin

常量

第 5 行

std.zig.BuiltinFn

别名

第 36 行

别名目标 std.zig.BuiltinFn

std.zig.c_translation

命名空间

第 52 行

std.zig.c_translation.builtins

别名

第 53 行

别名目标 std.zig.c_translation.builtins

std.zig.c_translation.helpers

别名

第 54 行

别名目标 std.zig.c_translation.helpers

std.zig.Cache

别名

第 14 行

别名目标 std.Build.Cache

std.zig.charEscape

函数

第 756 行

按单引号字符串的转义内容打印。

pub fn charEscape(codepoint: u21, w: *Writer) Writer.Error!void

参数

codepoint: u21
w: *Writer

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.zig.ClangCliParam

容器

第 1209 行

在此选择默认值,以缩减 src/clang_options.zon 的大小

字段

name: []const u8
ze: ZigEquivalent = .other
syntax: Syntax = .flag
pd1: bool = true

以 "-" 为前缀

pd2: bool = false

前缀为 "--"

psl: bool = false

前缀为 "/"

std.zig.ClangCliParam.matchEql

函数

第 1329 行

pub fn matchEql(self: @This(), arg: []const u8) u2

参数

self: @This()
arg: []const u8

std.zig.ClangCliParam.matchStartsWith

函数

第 1348 行

pub fn matchStartsWith(self: @This(), arg: []const u8) usize

参数

self: @This()
arg: []const u8

std.zig.ClangCliParam.Syntax

容器

第 1220 行

字段

flag

不带值的标志。

joined

将其唯一值附加在自身之后的选项。

separate

其值紧随其后的选项。

joined_or_separate

既可与非空值连写、也可由值紧随其后的选项。

joined_and_separate

同时与其第一个值连写,并由第二个值紧随其后的选项。

comma_joined

其后跟随多个值的选项,各值以逗号分隔。

remaining_args_joined

会消耗一个可选的连接参数及所有其他剩余参数的选项。

multi_arg: u8

接受多个独立参数的选项。

std.zig.ClangCliParam.ZigEquivalent

容器

第 1239 行

字段

target
o
c
r
m
x
other
positional
l
ignore
driver_punt
pic
no_pic
pie
no_pie
lto
no_lto
unwind_tables
no_unwind_tables
asynchronous_unwind_tables
no_asynchronous_unwind_tables
nostdlib
nostdlib_cpp
shared
rdynamic
wl
wp
preprocess_only
asm_only
optimize
debug
gdwarf32
gdwarf64
sanitize
no_sanitize
sanitize_trap
no_sanitize_trap
linker_script
dry_run
verbose
for_linker
linker_input_z
lib_dir
mcpu
dep_file
dep_file_to_stdout
framework_dir
framework
nostdlibinc
red_zone
no_red_zone
omit_frame_pointer
no_omit_frame_pointer
function_sections
no_function_sections
data_sections
no_data_sections
builtin
no_builtin
color_diagnostics
no_color_diagnostics
stack_check
no_stack_check
stack_protector
no_stack_protector
strip
exec_model
emit_llvm
sysroot
entry
force_undefined_symbol
weak_library
weak_framework
headerpad_max_install_names
compress_debug_sections
install_name
undefined
force_load_objc
mingw_unicode_entry_point
san_cov_trace_pc_guard
san_cov
no_san_cov
rtlib
static
dynamic
version
patchable_function_entry

std.zig.Client

别名

第 22 行

别名目标 std.zig.Client

std.zig.Color

容器

第 63 行

字段

auto

自动检测流是否支持终端颜色。

off

强制启用颜色。

on

禁用颜色。

std.zig.Color.settingFromEnvironment

函数

第 82 行

根据 NO_COLOR 和 CLICOLOR_FORCE 环境变量 确定是否使用颜色。WASI 上始终禁用颜色,依据为 https://github.com/WebAssembly/WASI/issues/162

pub fn settingFromEnvironment(environ_map: *const std.process.Environ.Map) Color

参数

environ_map: *const std.process.Environ.Map

std.zig.Color.terminalMode

函数

第 71 行

pub fn terminalMode(color: Color) ?Io.Terminal.Mode

参数

color: Color

std.zig.CompressDebugSections

容器

第 391 行

字段

none
zlib
zstd

std.zig.default_local_zig_cache_basename

常量

第 57 行

std.zig.Dir

别名

第 16 行

别名目标 std.Io.Dir

std.zig.Directories

容器

第 1470 行

字段

cwd: []const u8

introspect.getResolvedCwd 返回的字符串。通常为绝对路径, 但 WASI 上改为空字符串,因为 WASI 没有绝对路径。

zig_lib: Cache.Directory

Zig 的“lib”目录。 zig_lib.path 已解析(resolvePath),或在 cwd 情况下为 null。 保证该路径不同于 global_cache 和 local_cache。

global_cache: Cache.Directory

全局 Zig 缓存目录。 global_cache.path 已经解析(resolvePath),或为表示当前工作目录的 null。

local_cache: Cache.Directory

本地 Zig 缓存目录。 local_cache.path 已解析(resolvePath),或为 null 以表示当前工作目录。 它可以与 global_cache 相同。

build_root: Cache.Directory

包含 build.zig 的目录。使用构建系统时, 此路径由构建系统提供;否则为 null, 表示 cwd。

std.zig.Directories.deinit

函数

第 1490 行

pub fn deinit(dirs: *Directories, io: Io) void

参数

dirs: *Directories
io: Io

std.zig.Directories.getLocalCacheDirectory

函数

第 1580 行

fn getLocalCacheDirectory( arena: Allocator, io: Io, cwd: []const u8, global_cache: Cache.Directory, local_cache_strat: LocalCacheStrategy, ) Cache.Directory

参数

arena: Allocator
io: Io
cwd: []const u8
global_cache: Cache.Directory
local_cache_strat: LocalCacheStrategy

std.zig.Directories.getPreopen

函数

第 1599 行

fn getPreopen(preopens: std.process.Preopens, name: []const u8) Cache.Directory

参数

preopens: std.process.Preopens
name: []const u8

std.zig.Directories.init

函数

第 1535 行

遇到错误时使用 std.process.fatal。

pub fn init(arena: Allocator, io: Io, options: InitOptions) Directories

参数

arena: Allocator
io: Io
options: InitOptions

std.zig.Directories.InitOptions

容器

第 1520 行

字段

override_zig_lib: ?[]const u8
override_global_cache: ?[]const u8
build_root: ?[]const u8
local_cache_strat: LocalCacheStrategy
preopens: std.process.Preopens
self_exe_path: switch (builtin.target.os.tag) {
    .wasi => void,
    else => []const u8,
}
environ_map: *const std.process.Environ.Map
cwd: []const u8

std.zig.Directories.LocalCacheStrategy

容器

第 1514 行

字段

override: []const u8
search
global

std.zig.Directories.openUnresolved

函数

第 1608 行

pub fn openUnresolved( arena: Allocator, io: Io, cwd: []const u8, unresolved_path: []const u8, thing: enum { @"zig lib", @"global cache", @"local cache", @"build root" }, ) Cache.Directory

参数

arena: Allocator
io: Io
cwd: []const u8
unresolved_path: []const u8
thing: enum { @"zig lib", @"global cache", @"local cache", @"build root" }

std.zig.Directories.withoutLocalCache

函数

第 1504 行

返回一个将 local_cache 替换为 global_cache 的 Directories,供子编译 使用,例如 compiler_rt。不要对返回的 Directories 调用 deinit; 它与 dirs 共享句柄。

pub fn withoutLocalCache(dirs: Directories) Directories

参数

dirs: Directories

std.zig.EmitArtifact

容器

第 1180 行

编译器可生成的所有产物类型。

字段

bin
@"asm"
implib
llvm_ir
llvm_bc
docs
pdb
h

std.zig.EmitArtifact.cacheName

函数

第 1193 行

使用 Server 与编译器通信时,编译器会将请求的产物放在 输出目录下的路径中,其路径命名规则由此函数确定。 返回的字符串由 gpa 分配,所有权归调用者。

pub fn cacheName(ea: EmitArtifact, gpa: Allocator, opts: BinNameOptions) Allocator.Error![]const u8

参数

错误

OutOfMemory

std.zig.EnvVar

容器

第 955 行

收集 Zig 可能检查的所有环境变量, 以便对其反射,并通过 zig env 打印。

字段

ZIG_GLOBAL_CACHE_DIR
ZIG_LOCAL_CACHE_DIR
ZIG_LOCAL_PKG_DIR
ZIG_LIB_DIR
ZIG_LIBC
ZIG_BUILD_ERROR_STYLE
ZIG_BUILD_MULTILINE_ERRORS
ZIG_BUILD_SUMMARY
ZIG_VERBOSE_LINK
ZIG_VERBOSE_CC
ZIG_VERBOSE_CMD
ZIG_DEBUG_CMD
ZIG_IS_DETECTING_LIBC_PATHS
ZIG_IS_AVOIDING_CALLING_ITSELF
NIX_CFLAGS_COMPILE
NIX_CFLAGS_LINK
NIX_LDFLAGS
C_INCLUDE_PATH
CPLUS_INCLUDE_PATH
LIBRARY_PATH
CC
PKG_CONFIG
NO_COLOR
CLICOLOR_FORCE
XDG_CACHE_HOME
LOCALAPPDATA
HOME
PROGRAMDATA
HOMEBREW_PREFIX

std.zig.EnvVar.get

函数

第 1000 行

pub fn get(ev: EnvVar, map: *const std.process.Environ.Map) ?[]const u8

参数

ev: EnvVar
map: *const std.process.Environ.Map

std.zig.EnvVar.isSet

函数

第 996 行

pub fn isSet(ev: EnvVar, map: *const std.process.Environ.Map) bool

参数

ev: EnvVar
map: *const std.process.Environ.Map

std.zig.ErrorBundle

别名

第 20 行

别名目标 std.zig.ErrorBundle

std.zig.fatal

别名

第 15 行

别名目标 std.process.fatal

std.zig.findLineColumn

函数

第 127 行

pub fn findLineColumn(source: []const u8, byte_offset: usize) Loc

参数

source: []const u8
byte_offset: usize

std.zig.findZigLibDir

函数

第 1642 行

目录句柄及路径均为新分配的资源,现由调用方拥有。

pub fn findZigLibDir(gpa: Allocator, io: Io) !Cache.Directory

参数

gpa: Allocator
io: Io

std.zig.findZigLibDirFromSelfExe

函数

第 1652 行

目录句柄及路径均为新分配的资源,现由调用方拥有。

pub fn findZigLibDirFromSelfExe( allocator: Allocator, io: Io, cwd_path: []const u8, self_exe_path: []const u8, ) error{ OutOfMemory, FileNotFound }!Cache.Directory

参数

allocator: Allocator
io: Io
cwd_path: []const u8

getResolvedCwd 的返回值。 作为参数传入,以避免无意义的重复调用。

self_exe_path: []const u8

错误

FileNotFound
OutOfMemory

std.zig.fmtChar

函数

第 527 行

返回用于转义单引号 Zig 字符串的格式化器。

pub fn fmtChar(c: u21) std.fmt.Alt(u21, charEscape)

参数

c: u21

用法示例

test fmtChar {
    try std.testing.expectFmt("c \\u{26a1}", "{f} {f}", .{ fmtChar('c'), fmtChar('⚡') });
}

std.zig.fmtId

函数

第 443 行

返回 Zig 标识符的 Formatter,必要时使用 @"" 语法转义。

另请参见 fmtIdFlags。

pub fn fmtId(bytes: []const u8) FormatId

参数

bytes: []const u8

用法示例

test fmtId {
    const expectFmt = std.testing.expectFmt;
    try expectFmt("@\"while\"", "{f}", .{fmtId("while")});
    try expectFmt("@\"while\"", "{f}", .{fmtIdFlags("while", .{ .allow_primitive = true })});
    try expectFmt("@\"while\"", "{f}", .{fmtIdFlags("while", .{ .allow_underscore = true })});
    try expectFmt("@\"while\"", "{f}", .{fmtIdFlags("while", .{ .allow_primitive = true, .allow_underscore = true })});

    try expectFmt("hello", "{f}", .{fmtId("hello")});
    try expectFmt("hello", "{f}", .{fmtIdFlags("hello", .{ .allow_primitive = true })});
    try expectFmt("hello", "{f}", .{fmtIdFlags("hello", .{ .allow_underscore = true })});
    try expectFmt("hello", "{f}", .{fmtIdFlags("hello", .{ .allow_primitive = true, .allow_underscore = true })});

    try expectFmt("@\"type\"", "{f}", .{fmtId("type")});
    try expectFmt("type", "{f}", .{fmtIdFlags("type", .{ .allow_primitive = true })});
    try expectFmt("@\"type\"", "{f}", .{fmtIdFlags("type", .{ .allow_underscore = true })});
    try expectFmt("type", "{f}", .{fmtIdFlags("type", .{ .allow_primitive = true, .allow_underscore = true })});

    try expectFmt("@\"_\"", "{f}", .{fmtId("_")});
    try expectFmt("@\"_\"", "{f}", .{fmtIdFlags("_", .{ .allow_primitive = true })});
    try expectFmt("_", "{f}", .{fmtIdFlags("_", .{ .allow_underscore = true })});
    try expectFmt("_", "{f}", .{fmtIdFlags("_", .{ .allow_primitive = true, .allow_underscore = true })});

    try expectFmt("@\"i123\"", "{f}", .{fmtId("i123")});
    try expectFmt("i123", "{f}", .{fmtIdFlags("i123", .{ .allow_primitive = true })});
    try expectFmt("@\"4four\"", "{f}", .{fmtId("4four")});
    try expectFmt("_underscore", "{f}", .{fmtId("_underscore")});
    try expectFmt("@\"11\\\"23\"", "{f}", .{fmtId("11\"23")});
    try expectFmt("@\"11\\x0f23\"", "{f}", .{fmtId("11\x0F23")});

    try expectFmt("@\"\\r\\\"\\n\\xff😎\\xe2\\x80\\xa8\"", "{f}", .{fmtId("\r\"\n\xFF😎\u{2028}")});

    // 严格来说,这些内容目前在 Zig 中不合法。
    try expectFmt("@\"\"", "{f}", .{fmtId("")});
    try expectFmt("@\"\\x00\"", "{f}", .{fmtId("\x00")});
}

std.zig.fmtIdFlags

函数

第 450 行

返回 Zig 标识符的 Formatter,必要时用 @"" 语法转义。

另见 fmtId。

pub fn fmtIdFlags(bytes: []const u8, flags: FormatId.Flags) FormatId

参数

bytes: []const u8
flags: FormatId.Flags

std.zig.fmtIdP

函数

第 458 行

pub fn fmtIdP(bytes: []const u8) FormatId

参数

bytes: []const u8

std.zig.fmtIdPU

函数

第 454 行

pub fn fmtIdPU(bytes: []const u8) FormatId

参数

bytes: []const u8

std.zig.fmtString

函数

第 522 行

返回用于转义双引号 Zig 字符串的格式化器。

pub fn fmtString(bytes: []const u8) std.fmt.Alt([]const u8, stringEscape)

参数

bytes: []const u8

用法示例

test fmtString {
    try std.testing.expectFmt("\\x0f", "{f}", .{fmtString("\x0f")});
    try std.testing.expectFmt(
        \\" \\ hi \x07 \x11 \" derp '"
    , "\"{f}\"", .{fmtString(" \\ hi \x07 \x11 \" derp '")});
}

std.zig.FormatId

容器

第 498 行

字段

bytes: []const u8
flags: Flags

std.zig.FormatId.Flags

容器

第 501 行

字段

allow_primitive: bool = false
allow_underscore: bool = false

std.zig.FormatId.format

函数

第 507 行

将字符串作为 Zig 标识符打印,必要时使用 @"" 语法转义。

pub fn format(ctx: FormatId, writer: *Writer) Writer.Error!void

参数

ctx: FormatId
writer: *Writer

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.zig.getResolvedCwd

函数

第 1454 行

类似 std.process.currentPathAlloc,但还使用 Dir.path.resolve 解析路径。 因此路径中不含重复分隔符、“.”或“..”部分,也不含末尾分隔符。 在 WASI 上返回“”,而非“.”。

pub fn getResolvedCwd(io: Io, gpa: Allocator) std.process.CurrentPathAllocError![]u8

参数

io: Io
gpa: Allocator

错误

Canceled Cancelable

调用方请求停止异步操作。

CurrentDirUnlinked CurrentPathError

在 Windows 上不可能发生。在 WASI 上始终返回。

NameTooLong CurrentPathError

缓冲区过小,无法容纳当前路径。

OutOfMemory Error
PathExceedsLimit CurrentPathError

受底层 libc 或系统调用实现限制,无法获取当前路径。换用更大缓冲区重试也不会成功。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.zig.hashName

函数

第 106 行

pub fn hashName(parent_hash: SrcHash, sep: []const u8, name: []const u8) SrcHash

参数

parent_hash: SrcHash
sep: []const u8
name: []const u8

std.zig.hashSrc

函数

第 96 行

pub fn hashSrc(src: []const u8) SrcHash

参数

src: []const u8

std.zig.Io

别名

第 12 行

别名目标 std.Io

std.zig.isPrimitive

别名

第 29 行

别名目标 std.zig.primitives.isPrimitive

std.zig.isUnderscore

函数

第 798 行

pub fn isUnderscore(bytes: []const u8) bool

参数

bytes: []const u8

用法示例

test isUnderscore {
    try std.testing.expect(isUnderscore("_"));
    try std.testing.expect(!isUnderscore("__"));
    try std.testing.expect(!isUnderscore("_foo"));
    try std.testing.expect(isUnderscore("\x5f"));
    try std.testing.expect(!isUnderscore("\\x5f"));
}

std.zig.isUpDir

函数

第 1822 行

pub fn isUpDir(p: []const u8) bool

参数

p: []const u8

std.zig.isValidId

函数

第 777 行

pub fn isValidId(bytes: []const u8) bool

参数

bytes: []const u8

用法示例

test isValidId {
    try std.testing.expect(!isValidId(""));
    try std.testing.expect(isValidId("foobar"));
    try std.testing.expect(!isValidId("a b c"));
    try std.testing.expect(!isValidId("3d"));
    try std.testing.expect(!isValidId("enum"));
    try std.testing.expect(isValidId("i386"));
}

std.zig.LibCDirs

别名

第 40 行

别名目标 std.zig.LibCDirs

std.zig.LibCInstallation

别名

第 38 行

别名目标 std.zig.LibCInstallation

std.zig.lineDelta

函数

第 154 行

pub fn lineDelta(source: []const u8, start: usize, end: usize) isize

参数

source: []const u8
start: usize
end: usize

std.zig.llvm

别名

第 43 行

别名目标 std.zig.llvm

std.zig.Loc

容器

第 116 行

字段

line: usize
column: usize
source_line: []const u8

不包含末尾换行符。

std.zig.Loc.eql

函数

第 122 行

pub fn eql(a: Loc, b: Loc) bool

参数

a: Loc
b: Loc

std.zig.log

别名

第 10 行

别名目标 std.log

std.zig.LtoMode

容器

第 378 行

字段

none
full
thin

std.zig.max_src_size

常量

第 94 行

整个代码库中有许多假定:Zig 源文件可以 使用 u32 整数按字节索引。

std.zig.mem

别名

第 9 行

别名目标 std.mem

std.zig.number_literal

别名

第 27 行

别名目标 std.zig.number_literal

std.zig.parseCharLiteral

别名

第 49 行

别名目标 std.zig.string_literal.parseCharLiteral

std.zig.ParsedCharLiteral

别名

第 48 行

别名目标 std.zig.string_literal.ParsedCharLiteral

std.zig.parseNumberLiteral

别名

第 50 行

别名目标 std.zig.number_literal.parseNumberLiteral

std.zig.parser_generated_oracle

别名

第 45 行

别名目标 std.zig.parser_generated_oracle

std.zig.parseTargetQueryOrReportFatalError

函数

第 889 行

pub fn parseTargetQueryOrReportFatalError( allocator: Allocator, opts: std.Target.Query.ParseOptions, ) std.Target.Query

参数

std.zig.PkgConfig

别名

第 41 行

别名目标 std.zig.PkgConfig

std.zig.primitives

别名

第 28 行

别名目标 std.zig.primitives

std.zig.printAstErrorsToStderr

函数

第 851 行

pub fn printAstErrorsToStderr(gpa: Allocator, io: Io, tree: Ast, path: []const u8, color: Color) !void

参数

gpa: Allocator
io: Io
tree: Ast
path: []const u8
color: Color

std.zig.putAstErrorsIntoBundle

函数

第 862 行

pub fn putAstErrorsIntoBundle( gpa: Allocator, tree: Ast, path: []const u8, wip_errors: *ErrorBundle.Wip, ) Allocator.Error!void

参数

gpa: Allocator
tree: Ast
path: []const u8
wip_errors: *ErrorBundle.Wip

错误

OutOfMemory

std.zig.RcIncludes

容器

第 393 行

字段

any

若可用则使用 MSVC,否则回退到 MinGW。

msvc

使用 MSVC include 路径(MSVC 安装目录和 Windows SDK 必须已存在于系统中)。

gnu

使用 MinGW 包含路径(随 Zig 分发)。

none

不使用任何自动检测的包含路径。

std.zig.readSourceFileToEndAlloc

函数

第 813 行

若源数据可能采用 UTF-16LE 编码,此函数会断言 gpa 将字节大小的分配块至少按 2 对齐。 不满足此条件的分配器很少见。

pub fn readSourceFileToEndAlloc(gpa: Allocator, file_reader: *Io.File.Reader) ![:0]u8

参数

gpa: Allocator
file_reader: *Io.File.Reader

std.zig.resolveGlobalCacheDir

函数

第 1707 行

pub fn resolveGlobalCacheDir(arena: Allocator, environ_map: *const std.process.Environ.Map) ![]const u8

参数

arena: Allocator
environ_map: *const std.process.Environ.Map

std.zig.resolvePath

函数

第 1757 行

类似 Dir.path.resolve,但转换为相对于当前工作目录的路径;如果该路径 以相对的上级目录(“..”)开头,则返回基于当前工作目录的绝对路径。此外,当前工作目录 返回空串而非“.”。

pub fn resolvePath( gpa: Allocator, cwd_resolved: []const u8, paths: []const []const u8, ) Allocator.Error![]u8

参数

gpa: Allocator
cwd_resolved: []const u8

getResolvedCwd 的返回值。 作为参数传入,以避免无意义的重复调用。

paths: []const []const u8

错误

OutOfMemory

std.zig.resolveSuitableLocalCacheDir

函数

第 1738 行

从 cwd 向上搜索包含 build.zig 文件的目录。 若找到,返回该目录路径与 .zig_cache 名称拼接后的路径。 否则返回 null,表示没有适合的本地缓存位置。

pub fn resolveSuitableLocalCacheDir(arena: Allocator, io: Io, cwd: []const u8) Allocator.Error!?[]u8

参数

arena: Allocator
io: Io
cwd: []const u8

错误

OutOfMemory

std.zig.resolveTargetQueryOrFatal

函数

第 884 行

pub fn resolveTargetQueryOrFatal(io: Io, target_query: std.Target.Query) std.Target

参数

io: Io
target_query: std.Target.Query

std.zig.SanitizeC

容器

第 274 行

字段

off
trap
full

std.zig.serializeCpu

函数

第 407 行

将 std.Target.Cpu 值渲染为文本表示,可通过传给 Zig 编译器的 -mcpu 标志解析。 将结果追加到 buffer。

pub fn serializeCpu(buffer: *std.array_list.Managed(u8), cpu: std.Target.Cpu) Allocator.Error!void

参数

buffer: *std.array_list.Managed(u8)
cpu: std.Target.Cpu

错误

OutOfMemory

std.zig.serializeCpuAlloc

函数

第 434 行

pub fn serializeCpuAlloc(ally: Allocator, cpu: std.Target.Cpu) Allocator.Error![]u8

参数

ally: Allocator
cpu: std.Target.Cpu

错误

OutOfMemory

std.zig.Server

别名

第 21 行

别名目标 std.zig.Server

std.zig.shellEscape

函数

第 1388 行

fn shellEscape(writer: *Io.Writer, string: []const u8, is_argv0: bool) !void

参数

writer: *Io.Writer
string: []const u8
is_argv0: bool

std.zig.SimpleComptimeReason

容器

第 1005 行

字段

operand_setEvalBranchQuota
operand_setFloatMode
operand_branchHint
operand_setRuntimeSafety
operand_embedFile
operand_shuffle_mask
operand_atomicRmw_operation
operand_reduce_operation
export_target
export_options
extern_options
prefetch_options
call_modifier
compile_error_string
inline_assembly_code
atomic_order
slice_cat_operand
inline_call_target
generic_call_target
wasm_memory_index
work_group_dim_index
clobber
type
int_signedness
int_bit_width
array_sentinel
array_length
pointer_size
pointer_attrs
pointer_sentinel
slice_sentinel
vector_length
fn_ret_ty
fn_param_types
fn_param_attrs
fn_attrs
struct_layout
struct_field_names
struct_field_types
struct_field_attrs
union_layout
union_field_names
union_field_types
union_field_attrs
tuple_field_types
enum_field_names
enum_field_values
union_enum_tag_type
enum_int_tag_type
packed_struct_backing_int_type
packed_union_backing_int_type
decl_name
field_name
tuple_field_index
container_var_init
@"callconv"
@"align"
@"addrspace"
@"linksection"
comptime_keyword
comptime_call_modifier
inline_loop_operand
switch_item
tuple_field_default_value
struct_field_default_value
enum_field_tag_value
slice_single_item_ptr_bounds
stored_to_comptime_field
stored_to_comptime_var
casted_to_comptime_int
casted_to_comptime_float
std_lang_decl

std.zig.SimpleComptimeReason.message

函数

第 1093 行

pub fn message(r: SimpleComptimeReason) []const u8

参数

std.zig.SrcHash

类型

第 61 行

std.zig.srcHashEql

函数

第 102 行

pub fn srcHashEql(a: SrcHash, b: SrcHash) bool

参数

std.zig.SrcHasher

别名

第 60 行

别名目标 std.crypto.hash.Blake3

std.zig.std

别名

第 7 行

别名目标 std

std.zig.string_literal

别名

第 26 行

别名目标 std.zig.string_literal

std.zig.stringEscape

函数

第 553 行

将字符串打印为双引号字符串中经过转义的内容。

执行以下转换:

  • 转义:'\n'、'\r'、'\t'、'\'、'"'
  • 十六进制编码:
    • ASCII 控制字符
    • 无效 UTF-8 序列
    • 非 ASCII 换行符(U+0085、U+2028、U+2029)
    • 字节顺序标记(U+FEFF)

其他所有内容均原样传递。

pub fn stringEscape(bytes: []const u8, w: *Writer) Writer.Error!void

参数

bytes: []const u8
w: *Writer

错误

WriteFailed

详细诊断信息见 Writer 实现。

用法示例

test stringEscape {
    const bytes = "\x7f\t\n\r\\\"abc\xff\u{feff}\u{0085}\u{2028}\u{2029}\xed\xa0\x80\xf4\x90\x80\x80\xf4\x90a";
    const escaped = "\\x7f\\t\\n\\r\\\\\\\"abc\\xff\\xef\\xbb\\xbf\\xc2\\x85\\xe2\\x80\\xa8\\xe2\\x80\\xa9\\xed\\xa0\\x80\\xf4\\x90\\x80\\x80\\xf4\\x90a";

    var out_buf: [escaped.len]u8 = undefined;
    var out: Io.Writer = .fixed(&out_buf);

    try stringEscape(bytes, &out);
    try std.testing.expectEqualStrings(escaped, out.buffered());
}

std.zig.stringEscapeInner

函数

第 569 行

返回从 bytes 消费的字节数,可能小于 bytes.len。

fn stringEscapeInner(bytes: []const u8, w: *Writer) Writer.Error!usize

参数

bytes: []const u8
w: *Writer

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.zig.StringEscapeWriter

容器

第 631 行

字段

out: *Writer
writer: Writer

std.zig.StringEscapeWriter.drain

函数

第 648 行

fn drain(w: *Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize

参数

w: *Writer
data: []const []const u8
splat: usize

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.zig.StringEscapeWriter.drainBufferRemaining

函数

第 682 行

先排空缓冲区,必要时从 bytes 取数据,补全任何不完整的 UTF-8 序列。 然后消耗 bytes 的全部剩余内容,将可能位于末尾的不完整 UTF-8 序列存入缓冲区。

成功时,保证 w.buffered().len < 4。

fn drainBufferRemaining(w: *Writer, bytes: []const u8) Io.Writer.Error!usize

参数

w: *Writer
bytes: []const u8

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.zig.StringEscapeWriter.flush

函数

第 660 行

fn flush(w: *Writer) Io.Writer.Error!void

参数

w: *Writer

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.zig.StringEscapeWriter.init

函数

第 637 行

pub fn init(out: *Writer, buffer: []u8) @This()

参数

out: *Writer
buffer: []u8

std.zig.StringEscapeWriter.min_buffer_len

常量

第 635 行

std.zig.SubprocessCommand

容器

第 1421 行

字段

argv: []const []const u8
cwd: ?[]const u8 = null
parent_env: ?*const std.process.Environ.Map = null
child_env: ?*const std.process.Environ.Map = null

std.zig.SubprocessCommand.format

函数

第 1427 行

pub fn format(sc: SubprocessCommand, w: *Io.Writer) Io.Writer.Error!void

参数

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.zig.Subsystem

容器

第 380 行

字段

console
windows
posix
native
efi_application
efi_boot_service_driver
efi_rom
efi_runtime_driver

std.zig.system

别名

第 35 行

别名目标 std.zig.system

std.zig.target

别名

第 42 行

别名目标 std.zig.target

std.zig.testZigInstallPrefix

函数

第 1682 行

返回有效的 sub_path;若均无效,则返回 null。 返回 Directory 的路径相对于 base。 返回 Directory 的句柄处于打开状态。

fn testZigInstallPrefix(io: Io, base_dir: Dir) ?Cache.Directory

参数

io: Io
base_dir: Dir

std.zig.Token

别名

第 23 行

别名目标 std.zig.tokenizer.Token

std.zig.tokenizer

别名

第 18 行

别名目标 std.zig.tokenizer

std.zig.Tokenizer

别名

第 24 行

别名目标 std.zig.tokenizer.Tokenizer

std.zig.TokenSmith

别名

第 25 行

别名目标 std.zig.TokenSmith

std.zig.WindowsSdk

别名

第 39 行

别名目标 std.zig.WindowsSdk

std.zig.Writer

别名

第 13 行

别名目标 std.Io.Writer

std.zig.Zir

别名

第 32 行

别名目标 std.zig.Zir

std.zig.Zoir

别名

第 33 行

别名目标 std.zig.Zoir

std.zig.ZonGen

别名

第 34 行

别名目标 std.zig.ZonGen

源码

std/zig.zig

//! Zig 编译器构建产物有一部分以源码形式分发。
//! 这些源码位于此处。相关 API 按原样提供,
//! 没有任何 API 保证。

const builtin = @import("builtin");

const std = @import("std.zig");
const assert = std.debug.assert;
const mem = std.mem;
const log = std.log;
const Allocator = std.mem.Allocator;
const Io = std.Io;
const Writer = std.Io.Writer;
const Cache = std.Build.Cache;
const fatal = std.process.fatal;
const Dir = std.Io.Dir;

const tokenizer = @import("zig/tokenizer.zig");

pub const ErrorBundle = @import("zig/ErrorBundle.zig");
pub const Server = @import("zig/Server.zig");
pub const Client = @import("zig/Client.zig");
pub const Token = tokenizer.Token;
pub const Tokenizer = tokenizer.Tokenizer;
pub const TokenSmith = @import("zig/TokenSmith.zig");
pub const string_literal = @import("zig/string_literal.zig");
pub const number_literal = @import("zig/number_literal.zig");
pub const primitives = @import("zig/primitives.zig");
pub const isPrimitive = primitives.isPrimitive;
pub const Ast = @import("zig/Ast.zig");
pub const AstGen = @import("zig/AstGen.zig");
pub const Zir = @import("zig/Zir.zig");
pub const Zoir = @import("zig/Zoir.zig");
pub const ZonGen = @import("zig/ZonGen.zig");
pub const system = @import("zig/system.zig");
pub const BuiltinFn = @import("zig/BuiltinFn.zig");
pub const AstRlAnnotate = @import("zig/AstRlAnnotate.zig");
pub const LibCInstallation = @import("zig/LibCInstallation.zig");
pub const WindowsSdk = @import("zig/WindowsSdk.zig");
pub const LibCDirs = @import("zig/LibCDirs.zig");
pub const PkgConfig = @import("zig/PkgConfig.zig");
pub const target = @import("zig/target.zig");
pub const llvm = @import("zig/llvm.zig");

pub const parser_generated_oracle = @import("zig/parser_generated_oracle.zig");

// 字符字面量解析
pub const ParsedCharLiteral = string_literal.ParsedCharLiteral;
pub const parseCharLiteral = string_literal.parseCharLiteral;
pub const parseNumberLiteral = number_literal.parseNumberLiteral;

pub const c_translation = struct {
    pub const builtins = @import("zig/c_translation/builtins.zig");
    pub const helpers = @import("zig/c_translation/helpers.zig");
};

pub const default_local_zig_cache_basename = ".zig-cache";
pub const build_zig_basename = "build.zig";

pub const SrcHasher = std.crypto.hash.Blake3;
pub const SrcHash = [16]u8;

pub const Color = enum {
    /// 自动检测流是否支持终端颜色。
    auto,
    /// 强制启用颜色。
    off,
    /// 禁用颜色。
    on,

    pub fn terminalMode(color: Color) ?Io.Terminal.Mode {
        return switch (color) {
            .auto => null,
            .on => .escape_codes,
            .off => .no_color,
        };
    }

    /// 根据 NO_COLOR 和 CLICOLOR_FORCE 环境变量
    /// 确定是否使用颜色。WASI 上始终禁用颜色,依据为
    /// https://github.com/WebAssembly/WASI/issues/162
    pub fn settingFromEnvironment(environ_map: *const std.process.Environ.Map) Color {
        return if (builtin.os.tag == .wasi or EnvVar.NO_COLOR.isSet(environ_map))
            .off
        else if (EnvVar.CLICOLOR_FORCE.isSet(environ_map))
            .on
        else
            .auto;
    }
};

/// 整个代码库中有许多假定:Zig 源文件可以
/// 使用 u32 整数按字节索引。
pub const max_src_size = std.math.maxInt(u32);

pub fn hashSrc(src: []const u8) SrcHash {
    var out: SrcHash = undefined;
    SrcHasher.hash(src, &out, .{});
    return out;
}

pub fn srcHashEql(a: SrcHash, b: SrcHash) bool {
    return @as(u128, @bitCast(a)) == @as(u128, @bitCast(b));
}

pub fn hashName(parent_hash: SrcHash, sep: []const u8, name: []const u8) SrcHash {
    var out: SrcHash = undefined;
    var hasher = SrcHasher.init(.{});
    hasher.update(&parent_hash);
    hasher.update(sep);
    hasher.update(name);
    hasher.final(&out);
    return out;
}

pub const Loc = struct {
    line: usize,
    column: usize,
    /// 不包含末尾换行符。
    source_line: []const u8,

    pub fn eql(a: Loc, b: Loc) bool {
        return a.line == b.line and a.column == b.column and mem.eql(u8, a.source_line, b.source_line);
    }
};

pub fn findLineColumn(source: []const u8, byte_offset: usize) Loc {
    var line: usize = 0;
    var column: usize = 0;
    var line_start: usize = 0;
    var i: usize = 0;
    while (i < byte_offset) : (i += 1) {
        switch (source[i]) {
            '\n' => {
                line += 1;
                column = 0;
                line_start = i + 1;
            },
            else => {
                column += 1;
            },
        }
    }
    while (i < source.len and source[i] != '\n') {
        i += 1;
    }
    return .{
        .line = line,
        .column = column,
        .source_line = source[line_start..i],
    };
}

pub fn lineDelta(source: []const u8, start: usize, end: usize) isize {
    var line: isize = 0;
    if (end >= start) {
        for (source[start..end]) |byte| switch (byte) {
            '\n' => line += 1,
            else => continue,
        };
    } else {
        for (source[end..start]) |byte| switch (byte) {
            '\n' => line -= 1,
            else => continue,
        };
    }
    return line;
}

pub const BinNameOptions = struct {
    root_name: []const u8,
    cpu_arch: std.Target.Cpu.Arch,
    os_tag: std.Target.Os.Tag,
    ofmt: std.Target.ObjectFormat,
    abi: std.Target.Abi,
    output_mode: std.lang.OutputMode,
    link_mode: ?std.lang.LinkMode = null,
    version: ?std.SemanticVersion = null,
};

/// 返回 Zig 编译器生成的二进制文件的标准文件系统基本文件名。
pub fn binNameAlloc(allocator: Allocator, options: BinNameOptions) error{OutOfMemory}![]u8 {
    const root_name = options.root_name;
    switch (options.ofmt) {
        .coff => switch (options.output_mode) {
            .Exe => return std.fmt.allocPrint(allocator, "{s}{s}", .{
                root_name,
                options.os_tag.exeFileExt(options.cpu_arch),
            }),
            .Lib => {
                const suffix = switch (options.link_mode orelse .static) {
                    .static => ".lib",
                    .dynamic => ".dll",
                };
                return std.fmt.allocPrint(allocator, "{s}{s}", .{ root_name, suffix });
            },
            .Obj => return std.fmt.allocPrint(allocator, "{s}.obj", .{root_name}),
        },
        .elf => switch (options.output_mode) {
            .Exe => return allocator.dupe(u8, root_name),
            .Lib => {
                switch (options.link_mode orelse .static) {
                    .static => return std.fmt.allocPrint(allocator, "{s}{s}.a", .{
                        options.os_tag.libPrefix(options.abi), root_name,
                    }),
                    .dynamic => {
                        if (options.version) |ver| {
                            return std.fmt.allocPrint(allocator, "{s}{s}.so.{d}.{d}.{d}", .{
                                options.os_tag.libPrefix(options.abi), root_name, ver.major, ver.minor, ver.patch,
                            });
                        } else {
                            return std.fmt.allocPrint(allocator, "{s}{s}.so", .{
                                options.os_tag.libPrefix(options.abi), root_name,
                            });
                        }
                    },
                }
            },
            .Obj => return std.fmt.allocPrint(allocator, "{s}.o", .{root_name}),
        },
        .macho => switch (options.output_mode) {
            .Exe => return allocator.dupe(u8, root_name),
            .Lib => {
                switch (options.link_mode orelse .static) {
                    .static => return std.fmt.allocPrint(allocator, "{s}{s}.a", .{
                        options.os_tag.libPrefix(options.abi), root_name,
                    }),
                    .dynamic => {
                        if (options.version) |ver| {
                            return std.fmt.allocPrint(allocator, "{s}{s}.{d}.{d}.{d}.dylib", .{
                                options.os_tag.libPrefix(options.abi), root_name, ver.major, ver.minor, ver.patch,
                            });
                        } else {
                            return std.fmt.allocPrint(allocator, "{s}{s}.dylib", .{
                                options.os_tag.libPrefix(options.abi), root_name,
                            });
                        }
                    },
                }
            },
            .Obj => return std.fmt.allocPrint(allocator, "{s}.o", .{root_name}),
        },
        .wasm => switch (options.output_mode) {
            .Exe => return std.fmt.allocPrint(allocator, "{s}{s}", .{
                root_name,
                options.os_tag.exeFileExt(options.cpu_arch),
            }),
            .Lib => {
                switch (options.link_mode orelse .static) {
                    .static => return std.fmt.allocPrint(allocator, "{s}{s}.a", .{
                        options.os_tag.libPrefix(options.abi), root_name,
                    }),
                    .dynamic => return std.fmt.allocPrint(allocator, "{s}.wasm", .{root_name}),
                }
            },
            .Obj => return std.fmt.allocPrint(allocator, "{s}.o", .{root_name}),
        },
        .c => return std.fmt.allocPrint(allocator, "{s}.c", .{root_name}),
        .spirv => return std.fmt.allocPrint(allocator, "{s}.spv", .{root_name}),
        .hex => return std.fmt.allocPrint(allocator, "{s}.ihex", .{root_name}),
        .raw => return std.fmt.allocPrint(allocator, "{s}.bin", .{root_name}),
        .plan9 => switch (options.output_mode) {
            .Exe => return allocator.dupe(u8, root_name),
            .Obj => return std.fmt.allocPrint(allocator, "{s}{s}", .{
                root_name, options.ofmt.fileExt(options.cpu_arch),
            }),
            .Lib => return std.fmt.allocPrint(allocator, "{s}{s}.a", .{
                options.os_tag.libPrefix(options.abi), root_name,
            }),
        },
    }
}

pub const SanitizeC = enum {
    off,
    trap,
    full,
};

pub const BuildId = union(enum) {
    none,
    fast,
    uuid,
    sha1,
    md5,
    hexstring: HexString,

    pub fn eql(a: BuildId, b: BuildId) bool {
        const Tag = @typeInfo(BuildId).@"union".tag_type.?;
        const a_tag: Tag = a;
        const b_tag: Tag = b;
        if (a_tag != b_tag) return false;
        return switch (a) {
            .none, .fast, .uuid, .sha1, .md5 => true,
            .hexstring => |a_hexstring| mem.eql(u8, a_hexstring.toSlice(), b.hexstring.toSlice()),
        };
    }

    pub const HexString = struct {
        bytes: [32]u8,
        len: u8,

        /// 结果为字节值,*并非*十六进制编码。
        pub fn toSlice(hs: *const HexString) []const u8 {
            return hs.bytes[0..hs.len];
        }
    };

    /// 输入为字节值,*不是*十六进制编码。
    /// 断言 `bytes` 可放入 `HexString`。
    pub fn initHexString(bytes: []const u8) BuildId {
        var result: BuildId = .{ .hexstring = .{
            .bytes = undefined,
            .len = @intCast(bytes.len),
        } };
        @memcpy(result.hexstring.bytes[0..bytes.len], bytes);
        return result;
    }

    /// 将 UTF-8 文本转换为 `BuildId`。
    pub fn parse(text: []const u8) !BuildId {
        if (mem.eql(u8, text, "none")) {
            return .none;
        } else if (mem.eql(u8, text, "fast")) {
            return .fast;
        } else if (mem.eql(u8, text, "uuid")) {
            return .uuid;
        } else if (mem.eql(u8, text, "sha1") or mem.eql(u8, text, "tree")) {
            return .sha1;
        } else if (mem.eql(u8, text, "md5")) {
            return .md5;
        } else if (mem.startsWith(u8, text, "0x")) {
            var result: BuildId = .{ .hexstring = undefined };
            const slice = try std.fmt.hexToBytes(&result.hexstring.bytes, text[2..]);
            result.hexstring.len = @as(u8, @intCast(slice.len));
            return result;
        }
        return error.InvalidBuildIdStyle;
    }

    test parse {
        try std.testing.expectEqual(BuildId.md5, try parse("md5"));
        try std.testing.expectEqual(BuildId.none, try parse("none"));
        try std.testing.expectEqual(BuildId.fast, try parse("fast"));
        try std.testing.expectEqual(BuildId.uuid, try parse("uuid"));
        try std.testing.expectEqual(BuildId.sha1, try parse("sha1"));
        try std.testing.expectEqual(BuildId.sha1, try parse("tree"));

        try std.testing.expect(BuildId.initHexString("").eql(try parse("0x")));
        try std.testing.expect(BuildId.initHexString("\x12\x34\x56").eql(try parse("0x123456")));
        try std.testing.expectError(error.InvalidLength, parse("0x12-34"));
        try std.testing.expectError(error.InvalidCharacter, parse("0xfoobbb"));
        try std.testing.expectError(error.InvalidBuildIdStyle, parse("yaddaxxx"));
    }

    pub fn format(id: BuildId, writer: *Writer) Writer.Error!void {
        switch (id) {
            .none, .fast, .uuid, .sha1, .md5 => {
                try writer.writeAll(@tagName(id));
            },
            .hexstring => |hs| {
                try writer.print("0x{x}", .{hs.toSlice()});
            },
        }
    }

    test format {
        try std.testing.expectFmt("none", "{f}", .{@as(BuildId, .none)});
        try std.testing.expectFmt("fast", "{f}", .{@as(BuildId, .fast)});
        try std.testing.expectFmt("uuid", "{f}", .{@as(BuildId, .uuid)});
        try std.testing.expectFmt("sha1", "{f}", .{@as(BuildId, .sha1)});
        try std.testing.expectFmt("md5", "{f}", .{@as(BuildId, .md5)});
        try std.testing.expectFmt("0x", "{f}", .{BuildId.initHexString("")});
        try std.testing.expectFmt("0x1234cdef", "{f}", .{BuildId.initHexString("\x12\x34\xcd\xef")});
    }
};

pub const LtoMode = enum { none, full, thin };

pub const Subsystem = enum {
    console,
    windows,
    posix,
    native,
    efi_application,
    efi_boot_service_driver,
    efi_rom,
    efi_runtime_driver,
};

pub const CompressDebugSections = enum(u2) { none, zlib, zstd };

pub const RcIncludes = enum(u2) {
    /// 若可用则使用 MSVC,否则回退到 MinGW。
    any,
    /// 使用 MSVC include 路径(MSVC 安装目录和 Windows SDK 必须已存在于系统中)。
    msvc,
    /// 使用 MinGW 包含路径(随 Zig 分发)。
    gnu,
    /// 不使用任何自动检测的包含路径。
    none,
};

/// 将 `std.Target.Cpu` 值渲染为文本表示,可通过传给 Zig 编译器的
/// `-mcpu` 标志解析。
/// 将结果追加到 `buffer`。
pub fn serializeCpu(buffer: *std.array_list.Managed(u8), cpu: std.Target.Cpu) Allocator.Error!void {
    const all_features = cpu.arch.allFeaturesList();
    var populated_cpu_features = cpu.model.features;
    populated_cpu_features.populateDependencies(all_features);

    try buffer.appendSlice(cpu.model.name);

    if (populated_cpu_features.eql(cpu.features)) {
        // CPU 名称本身已足够。
        return;
    }

    for (all_features, 0..) |feature, i_usize| {
        const i: std.Target.Cpu.Feature.Set.Index = @intCast(i_usize);
        const in_cpu_set = populated_cpu_features.isEnabled(i);
        const in_actual_set = cpu.features.isEnabled(i);
        try buffer.ensureUnusedCapacity(feature.name.len + 1);
        if (in_cpu_set and !in_actual_set) {
            buffer.appendAssumeCapacity('-');
            buffer.appendSliceAssumeCapacity(feature.name);
        } else if (!in_cpu_set and in_actual_set) {
            buffer.appendAssumeCapacity('+');
            buffer.appendSliceAssumeCapacity(feature.name);
        }
    }
}

pub fn serializeCpuAlloc(ally: Allocator, cpu: std.Target.Cpu) Allocator.Error![]u8 {
    var buffer = std.array_list.Managed(u8).init(ally);
    try serializeCpu(&buffer, cpu);
    return buffer.toOwnedSlice();
}

/// 返回 Zig 标识符的 Formatter,必要时使用 `@""` 语法转义。
///
/// 另请参见 `fmtIdFlags`。
pub fn fmtId(bytes: []const u8) FormatId {
    return .{ .bytes = bytes, .flags = .{} };
}

/// 返回 Zig 标识符的 Formatter,必要时用 `@""` 语法转义。
///
/// 另见 `fmtId`。
pub fn fmtIdFlags(bytes: []const u8, flags: FormatId.Flags) FormatId {
    return .{ .bytes = bytes, .flags = flags };
}

pub fn fmtIdPU(bytes: []const u8) FormatId {
    return .{ .bytes = bytes, .flags = .{ .allow_primitive = true, .allow_underscore = true } };
}

pub fn fmtIdP(bytes: []const u8) FormatId {
    return .{ .bytes = bytes, .flags = .{ .allow_primitive = true } };
}

test fmtId {
    const expectFmt = std.testing.expectFmt;
    try expectFmt("@\"while\"", "{f}", .{fmtId("while")});
    try expectFmt("@\"while\"", "{f}", .{fmtIdFlags("while", .{ .allow_primitive = true })});
    try expectFmt("@\"while\"", "{f}", .{fmtIdFlags("while", .{ .allow_underscore = true })});
    try expectFmt("@\"while\"", "{f}", .{fmtIdFlags("while", .{ .allow_primitive = true, .allow_underscore = true })});

    try expectFmt("hello", "{f}", .{fmtId("hello")});
    try expectFmt("hello", "{f}", .{fmtIdFlags("hello", .{ .allow_primitive = true })});
    try expectFmt("hello", "{f}", .{fmtIdFlags("hello", .{ .allow_underscore = true })});
    try expectFmt("hello", "{f}", .{fmtIdFlags("hello", .{ .allow_primitive = true, .allow_underscore = true })});

    try expectFmt("@\"type\"", "{f}", .{fmtId("type")});
    try expectFmt("type", "{f}", .{fmtIdFlags("type", .{ .allow_primitive = true })});
    try expectFmt("@\"type\"", "{f}", .{fmtIdFlags("type", .{ .allow_underscore = true })});
    try expectFmt("type", "{f}", .{fmtIdFlags("type", .{ .allow_primitive = true, .allow_underscore = true })});

    try expectFmt("@\"_\"", "{f}", .{fmtId("_")});
    try expectFmt("@\"_\"", "{f}", .{fmtIdFlags("_", .{ .allow_primitive = true })});
    try expectFmt("_", "{f}", .{fmtIdFlags("_", .{ .allow_underscore = true })});
    try expectFmt("_", "{f}", .{fmtIdFlags("_", .{ .allow_primitive = true, .allow_underscore = true })});

    try expectFmt("@\"i123\"", "{f}", .{fmtId("i123")});
    try expectFmt("i123", "{f}", .{fmtIdFlags("i123", .{ .allow_primitive = true })});
    try expectFmt("@\"4four\"", "{f}", .{fmtId("4four")});
    try expectFmt("_underscore", "{f}", .{fmtId("_underscore")});
    try expectFmt("@\"11\\\"23\"", "{f}", .{fmtId("11\"23")});
    try expectFmt("@\"11\\x0f23\"", "{f}", .{fmtId("11\x0F23")});

    try expectFmt("@\"\\r\\\"\\n\\xff😎\\xe2\\x80\\xa8\"", "{f}", .{fmtId("\r\"\n\xFF😎\u{2028}")});

    // 严格来说,这些内容目前在 Zig 中不合法。
    try expectFmt("@\"\"", "{f}", .{fmtId("")});
    try expectFmt("@\"\\x00\"", "{f}", .{fmtId("\x00")});
}

pub const FormatId = struct {
    bytes: []const u8,
    flags: Flags,
    pub const Flags = struct {
        allow_primitive: bool = false,
        allow_underscore: bool = false,
    };

    /// 将字符串作为 Zig 标识符打印,必要时使用 `@""` 语法转义。
    pub fn format(ctx: FormatId, writer: *Writer) Writer.Error!void {
        const bytes = ctx.bytes;
        if (isValidId(bytes) and
            (ctx.flags.allow_primitive or !isPrimitive(bytes)) and
            (ctx.flags.allow_underscore or !isUnderscore(bytes)))
        {
            return writer.writeAll(bytes);
        }
        try writer.writeAll("@\"");
        try stringEscape(bytes, writer);
        try writer.writeByte('"');
    }
};

/// 返回用于转义双引号 Zig 字符串的格式化器。
pub fn fmtString(bytes: []const u8) std.fmt.Alt([]const u8, stringEscape) {
    return .{ .data = bytes };
}

/// 返回用于转义单引号 Zig 字符串的格式化器。
pub fn fmtChar(c: u21) std.fmt.Alt(u21, charEscape) {
    return .{ .data = c };
}

test fmtString {
    try std.testing.expectFmt("\\x0f", "{f}", .{fmtString("\x0f")});
    try std.testing.expectFmt(
        \\" \\ hi \x07 \x11 \" derp '"
    , "\"{f}\"", .{fmtString(" \\ hi \x07 \x11 \" derp '")});
}

test fmtChar {
    try std.testing.expectFmt("c \\u{26a1}", "{f} {f}", .{ fmtChar('c'), fmtChar('⚡') });
}

/// 将字符串打印为双引号字符串中经过转义的内容。
///
/// 执行以下转换:
/// * 转义:'\n'、'\r'、'\t'、'\\'、'"'
/// * 十六进制编码:
///   * ASCII 控制字符
///   * 无效 UTF-8 序列
///   * 非 ASCII 换行符(U+0085、U+2028、U+2029)
///   * 字节顺序标记(U+FEFF)
///
/// 其他所有内容均原样传递。
pub fn stringEscape(bytes: []const u8, w: *Writer) Writer.Error!void {
    var remaining = bytes.len;
    while (remaining > 0) {
        remaining -= try stringEscapeInner(bytes[bytes.len - remaining ..], w);

        // 转义第一个字节后重试。
        // 其余部分不一定需要转义。
        if (remaining > 0) {
            try w.writeAll("\\x");
            try w.printInt(bytes[bytes.len - remaining], 16, .lower, .{ .width = 2, .fill = '0' });
            remaining -= 1;
        }
    }
}

/// 返回从 `bytes` 消费的字节数,可能小于 `bytes.len`。
fn stringEscapeInner(bytes: []const u8, w: *Writer) Writer.Error!usize {
    var i: usize = 0;
    while (i < bytes.len) {
        const byte = bytes[i];
        switch (byte) {
            '\t' => {
                try w.writeAll("\\t");
            },
            '\n' => {
                try w.writeAll("\\n");
            },
            '\r' => {
                try w.writeAll("\\r");
            },
            '\\' => {
                try w.writeAll("\\\\");
            },
            '"' => {
                try w.writeAll("\\\"");
            },
            0...8, 11, 12, 14...0x1f, 0x7f => {
                try w.writeAll("\\x");
                try w.printInt(byte, 16, .lower, .{ .width = 2, .fill = '0' });
            },
            0x20, 0x21, 0x23...0x5b, 0x5d...0x7e => {
                try w.writeByte(byte);
            },
            0x80...0xff => {
                const len, const escape = blk: {
                    const len = std.unicode.utf8ByteSequenceLength(byte) catch break :blk .{ 1, true };
                    if (i + len > bytes.len) {
                        return i;
                    }
                    const sequence = bytes[i..][0..len];
                    const code_point = std.unicode.utf8Decode(sequence) catch |err| switch (err) {
                        error.Utf8CodepointTooLarge => break :blk .{ len, true },
                        else => break :blk .{ 1, true },
                    };
                    switch (code_point) {
                        '\u{feff}', '\u{0085}', '\u{2028}', '\u{2029}' => break :blk .{ len, true },
                        else => break :blk .{ len, false },
                    }
                };

                const sequence = bytes[i..][0..len];
                if (escape) {
                    for (sequence) |b| {
                        try w.writeAll("\\x");
                        try w.printInt(b, 16, .lower, .{ .width = 2, .fill = '0' });
                    }
                } else {
                    try w.writeAll(sequence);
                }
                i += len;
                continue;
            },
        }
        i += 1;
    }
    return i;
}

pub const StringEscapeWriter = struct {
    out: *Writer,
    writer: Writer,

    pub const min_buffer_len = 4;

    pub fn init(out: *Writer, buffer: []u8) @This() {
        assert(buffer.len >= min_buffer_len);
        return .{
            .out = out,
            .writer = .{
                .vtable = &.{ .drain = @This().drain, .flush = @This().flush },
                .buffer = buffer,
            },
        };
    }

    fn drain(w: *Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize {
        var n: usize = try drainBufferRemaining(w, "");
        for (data[0 .. data.len - 1]) |bytes| {
            n += try drainBufferRemaining(w, bytes);
        }
        const pattern = data[data.len - 1];
        for (0..splat) |_| {
            n += try drainBufferRemaining(w, pattern);
        }
        return n;
    }

    fn flush(w: *Writer) Io.Writer.Error!void {
        const sew: *StringEscapeWriter = @alignCast(@fieldParentPtr("writer", w));
        const out = sew.out;
        while (w.end != 0) {
            _ = try drainBufferRemaining(w, "");

            // 转义第一个字节后重试。
            // 其余部分不一定需要转义。
            const remaining = w.buffered();
            if (remaining.len > 0) {
                try out.writeAll("\\x");
                try out.printInt(remaining[0], 16, .lower, .{ .width = 2, .fill = '0' });
                _ = w.consume(1);
            }
        }
    }

    /// 先排空缓冲区,必要时从 `bytes` 取数据,补全任何不完整的 UTF-8 序列。
    /// 然后消耗 `bytes` 的全部剩余内容,将可能位于末尾的不完整 UTF-8 序列存入缓冲区。
    ///
    /// 成功时,保证 `w.buffered().len` < 4。
    ///
    fn drainBufferRemaining(w: *Writer, bytes: []const u8) Io.Writer.Error!usize {
        const sew: *StringEscapeWriter = @alignCast(@fieldParentPtr("writer", w));
        const out = sew.out;
        var remaining_bytes = bytes;
        while (w.end != 0) {
            const n = try stringEscapeInner(w.buffered(), out);
            _ = w.consume(n);

            if (w.end != 0) {
                if (remaining_bytes.len == 0) return bytes.len;
                const len = std.unicode.utf8ByteSequenceLength(w.buffer[0]) catch unreachable;
                const missing = len - w.end;
                const available = remaining_bytes.len;
                const copy_len = @min(missing, available);
                const start = len - missing;
                @memcpy(w.buffer[start..][0..copy_len], remaining_bytes[0..copy_len]);
                w.end = start + copy_len;
                remaining_bytes = remaining_bytes[copy_len..];
            }
        }

        const n = try stringEscapeInner(remaining_bytes, out);
        if (n < remaining_bytes.len) {
            const remaining = remaining_bytes.len - n;
            @memcpy(w.buffer[0..remaining], remaining_bytes[n..]);
            w.end = remaining;
        }

        return bytes.len;
    }
};

test stringEscape {
    const bytes = "\x7f\t\n\r\\\"abc\xff\u{feff}\u{0085}\u{2028}\u{2029}\xed\xa0\x80\xf4\x90\x80\x80\xf4\x90a";
    const escaped = "\\x7f\\t\\n\\r\\\\\\\"abc\\xff\\xef\\xbb\\xbf\\xc2\\x85\\xe2\\x80\\xa8\\xe2\\x80\\xa9\\xed\\xa0\\x80\\xf4\\x90\\x80\\x80\\xf4\\x90a";

    var out_buf: [escaped.len]u8 = undefined;
    var out: Io.Writer = .fixed(&out_buf);

    try stringEscape(bytes, &out);
    try std.testing.expectEqualStrings(escaped, out.buffered());
}

test StringEscapeWriter {
    const bytes = "\x7f\t\n\r\\\"abc\xff\u{feff}\u{0085}\u{2028}\u{2029}\xed\xa0\x80\xf4\x90\x80\x80\xf4\x90a";
    const escaped = "\\x7f\\t\\n\\r\\\\\\\"abc\\xff\\xef\\xbb\\xbf\\xc2\\x85\\xe2\\x80\\xa8\\xe2\\x80\\xa9\\xed\\xa0\\x80\\xf4\\x90\\x80\\x80\\xf4\\x90a";

    var sew_buf: [StringEscapeWriter.min_buffer_len]u8 = undefined;
    {
        var out_buf: [escaped.len]u8 = undefined;
        var out: Io.Writer = .fixed(&out_buf);
        var w: StringEscapeWriter = .init(&out, &sew_buf);

        const n = try w.writer.write(bytes);
        try w.writer.flush();

        try std.testing.expectEqual(bytes.len, n);
        try std.testing.expectEqualStrings(escaped, out.buffered());
    }
    {
        var out_buf: [escaped.len]u8 = undefined;
        var out: Io.Writer = .fixed(&out_buf);
        var w: StringEscapeWriter = .init(&out, &sew_buf);

        for (bytes) |byte| {
            try w.writer.writeByte(byte);
        }
        try w.writer.flush();

        try std.testing.expectEqualStrings(escaped, out.buffered());
    }
}

/// 按单引号字符串的转义内容打印。
pub fn charEscape(codepoint: u21, w: *Writer) Writer.Error!void {
    switch (codepoint) {
        '\n' => try w.writeAll("\\n"),
        '\r' => try w.writeAll("\\r"),
        '\t' => try w.writeAll("\\t"),
        '\\' => try w.writeAll("\\\\"),
        '\'' => try w.writeAll("\\'"),
        '"', ' ', '!', '#'...'&', '('...'[', ']'...'~' => try w.writeByte(@intCast(codepoint)),
        else => {
            if (std.math.cast(u8, codepoint)) |byte| {
                try w.writeAll("\\x");
                try w.printInt(byte, 16, .lower, .{ .width = 2, .fill = '0' });
            } else {
                try w.writeAll("\\u{");
                try w.printInt(codepoint, 16, .lower, .{});
                try w.writeByte('}');
            }
        },
    }
}

pub fn isValidId(bytes: []const u8) bool {
    if (bytes.len == 0) return false;
    for (bytes, 0..) |c, i| {
        switch (c) {
            '_', 'a'...'z', 'A'...'Z' => {},
            '0'...'9' => if (i == 0) return false,
            else => return false,
        }
    }
    return Token.getKeyword(bytes) == null;
}

test isValidId {
    try std.testing.expect(!isValidId(""));
    try std.testing.expect(isValidId("foobar"));
    try std.testing.expect(!isValidId("a b c"));
    try std.testing.expect(!isValidId("3d"));
    try std.testing.expect(!isValidId("enum"));
    try std.testing.expect(isValidId("i386"));
}

pub fn isUnderscore(bytes: []const u8) bool {
    return bytes.len == 1 and bytes[0] == '_';
}

test isUnderscore {
    try std.testing.expect(isUnderscore("_"));
    try std.testing.expect(!isUnderscore("__"));
    try std.testing.expect(!isUnderscore("_foo"));
    try std.testing.expect(isUnderscore("\x5f"));
    try std.testing.expect(!isUnderscore("\\x5f"));
}

/// 若源数据可能采用 UTF-16LE 编码,此函数会断言 `gpa`
/// 将字节大小的分配块至少按 2 对齐。
/// 不满足此条件的分配器很少见。
pub fn readSourceFileToEndAlloc(gpa: Allocator, file_reader: *Io.File.Reader) ![:0]u8 {
    var buffer: std.ArrayList(u8) = .empty;
    defer buffer.deinit(gpa);

    if (file_reader.getSize()) |size| {
        const casted_size = std.math.cast(u32, size) orelse return error.StreamTooLong;
        // 加 1,以避免为下方 toOwnedSliceSentinel 添加的空字节重新调整大小。
        try buffer.ensureTotalCapacityPrecise(gpa, casted_size + 1);
    } else |_| {}

    try file_reader.interface.appendRemaining(gpa, &buffer, .limited(max_src_size));

    // 通过字节序标记检测不受支持的文件类型
    const unsupported_boms = [_][]const u8{
        "\xff\xfe\x00\x00", // UTF-32 小端序
        "\xfe\xff\x00\x00", // UTF-32 大端序
        "\xfe\xff", // UTF-16 大端序
    };
    for (unsupported_boms) |bom| {
        if (mem.startsWith(u8, buffer.items, bom)) {
            return error.UnsupportedEncoding;
        }
    }

    // 若文件以 UTF-16 小端 BOM 开头,则转换为 UTF-8
    if (mem.startsWith(u8, buffer.items, "\xff\xfe")) {
        if (buffer.items.len % 2 != 0) return error.InvalidEncoding;
        return std.unicode.utf16LeToUtf8AllocZ(gpa, @ptrCast(@alignCast(buffer.items))) catch |err| switch (err) {
            error.DanglingSurrogateHalf => error.UnsupportedEncoding,
            error.ExpectedSecondSurrogateHalf => error.UnsupportedEncoding,
            error.UnexpectedSecondSurrogateHalf => error.UnsupportedEncoding,
            else => |e| return e,
        };
    }

    return buffer.toOwnedSliceSentinel(gpa, 0);
}

pub fn printAstErrorsToStderr(gpa: Allocator, io: Io, tree: Ast, path: []const u8, color: Color) !void {
    var wip_errors: ErrorBundle.Wip = try .init(gpa);
    defer wip_errors.deinit();

    try putAstErrorsIntoBundle(gpa, tree, path, &wip_errors);

    var error_bundle = try wip_errors.toOwnedBundle("");
    defer error_bundle.deinit(gpa);
    return error_bundle.renderToStderr(io, .{}, color);
}

pub fn putAstErrorsIntoBundle(
    gpa: Allocator,
    tree: Ast,
    path: []const u8,
    wip_errors: *ErrorBundle.Wip,
) Allocator.Error!void {
    switch (tree.mode) {
        .zig => {
            var zir = try AstGen.generate(gpa, tree);
            defer zir.deinit(gpa);

            try wip_errors.addZirErrorMessages(zir, tree, tree.source, path);
        },
        .zon => {
            var zoir = try ZonGen.generate(gpa, tree, .{});
            defer zoir.deinit(gpa);

            try wip_errors.addZoirErrorMessages(zoir, tree, tree.source, path);
        },
    }
}

pub fn resolveTargetQueryOrFatal(io: Io, target_query: std.Target.Query) std.Target {
    return system.resolveTargetQuery(io, target_query) catch |err|
        std.process.fatal("unable to resolve target: {t}", .{err});
}

pub fn parseTargetQueryOrReportFatalError(
    allocator: Allocator,
    opts: std.Target.Query.ParseOptions,
) std.Target.Query {
    var opts_with_diags = opts;
    var diags: std.Target.Query.ParseOptions.Diagnostics = .{};
    if (opts_with_diags.diagnostics == null) {
        opts_with_diags.diagnostics = &diags;
    }
    return std.Target.Query.parse(opts_with_diags) catch |err| switch (err) {
        error.UnknownCpuModel => {
            help: {
                var help_text = std.array_list.Managed(u8).init(allocator);
                defer help_text.deinit();
                for (diags.arch.?.allCpuModels()) |cpu| {
                    help_text.print(" {s}\n", .{cpu.name}) catch break :help;
                }
                log.info("available CPUs for architecture '{s}':\n{s}", .{
                    @tagName(diags.arch.?), help_text.items,
                });
            }
            std.process.fatal("unknown CPU: '{s}'", .{diags.cpu_name.?});
        },
        error.UnknownCpuFeature => {
            help: {
                var help_text = std.array_list.Managed(u8).init(allocator);
                defer help_text.deinit();
                for (diags.arch.?.allFeaturesList()) |feature| {
                    help_text.print(" {s}: {s}\n", .{ feature.name, feature.description }) catch break :help;
                }
                log.info("available CPU features for architecture '{s}':\n{s}", .{
                    @tagName(diags.arch.?), help_text.items,
                });
            }
            std.process.fatal("unknown CPU feature: '{s}'", .{diags.unknown_feature_name.?});
        },
        error.UnknownObjectFormat => {
            help: {
                var help_text = std.array_list.Managed(u8).init(allocator);
                defer help_text.deinit();
                inline for (@typeInfo(std.Target.ObjectFormat).@"enum".field_names) |field_name| {
                    help_text.print(" {s}\n", .{field_name}) catch break :help;
                }
                log.info("available object formats:\n{s}", .{help_text.items});
            }
            std.process.fatal("unknown object format: '{s}'", .{opts.object_format.?});
        },
        error.UnknownArchitecture => {
            help: {
                var help_text = std.array_list.Managed(u8).init(allocator);
                defer help_text.deinit();
                inline for (@typeInfo(std.Target.Cpu.Arch).@"enum".field_names) |field_name| {
                    help_text.print(" {s}\n", .{field_name}) catch break :help;
                }
                log.info("available architectures:\n{s} native\n", .{help_text.items});
            }
            std.process.fatal("unknown architecture: '{s}'", .{diags.unknown_architecture_name.?});
        },
        else => |e| std.process.fatal("unable to parse target query '{s}': {s}", .{
            opts.arch_os_abi, @errorName(e),
        }),
    };
}

/// 收集 Zig 可能检查的所有环境变量,
/// 以便对其反射,并通过 `zig env` 打印。
pub const EnvVar = enum {
    ZIG_GLOBAL_CACHE_DIR,
    ZIG_LOCAL_CACHE_DIR,
    ZIG_LOCAL_PKG_DIR,
    ZIG_LIB_DIR,
    ZIG_LIBC,
    ZIG_BUILD_ERROR_STYLE,
    ZIG_BUILD_MULTILINE_ERRORS,
    ZIG_BUILD_SUMMARY,
    ZIG_VERBOSE_LINK,
    ZIG_VERBOSE_CC,
    ZIG_VERBOSE_CMD,
    ZIG_DEBUG_CMD,
    ZIG_IS_DETECTING_LIBC_PATHS,
    ZIG_IS_AVOIDING_CALLING_ITSELF,

    // C 工具链集成
    NIX_CFLAGS_COMPILE,
    NIX_CFLAGS_LINK,
    NIX_LDFLAGS,
    C_INCLUDE_PATH,
    CPLUS_INCLUDE_PATH,
    LIBRARY_PATH,
    CC,
    PKG_CONFIG,

    // 终端集成
    NO_COLOR,
    CLICOLOR_FORCE,

    // 调试信息集成
    XDG_CACHE_HOME,
    LOCALAPPDATA,
    HOME,

    // Windows SDK 集成
    PROGRAMDATA,

    // Homebrew 集成
    HOMEBREW_PREFIX,

    pub fn isSet(ev: EnvVar, map: *const std.process.Environ.Map) bool {
        return map.contains(@tagName(ev));
    }

    pub fn get(ev: EnvVar, map: *const std.process.Environ.Map) ?[]const u8 {
        return map.get(@tagName(ev));
    }
};

pub const SimpleComptimeReason = enum(u32) {
    // 因内置函数操作数必须在编译期已知,故在编译期求值。
    // 这些消息均提及特定内置函数。
    operand_setEvalBranchQuota,
    operand_setFloatMode,
    operand_branchHint,
    operand_setRuntimeSafety,
    operand_embedFile,
    operand_shuffle_mask,
    operand_atomicRmw_operation,
    operand_reduce_operation,

    // 由于某个操作数必须在编译期已知,因此在编译期求值。
    // 这些消息不提及特定内置函数,甚至可能与内置函数无关。
    export_target,
    export_options,
    extern_options,
    prefetch_options,
    call_modifier,
    compile_error_string,
    inline_assembly_code,
    atomic_order,
    slice_cat_operand,
    inline_call_target,
    generic_call_target,
    wasm_memory_index,
    work_group_dim_index,
    clobber,

    // 在编译期求值,因为类型必须在编译期已知。
    // `.type` 之外的原因只是更具体的消息。
    type,
    int_signedness,
    int_bit_width,
    array_sentinel,
    array_length,
    pointer_size,
    pointer_attrs,
    pointer_sentinel,
    slice_sentinel,
    vector_length,
    fn_ret_ty,
    fn_param_types,
    fn_param_attrs,
    fn_attrs,
    struct_layout,
    struct_field_names,
    struct_field_types,
    struct_field_attrs,
    union_layout,
    union_field_names,
    union_field_types,
    union_field_attrs,
    tuple_field_types,
    enum_field_names,
    enum_field_values,
    union_enum_tag_type,
    enum_int_tag_type,
    packed_struct_backing_int_type,
    packed_union_backing_int_type,

    // 在编译期求值,因为声明/字段名称必须在编译期已知。
    decl_name,
    field_name,
    tuple_field_index,

    // 由于它是全局声明的属性,因此在编译期求值。
    container_var_init,
    @"callconv",
    @"align",
    @"addrspace",
    @"linksection",

    // 其他原因。
    comptime_keyword,
    comptime_call_modifier,
    inline_loop_operand,
    switch_item,
    tuple_field_default_value,
    struct_field_default_value,
    enum_field_tag_value,
    slice_single_item_ptr_bounds,
    stored_to_comptime_field,
    stored_to_comptime_var,
    casted_to_comptime_int,
    casted_to_comptime_float,
    std_lang_decl,

    pub fn message(r: SimpleComptimeReason) []const u8 {
        return switch (r) {
            // zig fmt: off
            .operand_setEvalBranchQuota  => "operand to '@setEvalBranchQuota' must be comptime-known",
            .operand_setFloatMode        => "operand to '@setFloatMode' must be comptime-known",
            .operand_branchHint          => "operand to '@branchHint' must be comptime-known",
            .operand_setRuntimeSafety    => "operand to '@setRuntimeSafety' must be comptime-known",
            .operand_embedFile           => "operand to '@embedFile' must be comptime-known",
            .operand_shuffle_mask        => "'@shuffle' mask must be comptime-known",
            .operand_atomicRmw_operation => "'@atomicRmw' operation must be comptime-known",
            .operand_reduce_operation    => "'@reduce' operation must be comptime-known",

            .export_target        => "export target must be comptime-known",
            .export_options       => "export options must be comptime-known",
            .extern_options       => "extern options must be comptime-known",
            .prefetch_options     => "prefetch options must be comptime-known",
            .call_modifier        => "call modifier must be comptime-known",
            .compile_error_string => "compile error string must be comptime-known",
            .inline_assembly_code => "inline assembly code must be comptime-known",
            .atomic_order         => "atomic order must be comptime-known",
            .slice_cat_operand    => "slice being concatenated must be comptime-known",
            .inline_call_target   => "function being called inline must be comptime-known",
            .generic_call_target  => "generic function being called must be comptime-known",
            .wasm_memory_index    => "wasm memory index must be comptime-known",
            .work_group_dim_index => "work group dimension index must be comptime-known",
            .clobber              => "clobber must be comptime-known",

            .type                => "types must be comptime-known",
            .int_signedness      => "integer signedness must be comptime-known",
            .int_bit_width       => "integer bit width must be comptime-known",
            .array_sentinel      => "array sentinel value must be comptime-known",
            .array_length        => "array length must be comptime-known",
            .pointer_size        => "pointer size must be comptime-known",
            .pointer_attrs       => "pointer attributes must be comptime-known",
            .pointer_sentinel    => "pointer sentinel value must be comptime-known",
            .slice_sentinel      => "slice sentinel value must be comptime-known",
            .vector_length       => "vector length must be comptime-known",
            .fn_ret_ty           => "function return type must be comptime-known",
            .fn_param_types      => "function parameter types must be comptime-known",
            .fn_param_attrs      => "function parameter attributes must be comptime-known",
            .fn_attrs            => "function attributes must be comptime-known",
            .struct_layout       => "struct layout must be comptime-known",
            .struct_field_names  => "struct field names must be comptime-known",
            .struct_field_types  => "struct field types must be comptime-known",
            .struct_field_attrs  => "struct field attributes must be comptime-known",
            .union_layout        => "union layout must be comptime-known",
            .union_field_names   => "union field names must be comptime-known",
            .union_field_types   => "union field types must be comptime-known",
            .union_field_attrs   => "union field attributes must be comptime-known",
            .tuple_field_types   => "tuple field types must be comptime-known",
            .enum_field_names    => "enum field names must be comptime-known",
            .enum_field_values   => "enum field values must be comptime-known",

            .union_enum_tag_type            => "enum tag type of union must be comptime-known",
            .enum_int_tag_type              => "integer tag type of enum must be comptime-known",
            .packed_struct_backing_int_type => "packed struct backing integer type must be comptime-known",
            .packed_union_backing_int_type  => "packed struct backing integer type must be comptime-known",

            .decl_name         => "declaration name must be comptime-known",
            .field_name        => "field name must be comptime-known",
            .tuple_field_index => "tuple field index must be comptime-known",

            .container_var_init => "initializer of container-level variable must be comptime-known",
            .@"callconv"        => "calling convention must be comptime-known",
            .@"align"           => "alignment must be comptime-known",
            .@"addrspace"       => "address space must be comptime-known",
            .@"linksection"     => "linksection must be comptime-known",

            .comptime_keyword             => "'comptime' keyword forces comptime evaluation",
            .comptime_call_modifier       => "'.compile_time' call modifier forces comptime evaluation",
            .inline_loop_operand          => "inline loop condition must be comptime-known",
            .switch_item                  => "switch prong values must be comptime-known",
            .tuple_field_default_value    => "tuple field default value must be comptime-known",
            .struct_field_default_value   => "struct field default value must be comptime-known",
            .enum_field_tag_value         => "enum field tag value must be comptime-known",
            .slice_single_item_ptr_bounds => "slice of single-item pointer must have comptime-known bounds",
            .stored_to_comptime_field     => "value stored to a comptime field must be comptime-known",
            .stored_to_comptime_var       => "value stored to a comptime variable must be comptime-known",
            .casted_to_comptime_int       => "value casted to 'comptime_int' must be comptime-known",
            .casted_to_comptime_float     => "value casted to 'comptime_float' must be comptime-known",
            .std_lang_decl                => "'std.lang' declaration values must be comptime-known",
            // zig fmt: on
        };
    }
};

/// 编译器可生成的所有产物类型。
pub const EmitArtifact = enum {
    bin,
    @"asm",
    implib,
    llvm_ir,
    llvm_bc,
    docs,
    pdb,
    h,

    /// 使用 `Server` 与编译器通信时,编译器会将请求的产物放在
    /// 输出目录下的路径中,其路径命名规则由此函数确定。
    /// 返回的字符串由 `gpa` 分配,所有权归调用者。
    pub fn cacheName(ea: EmitArtifact, gpa: Allocator, opts: BinNameOptions) Allocator.Error![]const u8 {
        const suffix: []const u8 = switch (ea) {
            .bin => return binNameAlloc(gpa, opts),
            .@"asm" => ".s",
            .implib => ".lib",
            .llvm_ir => ".ll",
            .llvm_bc => ".bc",
            .docs => "-docs",
            .pdb => ".pdb",
            .h => ".h",
        };
        return std.fmt.allocPrint(gpa, "{s}{s}", .{ opts.root_name, suffix });
    }
};

/// 在此选择默认值,以缩减 src/clang_options.zon 的大小
pub const ClangCliParam = struct {
    name: []const u8,
    ze: ZigEquivalent = .other,
    syntax: Syntax = .flag,
    /// 以 "-" 为前缀
    pd1: bool = true,
    /// 前缀为 "--"
    pd2: bool = false,
    /// 前缀为 "/"
    psl: bool = false,

    pub const Syntax = union(enum) {
        /// 不带值的标志。
        flag,
        /// 将其唯一值附加在自身之后的选项。
        joined,
        /// 其值紧随其后的选项。
        separate,
        /// 既可与非空值连写、也可由值紧随其后的选项。
        joined_or_separate,
        /// 同时与其第一个值连写,并由第二个值紧随其后的选项。
        joined_and_separate,
        /// 其后跟随多个值的选项,各值以逗号分隔。
        comma_joined,
        /// 会消耗一个可选的连接参数及所有其他剩余参数的选项。
        remaining_args_joined,
        /// 接受多个独立参数的选项。
        multi_arg: u8,
    };

    pub const ZigEquivalent = enum {
        target,
        o,
        c,
        r,
        m,
        x,
        other,
        positional,
        l,
        ignore,
        driver_punt,
        pic,
        no_pic,
        pie,
        no_pie,
        lto,
        no_lto,
        unwind_tables,
        no_unwind_tables,
        asynchronous_unwind_tables,
        no_asynchronous_unwind_tables,
        nostdlib,
        nostdlib_cpp,
        shared,
        rdynamic,
        wl,
        wp,
        preprocess_only,
        asm_only,
        optimize,
        debug,
        gdwarf32,
        gdwarf64,
        sanitize,
        no_sanitize,
        sanitize_trap,
        no_sanitize_trap,
        linker_script,
        dry_run,
        verbose,
        for_linker,
        linker_input_z,
        lib_dir,
        mcpu,
        dep_file,
        dep_file_to_stdout,
        framework_dir,
        framework,
        nostdlibinc,
        red_zone,
        no_red_zone,
        omit_frame_pointer,
        no_omit_frame_pointer,
        function_sections,
        no_function_sections,
        data_sections,
        no_data_sections,
        builtin,
        no_builtin,
        color_diagnostics,
        no_color_diagnostics,
        stack_check,
        no_stack_check,
        stack_protector,
        no_stack_protector,
        strip,
        exec_model,
        emit_llvm,
        sysroot,
        entry,
        force_undefined_symbol,
        weak_library,
        weak_framework,
        headerpad_max_install_names,
        compress_debug_sections,
        install_name,
        undefined,
        force_load_objc,
        mingw_unicode_entry_point,
        san_cov_trace_pc_guard,
        san_cov,
        no_san_cov,
        rtlib,
        static,
        dynamic,
        version,
        patchable_function_entry,
    };

    pub fn matchEql(self: @This(), arg: []const u8) u2 {
        if (self.pd1 and arg.len >= self.name.len + 1 and
            mem.startsWith(u8, arg, "-") and mem.eql(u8, arg[1..], self.name))
        {
            return 1;
        }
        if (self.pd2 and arg.len >= self.name.len + 2 and
            mem.startsWith(u8, arg, "--") and mem.eql(u8, arg[2..], self.name))
        {
            return 2;
        }
        if (self.psl and arg.len >= self.name.len + 1 and
            mem.startsWith(u8, arg, "/") and mem.eql(u8, arg[1..], self.name))
        {
            return 1;
        }
        return 0;
    }

    pub fn matchStartsWith(self: @This(), arg: []const u8) usize {
        if (self.pd1 and arg.len >= self.name.len + 1 and
            mem.startsWith(u8, arg, "-") and mem.startsWith(u8, arg[1..], self.name))
        {
            return self.name.len + 1;
        }
        if (self.pd2 and arg.len >= self.name.len + 2 and
            mem.startsWith(u8, arg, "--") and mem.startsWith(u8, arg[2..], self.name))
        {
            return self.name.len + 2;
        }
        if (self.psl and arg.len >= self.name.len + 1 and
            mem.startsWith(u8, arg, "/") and mem.startsWith(u8, arg[1..], self.name))
        {
            return self.name.len + 1;
        }
        return 0;
    }
};

/// 已弃用
pub const AllocPrintCmdOptions = struct {
    cwd: ?[]const u8 = null,
    parent_env: ?*const std.process.Environ.Map = null,
    child_env: ?*const std.process.Environ.Map = null,
};

/// 已弃用
pub fn allocPrintCmd(gpa: Allocator, argv: []const []const u8, options: AllocPrintCmdOptions) Allocator.Error![]u8 {
    var aw: Io.Writer.Allocating = .init(gpa);
    defer aw.deinit();
    SubprocessCommand.format(.{
        .argv = argv,
        .cwd = options.cwd,
        .parent_env = options.parent_env,
        .child_env = options.child_env,
    }, &aw.writer) catch return error.OutOfMemory;
    return aw.toOwnedSlice();
}

fn shellEscape(writer: *Io.Writer, string: []const u8, is_argv0: bool) !void {
    for (string) |c| {
        if (switch (c) {
            else => true,
            '%', '+'...':', '@'...'Z', '_', 'a'...'z' => false,
            '=' => is_argv0,
        }) break;
    } else return writer.writeAll(string);

    try writer.writeByte('"');
    for (string) |c| {
        if (switch (c) {
            std.ascii.control_code.nul => break,
            '!', '"', '$', '\\', '`' => true,
            else => !std.ascii.isPrint(c),
        }) try writer.writeByte('\\');
        switch (c) {
            std.ascii.control_code.nul => unreachable,
            std.ascii.control_code.bel => try writer.writeByte('a'),
            std.ascii.control_code.bs => try writer.writeByte('b'),
            std.ascii.control_code.ht => try writer.writeByte('t'),
            std.ascii.control_code.lf => try writer.writeByte('n'),
            std.ascii.control_code.vt => try writer.writeByte('v'),
            std.ascii.control_code.ff => try writer.writeByte('f'),
            std.ascii.control_code.cr => try writer.writeByte('r'),
            std.ascii.control_code.esc => try writer.writeByte('E'),
            ' '...'~' => try writer.writeByte(c),
            else => try writer.print("{o:0>3}", .{c}),
        }
    }
    try writer.writeByte('"');
}

pub const SubprocessCommand = struct {
    argv: []const []const u8,
    cwd: ?[]const u8 = null,
    parent_env: ?*const std.process.Environ.Map = null,
    child_env: ?*const std.process.Environ.Map = null,

    pub fn format(sc: SubprocessCommand, w: *Io.Writer) Io.Writer.Error!void {
        if (sc.cwd) |path| {
            try w.print("cd {s} && ", .{path});
        }
        if (sc.child_env) |child_env| {
            for (child_env.keys(), child_env.values()) |key, value| {
                if (sc.parent_env) |parent_env| {
                    if (parent_env.get(key)) |process_value| {
                        if (mem.eql(u8, value, process_value)) continue;
                    }
                }
                try w.print("{s}=", .{key});
                try shellEscape(w, value, false);
                try w.writeByte(' ');
            }
        }
        try shellEscape(w, sc.argv[0], true);
        for (sc.argv[1..]) |arg| {
            try w.writeByte(' ');
            try shellEscape(w, arg, false);
        }
    }
};

/// 类似 `std.process.currentPathAlloc`,但还使用 `Dir.path.resolve` 解析路径。
/// 因此路径中不含重复分隔符、“.”或“..”部分,也不含末尾分隔符。
/// 在 WASI 上返回“”,而非“.”。
pub fn getResolvedCwd(io: Io, gpa: Allocator) std.process.CurrentPathAllocError![]u8 {
    if (builtin.os.tag == .wasi) {
        if (std.debug.runtime_safety) {
            const cwd = try std.process.currentPathAlloc(io, gpa);
            defer gpa.free(cwd);
            assert(mem.eql(u8, cwd, "."));
        }
        return "";
    }
    const cwd = try std.process.currentPathAlloc(io, gpa);
    defer gpa.free(cwd);
    const resolved = try Dir.path.resolve(gpa, &.{cwd});
    assert(Dir.path.isAbsolute(resolved));
    return resolved;
}

pub const Directories = struct {
    /// `introspect.getResolvedCwd` 返回的字符串。通常为绝对路径,
    /// 但 WASI 上改为空字符串,因为 WASI 没有绝对路径。
    cwd: []const u8,
    /// Zig 的“lib”目录。
    /// `zig_lib.path` 已解析(`resolvePath`),或在 cwd 情况下为 `null`。
    /// 保证该路径不同于 `global_cache` 和 `local_cache`。
    zig_lib: Cache.Directory,
    /// 全局 Zig 缓存目录。
    /// `global_cache.path` 已经解析(`resolvePath`),或为表示当前工作目录的 `null`。
    global_cache: Cache.Directory,
    /// 本地 Zig 缓存目录。
    /// `local_cache.path` 已解析(`resolvePath`),或为 `null` 以表示当前工作目录。
    /// 它可以与 `global_cache` 相同。
    local_cache: Cache.Directory,
    /// 包含 build.zig 的目录。使用构建系统时,
    /// 此路径由构建系统提供;否则为 `null`,
    /// 表示 cwd。
    build_root: Cache.Directory,

    pub fn deinit(dirs: *Directories, io: Io) void {
        // 本地缓存与全局缓存可能相同。
        const close_local = dirs.local_cache.handle.handle != dirs.global_cache.handle.handle;
        const close_build_root = dirs.build_root.handle.handle != Io.Dir.cwd().handle;

        dirs.global_cache.handle.close(io);
        if (close_local) dirs.local_cache.handle.close(io);
        dirs.zig_lib.handle.close(io);
        if (close_build_root) dirs.build_root.handle.close(io);
    }

    /// 返回一个将 `local_cache` 替换为 `global_cache` 的 `Directories`,供子编译
    /// 使用,例如 compiler_rt。不要对返回的 `Directories` 调用 `deinit`;
    /// 它与 `dirs` 共享句柄。
    pub fn withoutLocalCache(dirs: Directories) Directories {
        return .{
            .cwd = dirs.cwd,
            .zig_lib = dirs.zig_lib,
            .global_cache = dirs.global_cache,
            .local_cache = dirs.global_cache,
            .build_root = dirs.build_root,
        };
    }

    const LocalCacheStrategy = union(enum) {
        override: []const u8,
        search,
        global,
    };

    pub const InitOptions = struct {
        override_zig_lib: ?[]const u8,
        override_global_cache: ?[]const u8,
        build_root: ?[]const u8,
        local_cache_strat: LocalCacheStrategy,
        preopens: std.process.Preopens,
        self_exe_path: switch (builtin.target.os.tag) {
            .wasi => void,
            else => []const u8,
        },
        environ_map: *const std.process.Environ.Map,
        cwd: []const u8,
    };

    /// 遇到错误时使用 `std.process.fatal`。
    pub fn init(arena: Allocator, io: Io, options: InitOptions) Directories {
        const wasi = builtin.target.os.tag == .wasi;
        const cwd = options.cwd;

        const zig_lib: Cache.Directory = d: {
            if (options.override_zig_lib) |path| break :d openUnresolved(arena, io, cwd, path, .@"zig lib");
            if (wasi) break :d getPreopen(options.preopens, "/lib");
            break :d findZigLibDirFromSelfExe(arena, io, cwd, options.self_exe_path) catch |err| {
                fatal("unable to find zig installation directory from executable path {q}: {t}", .{
                    options.self_exe_path, err,
                });
            };
        };
        const build_root: Cache.Directory = if (options.build_root) |s|
            openUnresolved(arena, io, cwd, s, .@"build root")
        else
            .cwd();

        const global_cache: Cache.Directory = d: {
            if (options.override_global_cache) |path| break :d openUnresolved(arena, io, cwd, path, .@"global cache");
            if (wasi) break :d getPreopen(options.preopens, "/cache");
            const path = resolveGlobalCacheDir(arena, options.environ_map) catch |err| {
                fatal("unable to resolve zig cache directory: {t}", .{err});
            };
            break :d openUnresolved(arena, io, cwd, path, .@"global cache");
        };

        const local_cache = getLocalCacheDirectory(arena, io, cwd, global_cache, options.local_cache_strat);

        if (mem.eql(u8, zig_lib.path orelse "", global_cache.path orelse "")) {
            fatal("zig lib directory '{f}' cannot be equal to global cache directory '{f}'", .{ zig_lib, global_cache });
        }
        if (mem.eql(u8, zig_lib.path orelse "", local_cache.path orelse "")) {
            fatal("zig lib directory '{f}' cannot be equal to local cache directory '{f}'", .{ zig_lib, local_cache });
        }

        return .{
            .cwd = cwd,
            .zig_lib = zig_lib,
            .global_cache = global_cache,
            .local_cache = local_cache,
            .build_root = build_root,
        };
    }

    fn getLocalCacheDirectory(
        arena: Allocator,
        io: Io,
        cwd: []const u8,
        global_cache: Cache.Directory,
        local_cache_strat: LocalCacheStrategy,
    ) Cache.Directory {
        return switch (local_cache_strat) {
            .override => |path| openUnresolved(arena, io, cwd, path, .@"local cache"),
            .search => d: {
                const maybe_path = resolveSuitableLocalCacheDir(arena, io, cwd) catch |err|
                    fatal("unable to resolve zig cache directory: {t}", .{err});
                const path = maybe_path orelse break :d global_cache;
                break :d openUnresolved(arena, io, cwd, path, .@"local cache");
            },
            .global => global_cache,
        };
    }

    fn getPreopen(preopens: std.process.Preopens, name: []const u8) Cache.Directory {
        return .{
            .path = if (mem.eql(u8, name, ".")) null else name,
            .handle = switch (preopens.get(name) orelse fatal("preopen not found: {q}", .{name})) {
                .file => fatal("preopen {q} is not a directory", .{name}),
                .dir => |d| d,
            },
        };
    }
    pub fn openUnresolved(
        arena: Allocator,
        io: Io,
        cwd: []const u8,
        unresolved_path: []const u8,
        thing: enum { @"zig lib", @"global cache", @"local cache", @"build root" },
    ) Cache.Directory {
        const path = resolvePath(arena, cwd, &.{unresolved_path}) catch |err| {
            fatal("unable to resolve {t} directory: {t}", .{ thing, err });
        };
        const nonempty_path = if (path.len == 0) "." else path;
        const handle_or_err = switch (thing) {
            .@"zig lib", .@"build root" => Dir.cwd().openDir(io, nonempty_path, .{}),
            .@"global cache", .@"local cache" => Dir.cwd().createDirPathOpen(io, nonempty_path, .{}),
        };
        return .{
            .path = if (path.len == 0) null else path,
            .handle = handle_or_err catch |err| {
                const extra_str: []const u8 = e: {
                    if (thing == .@"global cache") switch (err) {
                        error.AccessDenied, error.ReadOnlyFileSystem => break :e "\n" ++
                            "If this location is not writable then consider specifying an alternative with " ++
                            "the ZIG_GLOBAL_CACHE_DIR environment variable or the --global-cache-dir option.",
                        else => {},
                    };
                    break :e "";
                };
                fatal("unable to open {t} directory {q}: {t}{s}", .{ thing, nonempty_path, err, extra_str });
            },
        };
    }
};

/// 目录句柄及路径均为新分配的资源,现由调用方拥有。
pub fn findZigLibDir(gpa: Allocator, io: Io) !Cache.Directory {
    const cwd_path = try getResolvedCwd(io, gpa);
    defer gpa.free(cwd_path);
    const self_exe_path = try std.process.executablePathAlloc(io, gpa);
    defer gpa.free(self_exe_path);

    return findZigLibDirFromSelfExe(gpa, io, cwd_path, self_exe_path);
}

/// 目录句柄及路径均为新分配的资源,现由调用方拥有。
pub fn findZigLibDirFromSelfExe(
    allocator: Allocator,
    io: Io,
    /// `getResolvedCwd` 的返回值。
    /// 作为参数传入,以避免无意义的重复调用。
    cwd_path: []const u8,
    self_exe_path: []const u8,
) error{ OutOfMemory, FileNotFound }!Cache.Directory {
    const cwd = Dir.cwd();
    var cur_path: []const u8 = self_exe_path;
    while (Dir.path.dirname(cur_path)) |dirname| : (cur_path = dirname) {
        var base_dir = cwd.openDir(io, dirname, .{}) catch continue;
        defer base_dir.close(io);

        const sub_directory = testZigInstallPrefix(io, base_dir) orelse continue;
        const p = try Dir.path.join(allocator, &.{ dirname, sub_directory.path.? });
        defer allocator.free(p);

        const resolved = try resolvePath(allocator, cwd_path, &.{p});
        return .{
            .handle = sub_directory.handle,
            .path = if (resolved.len == 0) null else resolved,
        };
    }
    return error.FileNotFound;
}

/// 返回有效的 sub_path;若均无效,则返回 `null`。
/// 返回 Directory 的路径相对于 `base`。
/// 返回 Directory 的句柄处于打开状态。
fn testZigInstallPrefix(io: Io, base_dir: Dir) ?Cache.Directory {
    const test_index_file = "std" ++ Dir.path.sep_str ++ "std.zig";

    zig_dir: {
        // 尝试 lib/zig/std/std.zig
        const lib_zig = "lib" ++ Dir.path.sep_str ++ "zig";
        var test_zig_dir = base_dir.openDir(io, lib_zig, .{}) catch break :zig_dir;
        const file = test_zig_dir.openFile(io, test_index_file, .{}) catch {
            test_zig_dir.close(io);
            break :zig_dir;
        };
        file.close(io);
        return .{ .handle = test_zig_dir, .path = lib_zig };
    }

    // 尝试 lib/std/std.zig
    var test_zig_dir = base_dir.openDir(io, "lib", .{}) catch return null;
    const file = test_zig_dir.openFile(io, test_index_file, .{}) catch {
        test_zig_dir.close(io);
        return null;
    };
    file.close(io);
    return .{ .handle = test_zig_dir, .path = "lib" };
}

pub fn resolveGlobalCacheDir(arena: Allocator, environ_map: *const std.process.Environ.Map) ![]const u8 {
    if (EnvVar.ZIG_GLOBAL_CACHE_DIR.get(environ_map)) |value| return value;

    const app_name = "zig";

    switch (builtin.os.tag) {
        .wasi => @compileError("on WASI the global cache dir must be resolved with preopens"),
        .windows => {
            const local_app_data_dir = EnvVar.LOCALAPPDATA.get(environ_map) orelse
                return error.AppDataDirUnavailable;
            return Dir.path.join(arena, &.{ local_app_data_dir, app_name });
        },
        else => {
            if (EnvVar.XDG_CACHE_HOME.get(environ_map)) |cache_root| {
                if (cache_root.len > 0) {
                    return Dir.path.join(arena, &.{ cache_root, app_name });
                }
            }
            if (EnvVar.HOME.get(environ_map)) |home| {
                if (home.len > 0) {
                    return Dir.path.join(arena, &.{ home, ".cache", app_name });
                }
            }
            return error.AppDataDirUnavailable;
        },
    }
}

/// 从 `cwd` 向上搜索包含 `build.zig` 文件的目录。
/// 若找到,返回该目录路径与 `.zig_cache` 名称拼接后的路径。
/// 否则返回 `null`,表示没有适合的本地缓存位置。
pub fn resolveSuitableLocalCacheDir(arena: Allocator, io: Io, cwd: []const u8) Allocator.Error!?[]u8 {
    var cur_dir = cwd;
    while (true) {
        const joined = try Dir.path.join(arena, &.{ cur_dir, build_zig_basename });
        if (Dir.cwd().access(io, joined, .{})) |_| {
            return try Dir.path.join(arena, &.{ cur_dir, default_local_zig_cache_basename });
        } else |err| switch (err) {
            error.FileNotFound => {
                cur_dir = Dir.path.dirname(cur_dir) orelse return null;
                continue;
            },
            else => return null,
        }
    }
}

/// 类似 `Dir.path.resolve`,但转换为相对于当前工作目录的路径;如果该路径
/// 以相对的上级目录(“..”)开头,则返回基于当前工作目录的绝对路径。此外,当前工作目录
/// 返回空串而非“.”。
pub fn resolvePath(
    gpa: Allocator,
    /// `getResolvedCwd` 的返回值。
    /// 作为参数传入,以避免无意义的重复调用。
    cwd_resolved: []const u8,
    paths: []const []const u8,
) Allocator.Error![]u8 {
    if (builtin.target.os.tag == .wasi) {
        assert(mem.eql(u8, cwd_resolved, ""));
        const res = try Dir.path.resolve(gpa, paths);
        if (mem.eql(u8, res, ".")) {
            gpa.free(res);
            return "";
        }
        return res;
    }

    // 快速路径启发式:如果没有绝对路径分量,也从未出现 "..",则只需解析 `paths`。
    for (paths) |p| {
        if (Dir.path.isAbsolute(p)) break; // 绝对路径
        if (mem.find(u8, p, "..") != null) break; // 可能包含上级目录
    } else {
        // 不含绝对路径或 ".."。
        const res = try Dir.path.resolve(gpa, paths);
        if (mem.eql(u8, res, ".")) {
            gpa.free(res);
            return "";
        }
        assert(!Dir.path.isAbsolute(res));
        assert(!isUpDir(res));
        return res;
    }

    // 快速路径失败;完整解析全部内容。
    // 优化:`paths` 通常只有一个元素。
    const path_resolved = switch (paths.len) {
        0 => unreachable,
        1 => try Dir.path.resolve(gpa, &.{ cwd_resolved, paths[0] }),
        else => r: {
            const all_paths = try gpa.alloc([]const u8, paths.len + 1);
            defer gpa.free(all_paths);
            all_paths[0] = cwd_resolved;
            @memcpy(all_paths[1..], paths);
            break :r try Dir.path.resolve(gpa, all_paths);
        },
    };
    errdefer gpa.free(path_resolved);

    assert(Dir.path.isAbsolute(path_resolved));
    assert(Dir.path.isAbsolute(cwd_resolved));

    if (!mem.startsWith(u8, path_resolved, cwd_resolved)) return path_resolved; // 不在当前工作目录中
    if (path_resolved.len == cwd_resolved.len) {
        // 等于当前工作目录
        gpa.free(path_resolved);
        return "";
    }
    if (path_resolved[cwd_resolved.len] != Dir.path.sep) return path_resolved; // 不在当前工作目录中(末尾组件不同)

    // 位于 cwd 内;提取子路径
    const sub_path = try gpa.dupe(u8, path_resolved[cwd_resolved.len + 1 ..]);
    gpa.free(path_resolved);
    return sub_path;
}

pub fn isUpDir(p: []const u8) bool {
    return mem.startsWith(u8, p, "..") and (p.len == 2 or p[2] == Dir.path.sep);
}

pub const BuildExeSubprocessOptions = struct {
    argv: []const []const u8,
    cache_root: Cache.Directory,
    root_name: []const u8,

    environ_map: ?*std.process.Environ.Map = null,
    cache_manifest: ?*Cache.Manifest = null,
    arch_os_abi: ?[]const u8 = null,
    cpu_features: ?[]const u8 = null,
    progress_node: std.Progress.Node = .none,
    skip_log_cmdline_on_compile_errors: bool = false,
    /// 若提供此项,则将编译错误发送到此处;否则打印到 stderr。
    /// 必须为已初始化的 `ErrorBundle`;更新之前会先将其清空。
    error_bundle: ?*ErrorBundle = null,
};

pub const BuildExeSubprocessError = error{
    /// 错误消息已记录。
    AlreadyReported,
    /// 错误消息已记录,源码文件已添加到 `Cache.Manifest`。
    FailedButCacheIntact,
} || Io.Cancelable || Allocator.Error;

pub const BuildExeSubprocessResult = struct {
    received_fs_inputs: bool,
    cache_hit: bool,
    path: Cache.Path,
};

/// 假定 `argv` 包含 `--listen=-`,且子进程为 `zig build-exe`。
///
/// 结果路径通过 gpa 分配。
pub fn buildExeSubprocess(
    gpa: Allocator,
    io: Io,
    options: BuildExeSubprocessOptions,
) BuildExeSubprocessError!BuildExeSubprocessResult {
    const cmd: SubprocessCommand = .{ .argv = options.argv };

    var child = std.process.spawn(io, .{
        .argv = options.argv,
        .environ_map = options.environ_map,
        .stdin = .pipe,
        .stdout = .pipe,
        .stderr = .pipe,
        .progress_node = options.progress_node,
    }) catch |err| {
        log.err("spawning command {t}: {f}", .{ err, cmd });
        return error.AlreadyReported;
    };
    defer child.kill(io);

    var multi_reader_buffer: Io.File.MultiReader.Buffer(2) = undefined;
    var multi_reader: Io.File.MultiReader = undefined;
    multi_reader.init(gpa, io, multi_reader_buffer.toStreams(), &.{ child.stdout.?, child.stderr.? });
    defer multi_reader.deinit();
    const stdout = multi_reader.reader(0);
    const stderr = multi_reader.reader(1);

    var stdin_buffer: [8]u8 = undefined;
    var stdin_writer = child.stdin.?.writerStreaming(io, &stdin_buffer);

    var client: Client = .{
        .in = stdout,
        .out = &stdin_writer.interface,
    };

    (blk: {
        client.serveMessageHeader(.{ .tag = .update, .bytes_len = 0 }) catch |err| break :blk err;
        client.serveMessageHeader(.{ .tag = .exit, .bytes_len = 0 }) catch |err| break :blk err;
        client.out.flush() catch |err| break :blk err;
    }) catch |err| switch (err) {
        error.WriteFailed => {
            if (stdin_writer.err.? == error.Canceled) return error.Canceled;
            log.err("{t} writing to command: {f}", .{ stdin_writer.err.?, cmd });
            return error.AlreadyReported;
        },
    };

    var result: ?Cache.Path = null;
    defer if (result) |r| gpa.free(r.sub_path);

    var default_error_bundle: ErrorBundle = .empty;
    defer default_error_bundle.deinit(gpa);

    const error_bundle = options.error_bundle orelse &default_error_bundle;

    var received_fs_inputs = false;
    var cache_hit = false;

    var eos_err: error{EndOfStream}!void = {};

    while (true) {
        const header = client.receiveMessageWithMultiReader(&multi_reader, .none) catch |err| switch (err) {
            error.Timeout => unreachable,
            error.EndOfStream => |e| {
                if (client.in.bufferedLen() == 0) break;
                // 最好通过下面的 stderr 报告崩溃,但仍设置此值,
                // 以防子进程违反此协议
                // 却成功退出。
                eos_err = e;
                break;
            },
            error.Canceled, error.OutOfMemory => |e| return e,
            else => |e| {
                log.err("{t} reading from command: {f}", .{ e, cmd });
                return error.AlreadyReported;
            },
        };
        const body = stdout.take(header.bytes_len) catch unreachable;

        switch (header.tag) {
            .zig_version => {
                if (!mem.eql(u8, builtin.zig_version_string, body)) {
                    log.err("zig protocol version mismatch from command: {f}", .{cmd});
                    return error.AlreadyReported;
                }
            },
            .error_bundle => {
                error_bundle.deinit(gpa);
                error_bundle.* = Server.allocErrorBundle(gpa, body) catch |err| switch (err) {
                    error.EndOfStream => break,
                    else => |e| return e,
                };
            },
            .emit_digest => {
                const EmitDigest = Server.Message.EmitDigest;
                const ebp_hdr: *align(1) const EmitDigest = @ptrCast(body);
                cache_hit = ebp_hdr.flags.cache_hit;
                const digest = body[@sizeOf(EmitDigest)..][0..Cache.bin_digest_len];
                if (result) |r| gpa.free(r.sub_path);
                result = .{
                    .root_dir = options.cache_root,
                    .sub_path = try Dir.path.join(gpa, &.{ "o", &Cache.binToHex(digest.*) }),
                };
            },
            .file_system_inputs => if (options.cache_manifest) |man| {
                received_fs_inputs = true;
                var it = mem.splitScalar(u8, body, 0);
                while (it.next()) |prefixed_path| {
                    const prefix: Server.Message.PathPrefix = @fromBackingInt(@intCast(prefixed_path[0] - 1));
                    const sub_path = prefixed_path[1..];
                    man.addDiscoveredPath(.{
                        .discovered_path = .{ .prefixed = .{
                            .prefix = @intCast(@backingInt(prefix)),
                            .sub_path = sub_path,
                        } },
                    }) catch |err| switch (err) {
                        error.Canceled, error.OutOfMemory => |e| return e,
                        else => |e| {
                            log.err("adding {t} {s} to cache failed: {t}", .{ prefix, sub_path, e });
                            return error.AlreadyReported;
                        },
                    };
                }
            },
            else => {}, // 忽略其他消息
        }
    }

    const stderr_contents = stderr.buffered();
    if (stderr_contents.len > 0)
        log.warn("unexpected stderr from {s} command:\n{s}", .{ options.argv[0], stderr_contents });

    eos_err catch {
        log.err("unexpected end of stream from command: {f}", .{cmd});
        return error.AlreadyReported;
    };

    // 向标准输入发送 EOF。
    child.stdin.?.close(io);
    child.stdin = null;

    const term = child.wait(io) catch |err| switch (err) {
        error.Canceled => |e| return e,
        else => |e| {
            log.err("{t} waiting for command: {f}", .{ e, cmd });
            return error.AlreadyReported;
        },
    };

    if (!term.success()) {
        log.err("command {f}: {f}", .{ term, cmd });
        if (received_fs_inputs) return error.FailedButCacheIntact;
        return error.AlreadyReported;
    }

    if (default_error_bundle.errorMessageCount() > 0) {
        default_error_bundle.renderToStderr(io, .{}, .auto) catch |err| switch (err) {
            error.Canceled => |e| return e,
            else => |e| {
                log.err("failed rendering error bundle: {t}", .{e});
                return error.AlreadyReported;
            },
        };
        if (!options.skip_log_cmdline_on_compile_errors) log.err("command reported {d} compilation errors: {f}", .{
            default_error_bundle.errorMessageCount(), cmd,
        });
        if (received_fs_inputs) return error.FailedButCacheIntact;
        return error.AlreadyReported;
    }

    if (error_bundle.errorMessageCount() > 0) {
        if (received_fs_inputs) return error.FailedButCacheIntact;
        return error.AlreadyReported;
    }

    const base_path = result orelse {
        log.err("command failed to report result: {f}", .{cmd});
        return error.AlreadyReported;
    };
    const parsed_target = system.resolveTargetQuery(io, std.Build.parseTargetQuery(.{
        .arch_os_abi = options.arch_os_abi orelse "native",
        .cpu_features = options.cpu_features,
    }) catch unreachable) catch unreachable;
    const bin_name = try binNameAlloc(gpa, .{
        .root_name = options.root_name,
        .cpu_arch = parsed_target.cpu.arch,
        .os_tag = parsed_target.os.tag,
        .ofmt = parsed_target.ofmt,
        .abi = parsed_target.abi,
        .output_mode = .Exe,
    });
    defer gpa.free(bin_name);
    return .{
        .received_fs_inputs = received_fs_inputs,
        .cache_hit = cache_hit,
        .path = try base_path.join(gpa, bin_name),
    };
}

test {
    _ = Ast;
    _ = AstRlAnnotate;
    _ = BuiltinFn;
    _ = Client;
    _ = ErrorBundle;
    _ = LibCDirs;
    _ = LibCInstallation;
    _ = Server;
    _ = TokenSmith;
    _ = WindowsSdk;
    _ = number_literal;
    _ = primitives;
    _ = string_literal;
    _ = system;
    _ = target;
    _ = c_translation;
    _ = llvm;
    _ = @import("zig/parser_fuzz.zig");
}