Skip to content
Standard libraryZig 0.17.1Official documentation
Sourcestd/zig/Server.zig

Source line 1

Fields

in: *Reader
out: *Writer

std.zig.Server.Allocator

alias

Source line 4

Alias of std.mem.Allocator

std.zig.Server.allocErrorBundle

function

Source line 360

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

Source line 5

Alias of std.debug.assert

std.zig.Server.build_system_version

constant

Source line 22

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

Source line 6

Alias of std.Build.Cache

std.zig.Server.Configuration

alias

Source line 11

Alias of std.Build.Configuration

std.zig.Server.InMessage

alias

Source line 8

Alias of std.zig.Client.Message

std.zig.Server.Message

namespace

Source line 24

std.zig.Server.Message.BuildStepCompleted

container

Source line 131

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

Source line 141

Fields

success
failure
skipped
skipped_oom

std.zig.Server.Message.Config

container

Source line 231

Properties of the output binary target that are decided by the compiler.

Fields

flags: Flags

std.zig.Server.Message.Config.Flags

container

Source line 234

Fields

output_mode: std.lang.OutputMode
link_mode: std.lang.LinkMode
link_libc: bool
link_libcpp: bool
link_libunwind: bool
pie: bool
unused: u1 = 0

std.zig.Server.Message.EmitDigest

container

Source line 213

Trailing:

  • the hex digest of the cache directory within the /o/ subdirectory.

Fields

flags: Flags

std.zig.Server.Message.EmitDigest.Flags

container

Source line 216

Fields

cache_hit: bool
reserved: u7 = 0

std.zig.Server.Message.ErrorBundle

container

Source line 167

Trailing:

Fields

extra_len: u32
string_bytes_len: u32

std.zig.Server.Message.GeneratedFile

container

Source line 149

Fields

index: Configuration.GeneratedFileIndex
path_len: u32

Includes only the path bytes, not the prefix or null byte.

std.zig.Server.Message.Handshake

container

Source line 114

Trailing:

  • base_paths: BasePaths,

Fields

version: u32
flags: Flags

std.zig.Server.Message.Handshake.Flags

container

Source line 119

Fields

file_system_watch_supported: bool
unused: u31 = 0

std.zig.Server.Message.Header

container

Source line 25

Fields

tag: Tag
bytes_len: u32

Size of the body only; does not include this Header.

std.zig.Server.Message.InputDir

container

Source line 223

A reference to one of the .input_dirs from the .args message.

Fields

cwd

Server cwd relative path, or absolute path.

_

Numbered in the order that .input_dirs appear in the .args message.

std.zig.Server.Message.PathPrefix

container

Source line 155

Fields

cwd
zig_lib
local_cache
global_cache
build_root

std.zig.Server.Message.Tag

container

Source line 31

Fields

zig_version

Body is a UTF-8 string.

error_bundle

Body is an ErrorBundle.

emit_digest

Body is a EmitDigest.

test_metadata

Body is a TestMetadata

test_results

Body is a TestResults

test_started

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).

file_system_inputs

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)

coverage_id

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
fuzz_start_addr

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_test_change

Body is:

  • u32le test index.
broadcast_fuzz_input

Body is:

  • u32le test index
  • input in remaining bytes
time_report

Body is a TimeReport.

discovered_inputs

Body is a sequence of:

  • root_dir: InputDir,
  • sub_path: [:0]u8,
config

Body is a Config.

bsp_handshake = 0x80000000

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_configuration

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_failed

build.zig itself failed to build from source. Body is an ErrorBundle 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

Does not have a body. This message only applies to the build system protocol.

bsp_step_started

Body is a Configuration.Step.Index. This message only applies to the build system protocol.

bsp_step_completed

Body is a BuildStepCompleted. This message only applies to the build system protocol.

_

std.zig.Server.Message.TestMetadata

container

Source line 179

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

Source line 184

Fields

index: u32
flags: Flags align(4)

std.zig.Server.Message.TestResults.Flags

container

Source line 188

Fields

status: Status
fuzz: bool
log_err_count: u30
leak_count: u31

std.zig.Server.Message.TestResults.Status

container

Source line 195

Fields

pass
fail
skip

std.zig.Server.Message.TimeReport

container

Source line 199

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

Source line 205

Fields

use_llvm: bool
unused: u31 = 0

std.zig.Server.OutMessage

alias

Source line 7

Alias of std.zig.Server.Message

std.zig.Server.Reader

alias

Source line 9

Alias of std.Io.Reader

std.zig.Server.receiveBody_u32

function

Source line 253

pub fn receiveBody_u32(s: *Server) !u32

Parameters

s: *Server

std.zig.Server.receiveBody_u64

function

Source line 256

pub fn receiveBody_u64(s: *Server) !u64

Parameters

s: *Server

std.zig.Server.receiveBody_u8

function

Source line 250

pub fn receiveBody_u8(s: *Server) !u8

Parameters

s: *Server

std.zig.Server.receiveMessage

function

Source line 246

pub fn receiveMessage(s: *Server) !InMessage.Header

Parameters

s: *Server

std.zig.Server.serveBodylessMessage

function

Source line 274

pub fn serveBodylessMessage(s: *const Server, tag: OutMessage.Tag) Writer.Error!void

Parameters

s: *const Server
tag: OutMessage.Tag

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.zig.Server.serveBroadcastFuzzInputMessage

function

Source line 310

pub fn serveBroadcastFuzzInputMessage(s: *const Server, test_i: u32, bytes: []const u8) !void

Parameters

s: *const Server
test_i: u32
bytes: []const u8

std.zig.Server.serveConfig

function

Source line 398

pub fn serveConfig(s: *Server, config: OutMessage.Config) !void

Parameters

s: *Server
config: OutMessage.Config

std.zig.Server.serveCoverageIdMessage

function

Source line 298

pub fn serveCoverageIdMessage(s: *const Server, id: u64, runs: u64, unique: u64, cov: u64) !void

Parameters

s: *const Server
id: u64
runs: u64
unique: u64
cov: u64

std.zig.Server.serveEmitDigest

function

Source line 320

pub fn serveEmitDigest( s: *Server, digest: *const [Cache.bin_digest_len]u8, header: OutMessage.EmitDigest, ) !void

Parameters

s: *Server
digest: *const [Cache.bin_digest_len]u8
header: OutMessage.EmitDigest

std.zig.Server.serveErrorBundle

function

Source line 343

pub fn serveErrorBundle(s: *Server, tag: Message.Tag, error_bundle: std.zig.ErrorBundle) !void

Parameters

s: *Server
tag: Message.Tag
error_bundle: std.zig.ErrorBundle

std.zig.Server.serveMessageHeader

function

Source line 270

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

Source line 1

Alias of std.zig.Server

std.zig.Server.serveStringMessage

function

Source line 260

pub fn serveStringMessage(s: *Server, tag: OutMessage.Tag, msg: []const u8) !void

Parameters

s: *Server
tag: OutMessage.Tag
msg: []const u8

std.zig.Server.serveTestMetadata

function

Source line 378

pub fn serveTestMetadata(s: *Server, test_metadata: TestMetadata) !void

Parameters

s: *Server
test_metadata: TestMetadata

std.zig.Server.serveTestResults

function

Source line 334

pub fn serveTestResults(s: *Server, msg: OutMessage.TestResults) !void

Parameters

std.zig.Server.serveU32Message

function

Source line 279

pub fn serveU32Message(s: *const Server, tag: OutMessage.Tag, int: u32) !void

Parameters

s: *const Server
tag: OutMessage.Tag
int: u32

std.zig.Server.serveU64Message

function

Source line 288

pub fn serveU64Message(s: *const Server, tag: OutMessage.Tag, int: u64) !void

Parameters

s: *const Server
tag: OutMessage.Tag
int: u64

std.zig.Server.std

alias

Source line 3

Alias of std

std.zig.Server.TestMetadata

container

Source line 372

Fields

names: []const u32
expected_panic_msgs: []const u32
string_bytes: []const u8

std.zig.Server.Writer

alias

Source line 10

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();
}