EmbedFile.zig

An extension to the Zig build system. Its purpose is to enable a build.zig script author to programmatically assemble a collection of assets, each of which is to be embedded with @embedFile, into a module which can be included with @import.

To use in your build.zig scripts, first add this project to your build.zig.zon, for example by running the following command

zig fetch --save git+https://github.com/robbielyman/EmbedFile.zig

Then in your build.zig you can do

const std = @import("std");
const e = @import("embed-file");

pub fn build(b: *std.Build) void {
    // both return a pointer of type *e.EmbedFile
    const embed_file = e.addEmbedFiles(b);
    const alignment: ?u29 = null;
    const embed_file_other = e.addEmbedFile("name", "contents", alignment);
    // ...
}

This is the public API of an EmbedFile Step:

pub fn add(embed_file: *EmbedFile, name: []const u8, bytes: []const u8, alignment: ?u29) void {
    //...
}

pub fn addFile(
    embed_file: *EmbedFile,
    // this is a path to the parent directory of the file to be added
    source: std.Build.LazyPath,
    // this is the name which will be available when using the resulting Zig module
    name: []const u8,
    alignment: ?u29,
) void {
    //...
}

pub fn addDirectory(
    embed_file: *EmbedFile,
    // this is a path to the parent directory of the directory to be added
    source: std.Build.LazyPath,
    // this allows the user to include or exclude files based on their extensions
    options: std.Build.Step.WriteFile.Directory.Options,
    // this is the namespace which will be available when using the resulting Zig module
    name: []const u8,
    // this alignment, if non-null, will be provided to all resulting `@embedFile` declarations
    // under this namespace
    alignment: ?u29,) void {
    //...
}

/// returns a `LazyPath` to the Zig source file generated from this `EmbedFile`
pub fn getSource(embed_file: *EmbedFile) std.Build.LazyPath {
    // ...
}

/// adds a named WriteFile step that collects all of this EmbedFile's dependencies to write out
pub fn writeSources(embed_file: *EmbedFile, name: []const u8) *std.Build.Step.WriteFile {
    // ...
}

/// a `*Module` containing the Zig source file generated from this `EmbedFile`
/// add it to your compilation by passing it `addImport`,
/// e.g. `exe.root_module.addImport("assets", embed_file.module);`
module: *std.Build.Module,

To see an example of correct usage, you can clone this repository and run zig build test in the tests directory. The resulting Zig file will be placed in test-output/module.zig relative to the build prefix. (NB: the resulting module.zig will not compile without build.zig logic, since its declarations use module imports that EmbedFile constructs itself. Of course, you could rewrite or reproduce these imports yourself.)