Skip to content
Standard libraryZig 0.17.0Official documentation
Sourcestd/Build/Step/Options.zig

Source line 1

Fields

step: Step
generated_file: Configuration.GeneratedFileIndex
contents: std.ArrayList(u8) = .empty
files: std.ArrayList(NamedPath) = .empty
directories: std.ArrayList(NamedPath) = .empty
untracked_paths: std.ArrayList(NamedPath) = .empty
encountered_types: std.StringHashMapUnmanaged(void)

std.Build.Step.Options.addOption

function

Source line 45

pub fn addOption(options: *Options, comptime T: type, name: []const u8, value: T) void

Parameters

options: *Options
T: type
name: []const u8
value: T

std.Build.Step.Options.addOptionFallible

function

Source line 49

fn addOptionFallible(options: *Options, comptime T: type, name: []const u8, value: T) !void

Parameters

options: *Options
T: type
name: []const u8
value: T

std.Build.Step.Options.addOptionPath

function

Source line 431

The added option has type []const u8 and value of the provided file path. If the provided path is a generated file, causes a transitive dependency on the file's contents.

See also:

pub fn addOptionPath(options: *Options, name: []const u8, path: LazyPath) void

Parameters

options: *Options
name: []const u8
path: LazyPath

std.Build.Step.Options.addOptionPathDirectory

function

Source line 449

The added option has type []const u8 and value of the provided directory path. Causes a transitive dependency through Options on the directory's contents.

See also:

pub fn addOptionPathDirectory(options: *Options, name: []const u8, path: LazyPath) void

Parameters

options: *Options
name: []const u8
path: LazyPath

std.Build.Step.Options.addOptionPathUntracked

function

Source line 467

The added option has type []const u8 and value of the provided path. The resolved path is interpreted as a string without tracking anything about the meaning or contents, and therefore may be a file, directory, not exist, or even be an invalid path, and likewise does not create any file system or Step dependencies.

See also:

pub fn addOptionPathUntracked(options: *Options, name: []const u8, path: LazyPath) void

Parameters

options: *Options
name: []const u8
path: LazyPath

std.Build.Step.Options.base_tag

constant

Source line 20

Step.Tag

std.Build.Step.Options.builtin

constant

Source line 3

std.Build.Step.Options.Configuration

alias

Source line 10

Alias of std.Build.Configuration

std.Build.Step.Options.create

function

Source line 27

pub fn create(owner: *std.Build) *Options

Parameters

owner: *std.Build

std.Build.Step.Options.createModule

function

Source line 479

pub fn createModule(options: *Options) *std.Build.Module

Parameters

options: *Options

std.Build.Step.Options.fs

alias

Source line 7

Alias of std.fs

std.Build.Step.Options.getOutput

function

Source line 487

Returns the main artifact of this Build Step which is a Zig source file generated from the key-value pairs of the Options.

pub fn getOutput(options: *Options) LazyPath

Parameters

options: *Options

std.Build.Step.Options.Io

alias

Source line 6

Alias of std.Io

std.Build.Step.Options.LazyPath

alias

Source line 9

Alias of std.Build.LazyPath

std.Build.Step.Options.NamedPath

container

Source line 22

Fields

std.Build.Step.Options.Options

alias

Source line 1

Alias of std.Build.Step.Options

std.Build.Step.Options.printEnum

function

Source line 290

fn printEnum( options: *Options, out: *std.ArrayList(u8), comptime T: type, comptime val: std.builtin.Type.Enum, indent: u8, ) !void

Parameters

options: *Options
out: *std.ArrayList(u8)
T: type
val: std.builtin.Type.Enum
indent: u8

std.Build.Step.Options.printStruct

function

Source line 320

fn printStruct( options: *Options, out: *std.ArrayList(u8), comptime T: type, comptime val: std.builtin.Type.Struct, indent: u8, ) !void

Parameters

options: *Options
out: *std.ArrayList(u8)
T: type
val: std.builtin.Type.Struct
indent: u8

std.Build.Step.Options.printStructValue

function

Source line 384

fn printStructValue( options: *Options, out: *std.ArrayList(u8), comptime struct_val: std.builtin.Type.Struct, val: anytype, indent: u8, ) !void

Parameters

options: *Options
out: *std.ArrayList(u8)
struct_val: std.builtin.Type.Struct
indent: u8

std.Build.Step.Options.printType

function

Source line 53

fn printType( options: *Options, out: *std.ArrayList(u8), comptime T: type, value: T, indent: u8, name: ?[]const u8, ) !void

Parameters

options: *Options
out: *std.ArrayList(u8)
T: type
value: T
indent: u8
name: ?[]const u8

std.Build.Step.Options.printUserDefinedType

function

Source line 278

fn printUserDefinedType(options: *Options, out: *std.ArrayList(u8), comptime T: type, indent: u8) !void

Parameters

options: *Options
out: *std.ArrayList(u8)
T: type
indent: u8

std.Build.Step.Options.std

alias

Source line 5

Alias of std

std.Build.Step.Options.Step

alias

Source line 8

Alias of std.Build.Step

Source code

std/Build/Step/Options.zig

const Options = @This();

const builtin = @import("builtin");

const std = @import("std");
const Io = std.Io;
const fs = std.fs;
const Step = std.Build.Step;
const LazyPath = std.Build.LazyPath;
const Configuration = std.Build.Configuration;

step: Step,
generated_file: Configuration.GeneratedFileIndex,
contents: std.ArrayList(u8) = .empty,
files: std.ArrayList(NamedPath) = .empty,
directories: std.ArrayList(NamedPath) = .empty,
untracked_paths: std.ArrayList(NamedPath) = .empty,
encountered_types: std.StringHashMapUnmanaged(void),

pub const base_tag: Step.Tag = .options;

pub const NamedPath = struct {
    name: Configuration.String,
    path: LazyPath,
};

pub fn create(owner: *std.Build) *Options {
    const graph = owner.graph;
    const arena = graph.arena;

    const options = arena.create(Options) catch @panic("OOM");
    options.* = .{
        .step = .init(.{
            .tag = base_tag,
            .name = "options",
            .owner = owner,
        }),
        .generated_file = graph.addGeneratedFile(&options.step),
        .encountered_types = .empty,
    };

    return options;
}

pub fn addOption(options: *Options, comptime T: type, name: []const u8, value: T) void {
    return addOptionFallible(options, T, name, value) catch @panic("unhandled error");
}

fn addOptionFallible(options: *Options, comptime T: type, name: []const u8, value: T) !void {
    try printType(options, &options.contents, T, value, 0, name);
}

fn printType(
    options: *Options,
    out: *std.ArrayList(u8),
    comptime T: type,
    value: T,
    indent: u8,
    name: ?[]const u8,
) !void {
    const gpa = options.step.owner.allocator;
    switch (T) {
        []const []const u8 => {
            if (name) |payload| {
                try out.print(gpa, "pub const {f}: []const []const u8 = ", .{std.zig.fmtId(payload)});
            }

            try out.appendSlice(gpa, "&[_][]const u8{\n");

            for (value) |slice| {
                try out.appendNTimes(gpa, ' ', indent);
                try out.print(gpa, "    \"{f}\",\n", .{std.zig.fmtString(slice)});
            }

            if (name != null) {
                try out.appendSlice(gpa, "};\n");
            } else {
                try out.appendSlice(gpa, "},\n");
            }

            return;
        },
        []const u8 => {
            if (name) |some| {
                try out.print(gpa, "pub const {f}: []const u8 = \"{f}\";", .{
                    std.zig.fmtId(some), std.zig.fmtString(value),
                });
            } else {
                try out.print(gpa, "\"{f}\",", .{std.zig.fmtString(value)});
            }
            return out.appendSlice(gpa, "\n");
        },
        [:0]const u8 => {
            if (name) |some| {
                try out.print(gpa, "pub const {f}: [:0]const u8 = \"{f}\";", .{ std.zig.fmtId(some), std.zig.fmtString(value) });
            } else {
                try out.print(gpa, "\"{f}\",", .{std.zig.fmtString(value)});
            }
            return out.appendSlice(gpa, "\n");
        },
        ?[]const u8 => {
            if (name) |some| {
                try out.print(gpa, "pub const {f}: ?[]const u8 = ", .{std.zig.fmtId(some)});
            }

            if (value) |payload| {
                try out.print(gpa, "\"{f}\"", .{std.zig.fmtString(payload)});
            } else {
                try out.appendSlice(gpa, "null");
            }

            if (name != null) {
                try out.appendSlice(gpa, ";\n");
            } else {
                try out.appendSlice(gpa, ",\n");
            }
            return;
        },
        ?[:0]const u8 => {
            if (name) |some| {
                try out.print(gpa, "pub const {f}: ?[:0]const u8 = ", .{std.zig.fmtId(some)});
            }

            if (value) |payload| {
                try out.print(gpa, "\"{f}\"", .{std.zig.fmtString(payload)});
            } else {
                try out.appendSlice(gpa, "null");
            }

            if (name != null) {
                try out.appendSlice(gpa, ";\n");
            } else {
                try out.appendSlice(gpa, ",\n");
            }
            return;
        },
        std.SemanticVersion => {
            if (name) |some| {
                try out.print(gpa, "pub const {f}: @import(\"std\").SemanticVersion = ", .{std.zig.fmtId(some)});
            }

            try out.appendSlice(gpa, ".{\n");
            try out.appendNTimes(gpa, ' ', indent);
            try out.print(gpa, "    .major = {d},\n", .{value.major});
            try out.appendNTimes(gpa, ' ', indent);
            try out.print(gpa, "    .minor = {d},\n", .{value.minor});
            try out.appendNTimes(gpa, ' ', indent);
            try out.print(gpa, "    .patch = {d},\n", .{value.patch});

            if (value.pre) |some| {
                try out.appendNTimes(gpa, ' ', indent);
                try out.print(gpa, "    .pre = \"{f}\",\n", .{std.zig.fmtString(some)});
            }
            if (value.build) |some| {
                try out.appendNTimes(gpa, ' ', indent);
                try out.print(gpa, "    .build = \"{f}\",\n", .{std.zig.fmtString(some)});
            }

            if (name != null) {
                try out.appendSlice(gpa, "};\n");
            } else {
                try out.appendSlice(gpa, "},\n");
            }
            return;
        },
        else => {},
    }

    switch (@typeInfo(T)) {
        .array => {
            if (name) |some| {
                try out.print(gpa, "pub const {f}: {s} = ", .{ std.zig.fmtId(some), @typeName(T) });
            }

            try out.print(gpa, "{s} {{\n", .{@typeName(T)});
            for (value) |item| {
                try out.appendNTimes(gpa, ' ', indent + 4);
                try printType(options, out, @TypeOf(item), item, indent + 4, null);
            }
            try out.appendNTimes(gpa, ' ', indent);
            try out.appendSlice(gpa, "}");

            if (name != null) {
                try out.appendSlice(gpa, ";\n");
            } else {
                try out.appendSlice(gpa, ",\n");
            }
            return;
        },
        .pointer => |p| {
            if (p.size != .slice) {
                @compileError("Non-slice pointers are not yet supported in build options");
            }

            if (name) |some| {
                try out.print(gpa, "pub const {f}: {s} = ", .{ std.zig.fmtId(some), @typeName(T) });
            }

            try out.print(gpa, "&[_]{s} {{\n", .{@typeName(p.child)});
            for (value) |item| {
                try out.appendNTimes(gpa, ' ', indent + 4);
                try printType(options, out, @TypeOf(item), item, indent + 4, null);
            }
            try out.appendNTimes(gpa, ' ', indent);
            try out.appendSlice(gpa, "}");

            if (name != null) {
                try out.appendSlice(gpa, ";\n");
            } else {
                try out.appendSlice(gpa, ",\n");
            }
            return;
        },
        .optional => {
            if (name) |some| {
                try out.print(gpa, "pub const {f}: {s} = ", .{ std.zig.fmtId(some), @typeName(T) });
            }

            if (value) |inner| {
                try printType(options, out, @TypeOf(inner), inner, indent + 4, null);
                // Pop the '\n' and ',' chars
                _ = options.contents.pop();
                _ = options.contents.pop();
            } else {
                try out.appendSlice(gpa, "null");
            }

            if (name != null) {
                try out.appendSlice(gpa, ";\n");
            } else {
                try out.appendSlice(gpa, ",\n");
            }
            return;
        },
        .void,
        .bool,
        .int,
        .comptime_int,
        .float,
        .comptime_float,
        .null,
        => {
            if (name) |some| {
                try out.print(gpa, "pub const {f}: {s} = {any};\n", .{ std.zig.fmtId(some), @typeName(T), value });
            } else {
                try out.print(gpa, "{any},\n", .{value});
            }
            return;
        },
        .@"enum" => |info| {
            try printEnum(options, out, T, info, indent);

            if (name) |some| {
                try out.print(gpa, "pub const {f}: {f} = .{f};\n", .{
                    std.zig.fmtId(some),
                    std.zig.fmtId(@typeName(T)),
                    std.zig.fmtIdFlags(@tagName(value), .{ .allow_underscore = true, .allow_primitive = true }),
                });
            }
            return;
        },
        .@"struct" => |info| {
            try printStruct(options, out, T, info, indent);

            if (name) |some| {
                try out.print(gpa, "pub const {f}: {f} = ", .{
                    std.zig.fmtId(some),
                    std.zig.fmtId(@typeName(T)),
                });
                try printStructValue(options, out, info, value, indent);
            }
            return;
        },
        else => @compileError(std.fmt.comptimePrint("`{s}` are not yet supported as build options", .{@tagName(@typeInfo(T))})),
    }
}

fn printUserDefinedType(options: *Options, out: *std.ArrayList(u8), comptime T: type, indent: u8) !void {
    switch (@typeInfo(T)) {
        .@"enum" => |info| {
            return try printEnum(options, out, T, info, indent);
        },
        .@"struct" => |info| {
            return try printStruct(options, out, T, info, indent);
        },
        else => {},
    }
}

fn printEnum(
    options: *Options,
    out: *std.ArrayList(u8),
    comptime T: type,
    comptime val: std.builtin.Type.Enum,
    indent: u8,
) !void {
    const gpa = options.step.owner.allocator;
    const gop = try options.encountered_types.getOrPut(gpa, @typeName(T));
    if (gop.found_existing) return;

    try out.appendNTimes(gpa, ' ', indent);
    try out.print(gpa, "pub const {f} = enum ({s}) {{\n", .{ std.zig.fmtId(@typeName(T)), @typeName(val.tag_type) });

    inline for (val.field_names, val.field_values) |field_name, field_value| {
        try out.appendNTimes(gpa, ' ', indent);
        try out.print(gpa, "    {f} = {d},\n", .{
            std.zig.fmtIdFlags(field_name, .{ .allow_primitive = true }), field_value,
        });
    }

    if (val.mode == .nonexhaustive) {
        try out.appendNTimes(gpa, ' ', indent);
        try out.appendSlice(gpa, "    _,\n");
    }

    try out.appendNTimes(gpa, ' ', indent);
    try out.appendSlice(gpa, "};\n");
}

fn printStruct(
    options: *Options,
    out: *std.ArrayList(u8),
    comptime T: type,
    comptime val: std.builtin.Type.Struct,
    indent: u8,
) !void {
    const gpa = options.step.owner.allocator;
    const gop = try options.encountered_types.getOrPut(gpa, @typeName(T));
    if (gop.found_existing) return;

    try out.appendNTimes(gpa, ' ', indent);
    try out.print(gpa, "pub const {f} = ", .{std.zig.fmtId(@typeName(T))});

    switch (val.layout) {
        .@"extern" => try out.appendSlice(gpa, "extern struct"),
        .@"packed" => try out.appendSlice(gpa, "packed struct"),
        else => try out.appendSlice(gpa, "struct"),
    }

    try out.appendSlice(gpa, " {\n");

    inline for (val.field_names, val.field_types, val.field_attrs) |field_name, field_type, field_attrs| {
        try out.appendNTimes(gpa, ' ', indent);

        const type_name = @typeName(field_type);

        // If the type name doesn't contains a '.' the type is from zig builtins.
        if (std.mem.containsAtLeast(u8, type_name, 1, ".")) {
            try out.print(gpa, "    {f}: {f}", .{
                std.zig.fmtIdFlags(field_name, .{ .allow_underscore = true, .allow_primitive = true }),
                std.zig.fmtId(type_name),
            });
        } else {
            try out.print(gpa, "    {f}: {s}", .{
                std.zig.fmtIdFlags(field_name, .{ .allow_underscore = true, .allow_primitive = true }),
                type_name,
            });
        }

        if (field_attrs.defaultValue(field_type)) |default_value| {
            try out.appendSlice(gpa, " = ");
            switch (@typeInfo(field_type)) {
                .@"enum" => try out.print(gpa, ".{s},\n", .{@tagName(default_value)}),
                .@"struct" => |info| {
                    try printStructValue(options, out, info, default_value, indent + 4);
                },
                else => try printType(options, out, field_type, default_value, indent, null),
            }
        } else {
            try out.appendSlice(gpa, ",\n");
        }
    }

    // TODO: write declarations

    try out.appendNTimes(gpa, ' ', indent);
    try out.appendSlice(gpa, "};\n");

    inline for (val.field_types) |field_type| {
        try printUserDefinedType(options, out, field_type, 0);
    }
}

fn printStructValue(
    options: *Options,
    out: *std.ArrayList(u8),
    comptime struct_val: std.builtin.Type.Struct,
    val: anytype,
    indent: u8,
) !void {
    const gpa = options.step.owner.allocator;
    try out.appendSlice(gpa, ".{\n");

    if (struct_val.is_tuple) {
        inline for (struct_val.field_names) |field_name| {
            try out.appendNTimes(gpa, ' ', indent);
            try printType(options, out, @TypeOf(@field(val, field_name)), @field(val, field_name), indent, null);
        }
    } else {
        inline for (struct_val.field_names) |field_name| {
            try out.appendNTimes(gpa, ' ', indent);
            try out.print(gpa, "    .{f} = ", .{
                std.zig.fmtIdFlags(field_name, .{ .allow_primitive = true, .allow_underscore = true }),
            });

            const field_val = @field(val, field_name);
            switch (@typeInfo(@TypeOf(field_val))) {
                .@"enum" => try out.print(gpa, ".{s},\n", .{@tagName(field_val)}),
                .@"struct" => |struct_info| {
                    try printStructValue(options, out, struct_info, field_val, indent + 4);
                },
                else => try printType(options, out, @TypeOf(field_val), field_val, indent, null),
            }
        }
    }

    if (indent == 0) {
        try out.appendSlice(gpa, "};\n");
    } else {
        try out.appendNTimes(gpa, ' ', indent);
        try out.appendSlice(gpa, "},\n");
    }
}

/// The added option has type `[]const u8` and value of the provided file path. If the provided path is a
/// generated file, causes a transitive dependency on the file's contents.
///
/// See also:
/// * `addOptionPathDirectory`
/// * `addOptionPathUntracked`
pub fn addOptionPath(options: *Options, name: []const u8, path: LazyPath) void {
    const graph = options.step.owner.graph;
    const arena = graph.arena;
    const wc = &graph.wip_configuration;

    options.files.append(arena, .{
        .name = wc.addString(name) catch @panic("OOM"),
        .path = path.dupe(options.step.owner.graph),
    }) catch @panic("OOM");
    path.addStepDependencies(&options.step);
}

/// The added option has type `[]const u8` and value of the provided directory path. Causes a transitive
/// dependency through Options on the directory's contents.
///
/// See also:
/// * `addOptionPath`
/// * `addOptionPathUntracked`
pub fn addOptionPathDirectory(options: *Options, name: []const u8, path: LazyPath) void {
    const graph = options.step.owner.graph;
    const arena = graph.arena;
    const wc = &graph.wip_configuration;

    options.directories.append(arena, .{
        .name = wc.addString(name) catch @panic("OOM"),
        .path = path.dupe(options.step.owner.graph),
    }) catch @panic("OOM");
    path.addStepDependencies(&options.step);
}

/// The added option has type `[]const u8` and value of the provided path. The resolved path is interpreted as
/// a string without tracking anything about the meaning or contents, and therefore may be a file, directory,
/// not exist, or even be an invalid path, and likewise does not create any file system or `Step` dependencies.
///
/// See also:
/// * `addOptionPath`
pub fn addOptionPathUntracked(options: *Options, name: []const u8, path: LazyPath) void {
    const graph = options.step.owner.graph;
    const arena = graph.arena;
    const wc = &graph.wip_configuration;

    options.untracked_paths.append(arena, .{
        .name = wc.addString(name) catch @panic("OOM"),
        .path = path.dupe(options.step.owner.graph),
    }) catch @panic("OOM");
    path.addStepDependencies(&options.step);
}

pub fn createModule(options: *Options) *std.Build.Module {
    return options.step.owner.createModule(.{
        .root_source_file = options.getOutput(),
    });
}

/// Returns the main artifact of this Build Step which is a Zig source file
/// generated from the key-value pairs of the Options.
pub fn getOutput(options: *Options) LazyPath {
    return .{ .generated = .{ .index = options.generated_file } };
}