How can I package some images into an executable program?

Help
4

Like the others have mentioned, you should consider whether you really want to embed the files into the compiled executable or if installing them alongside the executable and loading them at runtime is a better idea. There can be good reasons to prefer @embedFile, for example if you want to ship your application as one single binary instead of a directory tree. But you might also want to consider the size of the compiled binary, and if you’re making something like a game you might want to take things like ease of modding into account.

Anyway, if you want to use @embedFile:

Is having to do a separate @embedFile for each file really a problem? @embedFile returns a *const [N:0]u8 array of raw bytes, so embedding a directory doesn’t really make sense (how would the code access the data for individual files?).

This is probably best solved by the build system, by creating a module out of each individual file and having the main executable import them.

// in build.zig, in the build function
const assets = [_]struct { []const u8, []const u8 }{
    .{ "images/box.png", "box_png" },
    .{ "images/button.png", "button_png" },
};

for (assets) |asset| {
    const path, const name = asset;
    main_exe.root_module.addAnonymousImport(name, .{ .root_source_file = .{ .path = path } });
}

module.addAnonymousImport is a shorthand for b.createModule followed by module.addImport. The root source file of a module does not have to be source code, it can be any kind of file.

Just like you can @import a module, you can also @embedFile it.

// in src/main.zig
const box_png = @embedFile("box_png");
const button_png = @embedFile("button_png");

pub fn main() !void {
    // print the first 16 bytes of the embedded files
    std.debug.print(
        "{s}\n",
        .{std.fmt.fmtSliceHexLower(box_png[0..@min(box_png.len, 16)])},
    );
    std.debug.print(
        "{s}\n",
        .{std.fmt.fmtSliceHexLower(button_png[0..@min(button_png.len, 16)])},
    );
}

It might be a useful idea to create an assets.zig file (or module) that embeds all the files as public declarations, so that other files can easily access them all like @import("assets.zig").box_png.

This is an okay solution, but in general, you should try to avoid directly accessing the file system from build.zig if possible. An explicit list of included files is prefered over opening a directory and iterating over it for multiple reasons. Not only is it more clear to the reader exactly which files are included, but depending on what you’re doing it might also make it easier to catch mistakes (such as missing files or accidentally embedding temporary files or secrets) at build time rather than at runtime.

In addition, in the future zig build might run your build.zig script in a sandbox and prevent you from directly accessing the file system or OS functions for security reasons, so getting into the habit of listing files explicitly might be a good idea so you won’t have any issues if/when this sandboxing is implemented.

5 Likes