跳转到内容

std.Build.Step.Options

标准库Zig 0.17.0官方原文
源码std/Build/Step/Options.zig

第 1 行

字段

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

函数

第 45 行

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

参数

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

std.Build.Step.Options.addOptionFallible

函数

第 49 行

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

参数

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

std.Build.Step.Options.addOptionPath

函数

第 431 行

添加的选项类型为 []const u8,值为所提供的文件路径。若所提供路径是 生成文件,则会对该文件内容建立传递依赖。

另见:

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

参数

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

std.Build.Step.Options.addOptionPathDirectory

函数

第 449 行

添加的选项类型为 []const u8,值为所提供的目录路径。 通过 Options 对目录内容建立传递依赖。

另见:

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

参数

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

std.Build.Step.Options.addOptionPathUntracked

函数

第 467 行

添加的选项类型为 []const u8,值为提供的路径。解析后的路径被视为 字符串,不跟踪其含义或内容,因此它可以是文件、目录、 不存在甚至无效的路径,同样也不会建立任何文件系统或 Step 依赖。

另见:

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

参数

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

std.Build.Step.Options.base_tag

常量

第 20 行

Step.Tag

std.Build.Step.Options.builtin

常量

第 3 行

std.Build.Step.Options.Configuration

别名

第 10 行

别名目标 std.Build.Configuration

std.Build.Step.Options.create

函数

第 27 行

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

参数

owner: *std.Build

std.Build.Step.Options.createModule

函数

第 479 行

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

参数

options: *Options

std.Build.Step.Options.fs

别名

第 7 行

别名目标 std.fs

std.Build.Step.Options.getOutput

函数

第 487 行

返回此构建步骤的主要产物,即由 Options 的 键值对生成的 Zig 源文件。

pub fn getOutput(options: *Options) LazyPath

参数

options: *Options

std.Build.Step.Options.Io

别名

第 6 行

别名目标 std.Io

std.Build.Step.Options.LazyPath

别名

第 9 行

别名目标 std.Build.LazyPath

std.Build.Step.Options.NamedPath

容器

第 22 行

字段

std.Build.Step.Options.Options

别名

第 1 行

别名目标 std.Build.Step.Options

std.Build.Step.Options.printEnum

函数

第 290 行

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

参数

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

std.Build.Step.Options.printStruct

函数

第 320 行

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

参数

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

std.Build.Step.Options.printStructValue

函数

第 384 行

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

参数

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

std.Build.Step.Options.printType

函数

第 53 行

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

参数

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

std.Build.Step.Options.printUserDefinedType

函数

第 278 行

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

参数

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

std.Build.Step.Options.std

别名

第 5 行

别名目标 std

std.Build.Step.Options.Step

别名

第 8 行

别名目标 std.Build.Step

源码

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);
                // 弹出 '\n' 和 ',' 字符
                _ = 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);

        // 类型名称不包含 '.' 时,该类型来自 zig 内置类型。
        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: 编写声明

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

/// 添加的选项类型为 `[]const u8`,值为所提供的文件路径。若所提供路径是
/// 生成文件,则会对该文件内容建立传递依赖。
///
/// 另见:
/// * `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);
}

/// 添加的选项类型为 `[]const u8`,值为所提供的目录路径。
/// 通过 Options 对目录内容建立传递依赖。
///
/// 另见:
/// * `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);
}

/// 添加的选项类型为 `[]const u8`,值为提供的路径。解析后的路径被视为
/// 字符串,不跟踪其含义或内容,因此它可以是文件、目录、
/// 不存在甚至无效的路径,同样也不会建立任何文件系统或 `Step` 依赖。
///
/// 另见:
/// * `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(),
    });
}

/// 返回此构建步骤的主要产物,即由 Options 的
/// 键值对生成的 Zig 源文件。
pub fn getOutput(options: *Options) LazyPath {
    return .{ .generated = .{ .index = options.generated_file } };
}