跳转到内容

std.Build.Step.WriteFile

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

第 1 行

WriteFile 用于在本地缓存的适当位置创建目录, 目录内包含构建过程中生成的文件, 或从源码包复制的文件。

字段

step: Step
embeds: std.ArrayList(Embed) = .empty
copies: std.ArrayList(Copy) = .empty
directories: std.ArrayList(Directory) = .empty
generated_directory: Configuration.GeneratedFileIndex
mode: Mode = .whole_cached

std.Build.Step.WriteFile.add

函数

第 69 行

将 contents 写入相对于输出目录的 sub_path 文件。

sub_path 可以是基本文件名,也可以包含子目录; 子目录会按需创建。

pub fn add(wf: *WriteFile, sub_path: []const u8, contents: []const u8) std.Build.LazyPath

参数

wf: *WriteFile
sub_path: []const u8
contents: []const u8

std.Build.Step.WriteFile.addCopyDirectory

函数

第 126 行

将匹配指定排除/包含模式的文件复制到 相对此步骤生成目录的指定子目录。

返回值是指向生成子目录的延迟路径。

pub fn addCopyDirectory( wf: *WriteFile, src_path: std.Build.LazyPath, sub_path: []const u8, options: CopyDirectoryOptions, ) std.Build.LazyPath

参数

wf: *WriteFile
src_path: std.Build.LazyPath
sub_path: []const u8
options: CopyDirectoryOptions

std.Build.Step.WriteFile.addCopyFile

函数

第 93 行

将所提供的文件复制到相对于输出目录的 sub_path。

sub_path 可以是基本文件名,也可以包含子目录; 子目录会按需创建。

pub fn addCopyFile(wf: *WriteFile, src_file: std.Build.LazyPath, sub_path: []const u8) std.Build.LazyPath

参数

wf: *WriteFile
src_file: std.Build.LazyPath
sub_path: []const u8

std.Build.Step.WriteFile.base_tag

常量

第 17 行

Step.Tag

std.Build.Step.WriteFile.Configuration

别名

第 8 行

别名目标 std.Build.Configuration

std.Build.Step.WriteFile.Copy

容器

第 38 行

字段

sub_path: Configuration.String
src_file: std.Build.LazyPath

std.Build.Step.WriteFile.CopyDirectoryOptions

容器

第 113 行

字段

exclude_extensions: []const []const u8 = &.{}

以这些后缀之一结尾的文件路径将不予复制。

include_extensions: ?[]const []const u8 = null

仅复制以这些后缀之一结尾的文件路径。 null 表示包含全部后缀。 exclude_extensions 优先于 include_extensions。

std.Build.Step.WriteFile.create

函数

第 50 行

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

参数

owner: *std.Build

std.Build.Step.WriteFile.Directory

容器

第 43 行

字段

sub_path: Configuration.String
src_path: std.Build.LazyPath
exclude_extensions: Configuration.OptionalStringList
include_extensions: Configuration.OptionalStringList

std.Build.Step.WriteFile.Embed

别名

第 36 行

别名目标 std.Build.Configuration.Step.WriteFile.Embed

std.Build.Step.WriteFile.getDirectory

函数

第 163 行

返回表示基目录的 LazyPath,该目录包含此 WriteFile 中的所有文件。

pub fn getDirectory(wf: *WriteFile) std.Build.LazyPath

参数

wf: *WriteFile

std.Build.Step.WriteFile.maybeUpdateName

函数

第 167 行

fn maybeUpdateName(wf: *WriteFile) void

参数

wf: *WriteFile

std.Build.Step.WriteFile.Mode

容器

第 19 行

字段

whole_cached

默认模式。与缓存系统集成。 make 阶段目录应为只读。 不同输入会产生不同的“o”子目录。

tmp

在此模式下,目录放在“tmp”而非“o”内部,并跳过缓存。 在 make 阶段,此步骤始终执行全部文件系统操作。构建成功结束时,将与其他临时目录一起删除该目录。 因此,其他步骤可以修改此目录。

mutate: std.Build.LazyPath

操作不会作用于新创建的目录, 而是作用于临时目录。

std.Build.Step.WriteFile.std

别名

第 6 行

别名目标 std

std.Build.Step.WriteFile.Step

别名

第 7 行

别名目标 std.Build.Step

std.Build.Step.WriteFile.WriteFile

别名

第 4 行

别名目标 std.Build.Step.WriteFile

源码

std/Build/Step/WriteFile.zig

//! WriteFile 用于在本地缓存的适当位置创建目录,
//! 目录内包含构建过程中生成的文件,
//! 或从源码包复制的文件。
const WriteFile = @This();

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

step: Step,
embeds: std.ArrayList(Embed) = .empty,
copies: std.ArrayList(Copy) = .empty,
directories: std.ArrayList(Directory) = .empty,
generated_directory: Configuration.GeneratedFileIndex,
mode: Mode = .whole_cached,

pub const base_tag: Step.Tag = .write_file;

pub const Mode = union(enum) {
    /// 默认模式。与缓存系统集成。
    /// make 阶段目录应为只读。
    /// 不同输入会产生不同的“o”子目录。
    whole_cached,
    /// 在此模式下,目录放在“tmp”而非“o”内部,并跳过缓存。
    /// 在 `make` 阶段,此步骤始终执行全部文件系统操作。构建成功结束时,将与其他临时目录一起删除该目录。
    /// 因此,其他步骤可以修改此目录。
    ///
    ///
    ///
    tmp,
    /// 操作不会作用于新创建的目录,
    /// 而是作用于临时目录。
    mutate: std.Build.LazyPath,
};

pub const Embed = Configuration.Step.WriteFile.Embed;

pub const Copy = struct {
    sub_path: Configuration.String,
    src_file: std.Build.LazyPath,
};

pub const Directory = struct {
    sub_path: Configuration.String,
    src_path: std.Build.LazyPath,
    exclude_extensions: Configuration.OptionalStringList,
    include_extensions: Configuration.OptionalStringList,
};

pub fn create(owner: *std.Build) *WriteFile {
    const graph = owner.graph;
    const wf = graph.create(WriteFile);
    wf.* = .{
        .step = .init(.{
            .tag = base_tag,
            .name = "WriteFile",
            .owner = owner,
        }),
        .generated_directory = graph.addGeneratedFile(&wf.step),
    };
    return wf;
}

/// 将 `contents` 写入相对于输出目录的
/// `sub_path` 文件。
///
/// `sub_path` 可以是基本文件名,也可以包含子目录;
/// 子目录会按需创建。
pub fn add(wf: *WriteFile, sub_path: []const u8, contents: []const u8) std.Build.LazyPath {
    const graph = wf.step.owner.graph;
    const wc = &graph.wip_configuration;
    const arena = graph.arena;

    wf.embeds.append(arena, .{
        .sub_path = wc.addString(sub_path) catch @panic("OOM"),
        .contents = wc.addBytes(contents) catch @panic("OOM"),
    }) catch @panic("OOM");

    wf.maybeUpdateName();

    return .{
        .generated = .{
            .index = wf.generated_directory,
            .sub_path = graph.dupeString(sub_path),
        },
    };
}

/// 将所提供的文件复制到相对于输出目录的 `sub_path`。
///
/// `sub_path` 可以是基本文件名,也可以包含子目录;
/// 子目录会按需创建。
pub fn addCopyFile(wf: *WriteFile, src_file: std.Build.LazyPath, sub_path: []const u8) std.Build.LazyPath {
    const graph = wf.step.owner.graph;
    const wc = &graph.wip_configuration;
    const arena = graph.arena;

    wf.copies.append(arena, .{
        .sub_path = wc.addString(sub_path) catch @panic("OOM"),
        .src_file = src_file.dupe(graph),
    }) catch @panic("OOM");

    wf.maybeUpdateName();

    src_file.addStepDependencies(&wf.step);

    return .{ .generated = .{
        .index = wf.generated_directory,
        .sub_path = graph.dupePath(sub_path),
    } };
}

pub const CopyDirectoryOptions = struct {
    /// 以这些后缀之一结尾的文件路径将不予复制。
    exclude_extensions: []const []const u8 = &.{},
    /// 仅复制以这些后缀之一结尾的文件路径。
    /// `null` 表示包含全部后缀。
    /// `exclude_extensions` 优先于 `include_extensions`。
    include_extensions: ?[]const []const u8 = null,
};

/// 将匹配指定排除/包含模式的文件复制到
/// 相对此步骤生成目录的指定子目录。
///
/// 返回值是指向生成子目录的延迟路径。
pub fn addCopyDirectory(
    wf: *WriteFile,
    src_path: std.Build.LazyPath,
    sub_path: []const u8,
    options: CopyDirectoryOptions,
) std.Build.LazyPath {
    const graph = wf.step.owner.graph;
    const wc = &graph.wip_configuration;
    const arena = graph.arena;

    wf.directories.append(arena, .{
        .sub_path = wc.addString(sub_path) catch @panic("OOM"),
        .src_path = src_path.dupe(graph),
        .exclude_extensions = if (options.exclude_extensions.len != 0)
            .init(wc.addStringList(options.exclude_extensions) catch @panic("OOM"))
        else
            .none,
        .include_extensions = if (options.include_extensions) |list|
            .init(wc.addStringList(list) catch @panic("OOM"))
        else
            .none,
    }) catch @panic("OOM");

    wf.maybeUpdateName();

    src_path.addStepDependencies(&wf.step);

    return .{
        .generated = .{
            .index = wf.generated_directory,
            .sub_path = graph.dupePath(sub_path),
        },
    };
}

/// 返回表示基目录的 `LazyPath`,该目录包含此 `WriteFile`
/// 中的所有文件。
pub fn getDirectory(wf: *WriteFile) std.Build.LazyPath {
    return .{ .generated = .{ .index = wf.generated_directory } };
}

fn maybeUpdateName(wf: *WriteFile) void {
    const graph = wf.step.owner.graph;
    const wc = &graph.wip_configuration;
    const files_count = wf.embeds.items.len + wf.copies.items.len;
    if (files_count == 1 and wf.directories.items.len == 0) {
        // 首次添加文件;更新名称。
        const sub_path = if (wf.embeds.items.len == 1) wf.embeds.items[0].sub_path else wf.copies.items[0].sub_path;
        if (std.mem.eql(u8, wf.step.name, "WriteFile")) {
            wf.step.name = wf.step.owner.fmt("WriteFile {s}", .{wc.stringSlice(sub_path)});
        }
    } else if (wf.directories.items.len == 1 and files_count == 0) {
        // 首次添加目录;更新名称。
        const dir_name = wc.stringSlice(wf.directories.items[0].sub_path);
        if (std.mem.eql(u8, wf.step.name, "WriteFile")) {
            wf.step.name = wf.step.owner.fmt("WriteFile {s}", .{dir_name});
        }
    }
}