Fields
ServerstdAllocatorassertCacheOutMessageInMessageReaderWriterConfigurationbuild_system_versionMessagereceiveMessagereceiveBody_u8receiveBody_u32receiveBody_u64serveStringMessageserveMessageHeaderserveBodylessMessageserveU32MessageserveU64MessageserveCoverageIdMessageserveBroadcastFuzzInputMessageserveEmitDigestserveTestResultsserveErrorBundleallocErrorBundleTestMetadataserveTestMetadataserveConfig
std.zig.Server.Allocator
alias
Alias of std.mem.Allocator
std.zig.Server.allocErrorBundle
function
pub fn allocErrorBundle(gpa: Allocator, body: []const u8) error{ OutOfMemory, EndOfStream }!std.zig.ErrorBundle
Parameters
gpa: Allocator
body: []const u8
Errors
- EndOfStream
- OutOfMemory
std.zig.Server.assert
alias
Alias of std.debug.assert
std.zig.Server.build_system_version
constant
The ABI version of the build system protocol. Will be bumped whenever a backwards incompatible changes to the protocol is made.
Does not apply to the internal compiler protocol or test runner.
See version in Message.Handshake.
u32
std.zig.Server.Cache
alias
Alias of std.Build.Cache
std.zig.Server.Configuration
alias
Alias of std.Build.Configuration
std.zig.Server.InMessage
alias
Alias of std.zig.Client.Message
std.zig.Server.Message
namespace
std.zig.Server.Message.BuildStepCompleted
container
Trailing:
- error_bundle: ErrorBundle,
- generated_file: [generated_files_len]GeneratedFile,
- path_bytes: [_]u8, // for each GeneratedFile
- PathPrefix
- sub_path: [_]u8,
Fields
step_index: Configuration.Step.Index
status: Status
error_bundle: ErrorBundle
generated_files_len: u32
std.zig.Server.Message.BuildStepCompleted.Status
container
Fields
success
failure
skipped
skipped_oom
std.zig.Server.Message.Config
container
Properties of the output binary target that are decided by the compiler.
Fields
flags: Flags
std.zig.Server.Message.Config.Flags
container
Fields
std.zig.Server.Message.EmitDigest
container
Trailing:
- the hex digest of the cache directory within the /o/ subdirectory.
Fields
flags: Flags
std.zig.Server.Message.EmitDigest.Flags
container
Fields
cache_hit: bool
reserved: u7 = 0
std.zig.Server.Message.ErrorBundle
container
Trailing:
- extra: [extra_len]u32,
- string_bytes: [string_bytes_len]u8,
See
std.zig.ErrorBundle.
Fields
extra_len: u32
string_bytes_len: u32
std.zig.Server.Message.GeneratedFile
container
Fields
index: Configuration.GeneratedFileIndex
path_len: u32Includes only the path bytes, not the prefix or null byte.
std.zig.Server.Message.Handshake
container
Trailing:
- base_paths: BasePaths,
Fields
std.zig.Server.Message.Handshake.Flags
container
Fields
file_system_watch_supported: bool
unused: u31 = 0
std.zig.Server.Message.Header
container
Fields
std.zig.Server.Message.InputDir
container
A reference to one of the .input_dirs from the .args message.
Fields
cwdServer cwd relative path, or absolute path.
_Numbered in the order that .input_dirs appear in the .args message.
std.zig.Server.Message.PathPrefix
container
Fields
cwd
zig_lib
local_cache
global_cache
build_root
std.zig.Server.Message.Tag
container
Fields
zig_versionBody is a UTF-8 string.
error_bundleBody is an ErrorBundle.
emit_digestBody is a EmitDigest.
test_metadataBody is a TestMetadata
test_resultsBody is a TestResults
test_startedDoes not have a body.
Notifies the build runner that the next test (requested by Client.Message.Tag.run_test)
is starting execution. This message helps to ensure that the timestamp used by the build
runner to enforce unit test time limits is relatively accurate under extreme system load
(where there may be a non-trivial delay before the test process is scheduled).
file_system_inputsBody is a series of strings, delimited by null bytes. Each string is a prefixed file path. The first byte indicates the file prefix path (see prefixes fields of Cache). This byte is sent over the wire incremented so that null bytes are not confused with string terminators. The remaining bytes is the file path relative to that prefix. The prefixes are hard-coded in Compilation.create (cwd, zig lib dir, local cache dir)
coverage_idBody is:
- a u64le that indicates the file path within the cache used to store coverage information. The integer is a hash of the PCs stored within that file.
- u64le of total runs accumulated
- u64le of unique runs accumulated
- u64le of coverage accumulated
fuzz_start_addrBody is a u64le that indicates the function pointer virtual memory address of the fuzz unit test. This is used to provide a starting point to view coverage.
fuzz_test_changeBody is:
- u32le test index.
broadcast_fuzz_inputBody is:
- u32le test index
- input in remaining bytes
time_reportBody is a TimeReport.
discovered_inputsBody is a sequence of:
- root_dir: InputDir,
- sub_path: [:0]u8,
configBody is a Config.
bsp_handshake = 0x80000000The first message sent by the server over the build system protocol.
Body is a Handshake.
This message only applies to the build system protocol.
bsp_configurationNotifies that a new configuration file is available. Body is a cwd relative path to the configuration file. This message only applies to the build system protocol.
bsp_configuration_failedbuild.zig itself failed to build from source.
Body is an ErrorBundle
This message only applies to the build system protocol.
bsp_build_startedDoes not have a body. This message only applies to the build system protocol.
bsp_build_completedDoes not have a body. This message only applies to the build system protocol.
bsp_step_startedBody is a Configuration.Step.Index.
This message only applies to the build system protocol.
bsp_step_completedBody is a BuildStepCompleted.
This message only applies to the build system protocol.
_
std.zig.Server.Message.TestMetadata
container
Trailing:
- name: [tests_len]u32
- null-terminated string_bytes index
- expected_panic_msg: [tests_len]u32,
- null-terminated string_bytes index
- 0 means does not expect panic
- string_bytes: [string_bytes_len]u8,
Fields
string_bytes_len: u32
tests_len: u32
std.zig.Server.Message.TestResults
container
Fields
index: u32
flags: Flags align(4)
std.zig.Server.Message.TestResults.Flags
container
Fields
std.zig.Server.Message.TestResults.Status
container
Fields
pass
fail
skip
std.zig.Server.Message.TimeReport
container
Trailing is the same as in std.Build.abi.time_report.CompileResult, excluding step_name.
Fields
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
container
Fields
use_llvm: bool
unused: u31 = 0
std.zig.Server.OutMessage
alias
Alias of std.zig.Server.Message
std.zig.Server.Reader
alias
Alias of std.Io.Reader
std.zig.Server.receiveBody_u32
function
pub fn receiveBody_u32(s: *Server) !u32
Parameters
s: *Server
std.zig.Server.receiveBody_u64
function
pub fn receiveBody_u64(s: *Server) !u64
Parameters
s: *Server
std.zig.Server.receiveBody_u8
function
pub fn receiveBody_u8(s: *Server) !u8
Parameters
s: *Server
std.zig.Server.receiveMessage
function
pub fn receiveMessage(s: *Server) !InMessage.Header
Parameters
s: *Server
std.zig.Server.serveBodylessMessage
function
pub fn serveBodylessMessage(s: *const Server, tag: OutMessage.Tag) Writer.Error!void
Parameters
s: *const Server
tag: OutMessage.Tag
Errors
- WriteFailed
See the
Writerimplementation for detailed diagnostics.
std.zig.Server.serveBroadcastFuzzInputMessage
function
pub fn serveBroadcastFuzzInputMessage(s: *const Server, test_i: u32, bytes: []const u8) !void
Parameters
std.zig.Server.serveConfig
function
pub fn serveConfig(s: *Server, config: OutMessage.Config) !void
Parameters
s: *Server
config: OutMessage.Config
std.zig.Server.serveCoverageIdMessage
function
pub fn serveCoverageIdMessage(s: *const Server, id: u64, runs: u64, unique: u64, cov: u64) !void
Parameters
std.zig.Server.serveEmitDigest
function
pub fn serveEmitDigest( s: *Server, digest: *const [Cache.bin_digest_len]u8, header: OutMessage.EmitDigest, ) !void
Parameters
std.zig.Server.serveErrorBundle
function
pub fn serveErrorBundle(s: *Server, tag: Message.Tag, error_bundle: std.zig.ErrorBundle) !void
Parameters
std.zig.Server.serveMessageHeader
function
Don't forget to flush!
pub fn serveMessageHeader(s: *const Server, header: OutMessage.Header) !void
Parameters
s: *const Server
header: OutMessage.Header
std.zig.Server.Server
alias
Alias of std.zig.Server
std.zig.Server.serveStringMessage
function
pub fn serveStringMessage(s: *Server, tag: OutMessage.Tag, msg: []const u8) !void
Parameters
std.zig.Server.serveTestMetadata
function
pub fn serveTestMetadata(s: *Server, test_metadata: TestMetadata) !void
Parameters
s: *Server
test_metadata: TestMetadata
std.zig.Server.serveTestResults
function
pub fn serveTestResults(s: *Server, msg: OutMessage.TestResults) !void
Parameters
s: *Server
msg: OutMessage.TestResults
std.zig.Server.serveU32Message
function
pub fn serveU32Message(s: *const Server, tag: OutMessage.Tag, int: u32) !void
Parameters
std.zig.Server.serveU64Message
function
pub fn serveU64Message(s: *const Server, tag: OutMessage.Tag, int: u64) !void
Parameters
std.zig.Server.std
alias
Alias of std
std.zig.Server.TestMetadata
container
Fields
names: []const u32
expected_panic_msgs: []const u32
string_bytes: []const u8
std.zig.Server.Writer
alias
Alias of std.Io.Writer
Source code
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,
/// The ABI version of the build system protocol. Will be bumped whenever a
/// backwards incompatible changes to the protocol is made.
///
/// Does not apply to the internal compiler protocol or test runner.
///
/// See `version` in `Message.Handshake`.
pub const build_system_version: u32 = 1;
pub const Message = struct {
pub const Header = extern struct {
tag: Tag,
/// Size of the body only; does not include this Header.
bytes_len: u32,
};
pub const Tag = enum(u32) {
/// Body is a UTF-8 string.
zig_version,
/// Body is an ErrorBundle.
error_bundle,
/// Body is a EmitDigest.
emit_digest,
/// Body is a TestMetadata
test_metadata,
/// Body is a TestResults
test_results,
/// Does not have a body.
/// Notifies the build runner that the next test (requested by `Client.Message.Tag.run_test`)
/// is starting execution. This message helps to ensure that the timestamp used by the build
/// runner to enforce unit test time limits is relatively accurate under extreme system load
/// (where there may be a non-trivial delay before the test process is scheduled).
test_started,
/// Body is a series of strings, delimited by null bytes.
/// Each string is a prefixed file path.
/// The first byte indicates the file prefix path (see prefixes fields
/// of Cache). This byte is sent over the wire incremented so that null
/// bytes are not confused with string terminators.
/// The remaining bytes is the file path relative to that prefix.
/// The prefixes are hard-coded in Compilation.create (cwd, zig lib dir, local cache dir)
file_system_inputs,
/// Body is:
/// - a u64le that indicates the file path within the cache used
/// to store coverage information. The integer is a hash of the PCs
/// stored within that file.
/// - u64le of total runs accumulated
/// - u64le of unique runs accumulated
/// - u64le of coverage accumulated
coverage_id,
/// Body is a u64le that indicates the function pointer virtual memory
/// address of the fuzz unit test. This is used to provide a starting
/// point to view coverage.
fuzz_start_addr,
/// Body is:
/// - u32le test index.
fuzz_test_change,
/// Body is:
/// - u32le test index
/// - input in remaining bytes
broadcast_fuzz_input,
/// Body is a TimeReport.
time_report,
/// Body is a sequence of:
/// - root_dir: InputDir,
/// - sub_path: [:0]u8,
discovered_inputs,
/// Body is a Config.
config,
/// The first message sent by the server over the build system protocol.
/// Body is a `Handshake`.
/// This message only applies to the build system protocol.
bsp_handshake = 0x80000000,
/// Notifies that a new configuration file is available.
/// Body is a cwd relative path to the configuration file.
/// This message only applies to the build system protocol.
bsp_configuration,
/// build.zig itself failed to build from source.
/// Body is an `ErrorBundle`
/// This message only applies to the build system protocol.
bsp_configuration_failed,
/// Does not have a body.
/// This message only applies to the build system protocol.
bsp_build_started,
/// Does not have a body.
/// This message only applies to the build system protocol.
bsp_build_completed,
/// Body is a `Configuration.Step.Index`.
/// This message only applies to the build system protocol.
bsp_step_started,
/// Body is a `BuildStepCompleted`.
/// This message only applies to the build system protocol.
bsp_step_completed,
_,
};
/// Trailing:
/// * base_paths: BasePaths,
pub const Handshake = extern struct {
/// See `build_system_version`.
version: u32,
flags: Flags,
pub const Flags = packed struct(u32) {
file_system_watch_supported: bool,
unused: u31 = 0,
};
};
/// Trailing:
/// * error_bundle: ErrorBundle,
/// * generated_file: [generated_files_len]GeneratedFile,
/// * path_bytes: [_]u8, // for each 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,
/// Includes only the path bytes, not the prefix or null byte.
path_len: u32,
};
pub const PathPrefix = enum(u8) {
cwd,
zig_lib,
local_cache,
global_cache,
build_root,
};
/// Trailing:
/// * extra: [extra_len]u32,
/// * string_bytes: [string_bytes_len]u8,
/// See `std.zig.ErrorBundle`.
pub const ErrorBundle = extern struct {
extra_len: u32,
string_bytes_len: u32,
};
/// Trailing:
/// * name: [tests_len]u32
/// - null-terminated string_bytes index
/// * expected_panic_msg: [tests_len]u32,
/// - null-terminated string_bytes index
/// - 0 means does not expect 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 };
};
/// Trailing is the same as in `std.Build.abi.time_report.CompileResult`, excluding `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,
};
};
/// Trailing:
/// * the hex digest of the cache directory within the /o/ subdirectory.
pub const EmitDigest = extern struct {
flags: Flags,
pub const Flags = packed struct(u8) {
cache_hit: bool,
reserved: u7 = 0,
};
};
/// A reference to one of the `.input_dir`s from the `.args` message.
pub const InputDir = enum(u32) {
/// Server cwd relative path, or absolute path.
cwd,
/// Numbered in the order that `.input_dir`s appear in the `.args` message.
_,
};
/// Properties of the output binary target that are decided by the compiler.
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();
}
/// Don't forget to 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();
}