字段
ServerstdAllocatorassertCacheOutMessageInMessageReaderWriterConfigurationbuild_system_versionMessagereceiveMessagereceiveBody_u8receiveBody_u32receiveBody_u64serveStringMessageserveMessageHeaderserveBodylessMessageserveU32MessageserveU64MessageserveCoverageIdMessageserveBroadcastFuzzInputMessageserveEmitDigestserveTestResultsserveErrorBundleallocErrorBundleTestMetadataserveTestMetadataserveConfig
std.zig.Server.Allocator
别名
别名目标 std.mem.Allocator
std.zig.Server.allocErrorBundle
函数
pub fn allocErrorBundle(gpa: Allocator, body: []const u8) error{ OutOfMemory, EndOfStream }!std.zig.ErrorBundle
参数
gpa: Allocator
body: []const u8
错误
- EndOfStream
- OutOfMemory
std.zig.Server.assert
别名
别名目标 std.debug.assert
std.zig.Server.build_system_version
常量
u32
std.zig.Server.Cache
别名
别名目标 std.Build.Cache
std.zig.Server.Configuration
别名
std.zig.Server.InMessage
别名
std.zig.Server.Message
命名空间
std.zig.Server.Message.BuildStepCompleted
容器
尾随数据:
- error_bundle: ErrorBundle,
- generated_file: [generated_files_len]GeneratedFile,
- path_bytes: [_]u8, // 对每个 GeneratedFile
- PathPrefix
- sub_path: [_]u8,
字段
step_index: Configuration.Step.Index
status: Status
error_bundle: ErrorBundle
generated_files_len: u32
std.zig.Server.Message.BuildStepCompleted.Status
容器
字段
success
failure
skipped
skipped_oom
std.zig.Server.Message.Config
容器
由编译器决定的输出二进制目标属性。
字段
flags: Flags
std.zig.Server.Message.Config.Flags
容器
字段
std.zig.Server.Message.EmitDigest
容器
尾随数据:
- /o/ 子目录内缓存目录的十六进制摘要。
字段
flags: Flags
std.zig.Server.Message.EmitDigest.Flags
容器
字段
cache_hit: bool
reserved: u7 = 0
std.zig.Server.Message.ErrorBundle
容器
尾随数据:
- extra: [extra_len]u32,
- string_bytes: [string_bytes_len]u8,
参见
std.zig.ErrorBundle。
字段
extra_len: u32
string_bytes_len: u32
std.zig.Server.Message.GeneratedFile
容器
字段
std.zig.Server.Message.Handshake
容器
尾随字段:
- base_paths:BasePaths,
字段
std.zig.Server.Message.Handshake.Flags
容器
字段
file_system_watch_supported: bool
unused: u31 = 0
std.zig.Server.Message.Header
容器
字段
std.zig.Server.Message.InputDir
容器
对 .args 消息中某个 .input_dir 的引用。
字段
cwd相对于服务器 cwd 的路径,或绝对路径。
_按照 .input_dir 在 .args 消息中的出现顺序编号。
std.zig.Server.Message.PathPrefix
容器
字段
cwd
zig_lib
local_cache
global_cache
build_root
std.zig.Server.Message.Tag
容器
字段
zig_version正文为 UTF-8 字符串。
error_bundle主体为 ErrorBundle。
emit_digest主体为 EmitDigest。
test_metadata主体是 TestMetadata
test_results主体是 TestResults
test_started不包含主体。
通知构建运行器,由 Client.Message.Tag.run_test 请求的下一个测试
正在开始执行。此消息有助于确保在系统负载极高时,构建
运行器用于限制单元测试时间的时间戳仍较准确;
此时测试进程被调度之前可能存在明显延迟。
file_system_inputs主体是一系列由空字节分隔的字符串。 每个字符串是带前缀的文件路径。 第一个字节表示文件路径前缀,参见 Cache 的 prefixes 字段。传输时该字节值加一,以免空 字节与字符串终止符混淆。 其余字节为相对于该前缀的文件路径。 前缀硬编码于 Compilation.create 中:cwd、Zig 库目录、本地缓存目录。
coverage_id消息体为:
一个 u64le,指明缓存中用于保存覆盖率信息的文件路径。 此整数是该文件所存程序计数器地址的哈希值。
累计总运行次数,u64le
累计唯一运行次数,u64le
累计覆盖率,u64le
fuzz_start_addr消息体为 u64le,表示模糊测试单元测试的 函数指针虚拟内存地址。用作查看覆盖率的 起点。
fuzz_test_change主体为:
- u32le 测试索引。
broadcast_fuzz_input消息体为:
- u32le 测试索引
- 剩余字节作为输入
time_report正文为 TimeReport。
discovered_inputs消息体依次包含:
- root_dir: InputDir,
- sub_path: [:0]u8,
config主体是 Config。
bsp_handshake = 0x80000000服务器通过构建系统协议发送的第一条消息。
消息体为 Handshake。
此消息仅适用于构建系统协议。
bsp_configuration通知有新的配置文件可用。 消息体是相对于 cwd 的配置文件路径。 此消息仅适用于构建系统协议。
bsp_configuration_failedbuild.zig 本身从源码构建失败。
消息体为 ErrorBundle
此消息仅适用于构建系统协议。
bsp_build_started不含消息体。 此消息仅适用于构建系统协议。
bsp_build_completed不含消息体。 此消息仅适用于构建系统协议。
bsp_step_started消息体为 Configuration.Step.Index。
此消息仅适用于构建系统协议。
bsp_step_completed消息体为 BuildStepCompleted。
此消息仅适用于构建系统协议。
_
std.zig.Server.Message.TestMetadata
容器
尾随数据:
- name: [tests_len]u32
- 以 null 结尾的 string_bytes 索引
- expected_panic_msg: [tests_len]u32,
- 以 null 结尾的 string_bytes 索引
- 0 表示不预期发生 panic
- string_bytes: [string_bytes_len]u8,
字段
string_bytes_len: u32
tests_len: u32
std.zig.Server.Message.TestResults
容器
字段
index: u32
flags: Flags align(4)
std.zig.Server.Message.TestResults.Flags
容器
字段
std.zig.Server.Message.TestResults.Status
容器
字段
pass
fail
skip
std.zig.Server.Message.TimeReport
容器
尾随数据与 std.Build.abi.time_report.CompileResult 相同,但不包含 step_name。
字段
stats: std.Build.abi.time_report.CompileResult.Stats align(4)
llvm_pass_timings_len: u32
files_len: u32
decls_len: u32
flags: Flags
std.zig.Server.Message.TimeReport.Flags
容器
字段
use_llvm: bool
unused: u31 = 0
std.zig.Server.OutMessage
别名
std.zig.Server.Reader
别名
别名目标 std.Io.Reader
std.zig.Server.receiveBody_u32
函数
pub fn receiveBody_u32(s: *Server) !u32
参数
s: *Server
std.zig.Server.receiveBody_u64
函数
pub fn receiveBody_u64(s: *Server) !u64
参数
s: *Server
std.zig.Server.receiveBody_u8
函数
pub fn receiveBody_u8(s: *Server) !u8
参数
s: *Server
std.zig.Server.receiveMessage
函数
pub fn receiveMessage(s: *Server) !InMessage.Header
参数
s: *Server
std.zig.Server.serveBodylessMessage
函数
pub fn serveBodylessMessage(s: *const Server, tag: OutMessage.Tag) Writer.Error!void
参数
s: *const Server
tag: OutMessage.Tag
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.zig.Server.serveBroadcastFuzzInputMessage
函数
pub fn serveBroadcastFuzzInputMessage(s: *const Server, test_i: u32, bytes: []const u8) !void
参数
std.zig.Server.serveConfig
函数
pub fn serveConfig(s: *Server, config: OutMessage.Config) !void
参数
s: *Server
config: OutMessage.Config
std.zig.Server.serveCoverageIdMessage
函数
pub fn serveCoverageIdMessage(s: *const Server, id: u64, runs: u64, unique: u64, cov: u64) !void
参数
std.zig.Server.serveEmitDigest
函数
pub fn serveEmitDigest( s: *Server, digest: *const [Cache.bin_digest_len]u8, header: OutMessage.EmitDigest, ) !void
参数
std.zig.Server.serveErrorBundle
函数
pub fn serveErrorBundle(s: *Server, tag: Message.Tag, error_bundle: std.zig.ErrorBundle) !void
参数
std.zig.Server.serveMessageHeader
函数
不要忘记刷新!
pub fn serveMessageHeader(s: *const Server, header: OutMessage.Header) !void
参数
s: *const Server
header: OutMessage.Header
std.zig.Server.Server
别名
别名目标 std.zig.Server
std.zig.Server.serveStringMessage
函数
pub fn serveStringMessage(s: *Server, tag: OutMessage.Tag, msg: []const u8) !void
参数
std.zig.Server.serveTestMetadata
函数
pub fn serveTestMetadata(s: *Server, test_metadata: TestMetadata) !void
参数
s: *Server
test_metadata: TestMetadata
std.zig.Server.serveTestResults
函数
pub fn serveTestResults(s: *Server, msg: OutMessage.TestResults) !void
参数
s: *Server
msg: OutMessage.TestResults
std.zig.Server.serveU32Message
函数
pub fn serveU32Message(s: *const Server, tag: OutMessage.Tag, int: u32) !void
参数
std.zig.Server.serveU64Message
函数
pub fn serveU64Message(s: *const Server, tag: OutMessage.Tag, int: u64) !void
参数
std.zig.Server.std
别名
别名目标 std
std.zig.Server.TestMetadata
容器
字段
names: []const u32
expected_panic_msgs: []const u32
string_bytes: []const u8
std.zig.Server.Writer
别名
别名目标 std.Io.Writer
源码
std/zig/Server.zig
const Server = @This();
const std = @import("std");
const Allocator = std.mem.Allocator;
const assert = std.debug.assert;
const Cache = std.Build.Cache;
const OutMessage = std.zig.Server.Message;
const InMessage = std.zig.Client.Message;
const Reader = std.Io.Reader;
const Writer = std.Io.Writer;
const Configuration = std.Build.Configuration;
in: *Reader,
out: *Writer,
/// 构建系统协议的 ABI 版本。协议发生向后
/// 不兼容更改时递增。
///
/// 不适用于内部编译器协议或测试运行器。
///
/// 参见 `Message.Handshake` 中的 `version`。
pub const build_system_version: u32 = 1;
pub const Message = struct {
pub const Header = extern struct {
tag: Tag,
/// 仅消息体的大小,不包括此 Header。
bytes_len: u32,
};
pub const Tag = enum(u32) {
/// 正文为 UTF-8 字符串。
zig_version,
/// 主体为 ErrorBundle。
error_bundle,
/// 主体为 EmitDigest。
emit_digest,
/// 主体是 TestMetadata
test_metadata,
/// 主体是 TestResults
test_results,
/// 不包含主体。
/// 通知构建运行器,由 `Client.Message.Tag.run_test` 请求的下一个测试
/// 正在开始执行。此消息有助于确保在系统负载极高时,构建
/// 运行器用于限制单元测试时间的时间戳仍较准确;
/// 此时测试进程被调度之前可能存在明显延迟。
test_started,
/// 主体是一系列由空字节分隔的字符串。
/// 每个字符串是带前缀的文件路径。
/// 第一个字节表示文件路径前缀,参见 Cache
/// 的 prefixes 字段。传输时该字节值加一,以免空
/// 字节与字符串终止符混淆。
/// 其余字节为相对于该前缀的文件路径。
/// 前缀硬编码于 Compilation.create 中:cwd、Zig 库目录、本地缓存目录。
file_system_inputs,
/// 消息体为:
/// - 一个 u64le,指明缓存中用于保存覆盖率信息的文件路径。
/// 此整数是该文件所存程序计数器地址的哈希值。
///
/// - 累计总运行次数,u64le
/// - 累计唯一运行次数,u64le
/// - 累计覆盖率,u64le
coverage_id,
/// 消息体为 u64le,表示模糊测试单元测试的
/// 函数指针虚拟内存地址。用作查看覆盖率的
/// 起点。
fuzz_start_addr,
/// 主体为:
/// - u32le 测试索引。
fuzz_test_change,
/// 消息体为:
/// - u32le 测试索引
/// - 剩余字节作为输入
broadcast_fuzz_input,
/// 正文为 TimeReport。
time_report,
/// 消息体依次包含:
/// - root_dir: InputDir,
/// - sub_path: [:0]u8,
discovered_inputs,
/// 主体是 Config。
config,
/// 服务器通过构建系统协议发送的第一条消息。
/// 消息体为 `Handshake`。
/// 此消息仅适用于构建系统协议。
bsp_handshake = 0x80000000,
/// 通知有新的配置文件可用。
/// 消息体是相对于 cwd 的配置文件路径。
/// 此消息仅适用于构建系统协议。
bsp_configuration,
/// build.zig 本身从源码构建失败。
/// 消息体为 `ErrorBundle`
/// 此消息仅适用于构建系统协议。
bsp_configuration_failed,
/// 不含消息体。
/// 此消息仅适用于构建系统协议。
bsp_build_started,
/// 不含消息体。
/// 此消息仅适用于构建系统协议。
bsp_build_completed,
/// 消息体为 `Configuration.Step.Index`。
/// 此消息仅适用于构建系统协议。
bsp_step_started,
/// 消息体为 `BuildStepCompleted`。
/// 此消息仅适用于构建系统协议。
bsp_step_completed,
_,
};
/// 尾随字段:
/// * base_paths:BasePaths,
pub const Handshake = extern struct {
/// 参见 `build_system_version`。
version: u32,
flags: Flags,
pub const Flags = packed struct(u32) {
file_system_watch_supported: bool,
unused: u31 = 0,
};
};
/// 尾随数据:
/// * error_bundle: ErrorBundle,
/// * generated_file: [generated_files_len]GeneratedFile,
/// * path_bytes: [_]u8, // 对每个 GeneratedFile
/// - PathPrefix
/// - sub_path: [_]u8,
pub const BuildStepCompleted = extern struct {
step_index: Configuration.Step.Index,
status: Status,
error_bundle: ErrorBundle,
generated_files_len: u32,
// TODO result_error_msgs
// TODO result_stderr
// TODO result_peak_rss
// TODO result_duration_ns
pub const Status = enum(u32) {
success,
failure,
skipped,
skipped_oom,
};
};
pub const GeneratedFile = extern struct {
index: Configuration.GeneratedFileIndex,
/// 仅包含路径字节,不包含前缀或空字节。
path_len: u32,
};
pub const PathPrefix = enum(u8) {
cwd,
zig_lib,
local_cache,
global_cache,
build_root,
};
/// 尾随数据:
/// * extra: [extra_len]u32,
/// * string_bytes: [string_bytes_len]u8,
/// 参见 `std.zig.ErrorBundle`。
pub const ErrorBundle = extern struct {
extra_len: u32,
string_bytes_len: u32,
};
/// 尾随数据:
/// * name: [tests_len]u32
/// - 以 null 结尾的 string_bytes 索引
/// * expected_panic_msg: [tests_len]u32,
/// - 以 null 结尾的 string_bytes 索引
/// - 0 表示不预期发生 panic
/// * string_bytes: [string_bytes_len]u8,
pub const TestMetadata = extern struct {
string_bytes_len: u32,
tests_len: u32,
};
pub const TestResults = extern struct {
index: u32,
flags: Flags align(4),
pub const Flags = packed struct(u64) {
status: Status,
fuzz: bool,
log_err_count: u30,
leak_count: u31,
};
pub const Status = enum(u2) { pass, fail, skip };
};
/// 尾随数据与 `std.Build.abi.time_report.CompileResult` 相同,但不包含 `step_name`。
pub const TimeReport = extern struct {
stats: std.Build.abi.time_report.CompileResult.Stats align(4),
llvm_pass_timings_len: u32,
files_len: u32,
decls_len: u32,
flags: Flags,
pub const Flags = packed struct(u32) {
use_llvm: bool,
unused: u31 = 0,
};
};
/// 尾随数据:
/// * /o/ 子目录内缓存目录的十六进制摘要。
pub const EmitDigest = extern struct {
flags: Flags,
pub const Flags = packed struct(u8) {
cache_hit: bool,
reserved: u7 = 0,
};
};
/// 对 `.args` 消息中某个 `.input_dir` 的引用。
pub const InputDir = enum(u32) {
/// 相对于服务器 cwd 的路径,或绝对路径。
cwd,
/// 按照 `.input_dir` 在 `.args` 消息中的出现顺序编号。
_,
};
/// 由编译器决定的输出二进制目标属性。
pub const Config = extern struct {
flags: Flags,
pub const Flags = packed struct(u8) {
output_mode: std.lang.OutputMode,
link_mode: std.lang.LinkMode,
link_libc: bool,
link_libcpp: bool,
link_libunwind: bool,
pie: bool,
unused: u1 = 0,
};
};
};
pub fn receiveMessage(s: *Server) !InMessage.Header {
return s.in.takeStruct(InMessage.Header, .little);
}
pub fn receiveBody_u8(s: *Server) !u8 {
return s.in.takeInt(u8, .little);
}
pub fn receiveBody_u32(s: *Server) !u32 {
return s.in.takeInt(u32, .little);
}
pub fn receiveBody_u64(s: *Server) !u64 {
return s.in.takeInt(u64, .little);
}
pub fn serveStringMessage(s: *Server, tag: OutMessage.Tag, msg: []const u8) !void {
try s.serveMessageHeader(.{
.tag = tag,
.bytes_len = @intCast(msg.len),
});
try s.out.writeAll(msg);
try s.out.flush();
}
/// 不要忘记刷新!
pub fn serveMessageHeader(s: *const Server, header: OutMessage.Header) !void {
try s.out.writeStruct(header, .little);
}
pub fn serveBodylessMessage(s: *const Server, tag: OutMessage.Tag) Writer.Error!void {
try s.serveMessageHeader(.{ .tag = tag, .bytes_len = 0 });
try s.out.flush();
}
pub fn serveU32Message(s: *const Server, tag: OutMessage.Tag, int: u32) !void {
try serveMessageHeader(s, .{
.tag = tag,
.bytes_len = @sizeOf(u32),
});
try s.out.writeInt(u32, int, .little);
try s.out.flush();
}
pub fn serveU64Message(s: *const Server, tag: OutMessage.Tag, int: u64) !void {
assert(tag != .coverage_id);
try serveMessageHeader(s, .{
.tag = tag,
.bytes_len = @sizeOf(u64),
});
try s.out.writeInt(u64, int, .little);
try s.out.flush();
}
pub fn serveCoverageIdMessage(s: *const Server, id: u64, runs: u64, unique: u64, cov: u64) !void {
try serveMessageHeader(s, .{
.tag = .coverage_id,
.bytes_len = @sizeOf(u64) + @sizeOf(u64) + @sizeOf(u64) + @sizeOf(u64),
});
try s.out.writeInt(u64, id, .little);
try s.out.writeInt(u64, runs, .little);
try s.out.writeInt(u64, unique, .little);
try s.out.writeInt(u64, cov, .little);
try s.out.flush();
}
pub fn serveBroadcastFuzzInputMessage(s: *const Server, test_i: u32, bytes: []const u8) !void {
try s.serveMessageHeader(.{
.tag = .broadcast_fuzz_input,
.bytes_len = @sizeOf(u32) + @as(u32, @intCast(bytes.len)),
});
try s.out.writeInt(u32, test_i, .little);
try s.out.writeAll(bytes);
try s.out.flush();
}
pub fn serveEmitDigest(
s: *Server,
digest: *const [Cache.bin_digest_len]u8,
header: OutMessage.EmitDigest,
) !void {
try s.serveMessageHeader(.{
.tag = .emit_digest,
.bytes_len = @intCast(digest.len + @sizeOf(OutMessage.EmitDigest)),
});
try s.out.writeStruct(header, .little);
try s.out.writeAll(digest);
try s.out.flush();
}
pub fn serveTestResults(s: *Server, msg: OutMessage.TestResults) !void {
try s.serveMessageHeader(.{
.tag = .test_results,
.bytes_len = @intCast(@sizeOf(OutMessage.TestResults)),
});
try s.out.writeStruct(msg, .little);
try s.out.flush();
}
pub fn serveErrorBundle(s: *Server, tag: Message.Tag, error_bundle: std.zig.ErrorBundle) !void {
const eb_hdr: OutMessage.ErrorBundle = .{
.extra_len = @intCast(error_bundle.extra.len),
.string_bytes_len = @intCast(error_bundle.string_bytes.len),
};
const bytes_len = @sizeOf(OutMessage.ErrorBundle) +
4 * error_bundle.extra.len + error_bundle.string_bytes.len;
try s.serveMessageHeader(.{
.tag = tag,
.bytes_len = @intCast(bytes_len),
});
try s.out.writeStruct(eb_hdr, .little);
try s.out.writeSliceEndian(u32, error_bundle.extra, .little);
try s.out.writeAll(error_bundle.string_bytes);
try s.out.flush();
}
pub fn allocErrorBundle(gpa: Allocator, body: []const u8) error{ OutOfMemory, EndOfStream }!std.zig.ErrorBundle {
var r: Reader = .fixed(body);
const hdr = r.takeStruct(OutMessage.ErrorBundle, .little) catch |err| switch (err) {
error.ReadFailed => unreachable,
error.EndOfStream => |e| return e,
};
return std.zig.ErrorBundle.readAlloc(&r, gpa, hdr.extra_len, hdr.string_bytes_len) catch |err| switch (err) {
error.ReadFailed => unreachable,
else => |e| return e,
};
}
pub const TestMetadata = struct {
names: []const u32,
expected_panic_msgs: []const u32,
string_bytes: []const u8,
};
pub fn serveTestMetadata(s: *Server, test_metadata: TestMetadata) !void {
const header: OutMessage.TestMetadata = .{
.tests_len = @intCast(test_metadata.names.len),
.string_bytes_len = @intCast(test_metadata.string_bytes.len),
};
const trailing = 2;
const bytes_len = @sizeOf(OutMessage.TestMetadata) +
trailing * @sizeOf(u32) * test_metadata.names.len + test_metadata.string_bytes.len;
try s.serveMessageHeader(.{
.tag = .test_metadata,
.bytes_len = @intCast(bytes_len),
});
try s.out.writeStruct(header, .little);
try s.out.writeSliceEndian(u32, test_metadata.names, .little);
try s.out.writeSliceEndian(u32, test_metadata.expected_panic_msgs, .little);
try s.out.writeAll(test_metadata.string_bytes);
try s.out.flush();
}
pub fn serveConfig(s: *Server, config: OutMessage.Config) !void {
try s.serveMessageHeader(.{
.tag = .config,
.bytes_len = @intCast(@sizeOf(OutMessage.Config)),
});
try s.out.writeStruct(config, .little);
try s.out.flush();
}