https://github.com/robbielyman/embedfile.zig

an extension to the Zig build system to programmatically collect assets
https://github.com/robbielyman/embedfile.zig

zig zig-build zig-package

Last synced: about 1 month ago
JSON representation

an extension to the Zig build system to programmatically collect assets

• Host: GitHub
• URL: https://github.com/robbielyman/embedfile.zig
• Owner: robbielyman
• License: mit
• Created: 2024-12-31T19:43:21.000Z (about 1 month ago)
• Default Branch: main
• Last Pushed: 2024-12-31T19:45:57.000Z (about 1 month ago)
• Last Synced: 2024-12-31T20:30:14.680Z (about 1 month ago)
• Topics: zig, zig-build, zig-package
• Language: Zig
• Homepage:
• Size: 0 Bytes
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.org
  • License: LICENSE

Awesome Lists containing this project

README

        
* 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

#+begin_src sh

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

#+end_src

Then in your =build.zig= you can do

#+begin_src zig

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

      // ...

  }

#+end_src

This is the public API of an =EmbedFile= Step:

#+begin_src zig

  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,

#+end_src

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.)