Build process

Suppose we have the following Zig file:

/home/eric/project_x/zig/hello.zig

And we want to compile it at ReleaseSmall to:

/home/eric/project_x/lib/hello.zigar/linux.x64.so

Zigar would go through the following steps:

1. Recursively scan /home/eric/project_x/zig.
2. Obtain the last-modified time of /home/eric/project_x/lib/hello.zigar/linux.x64.so.
3. Check if any file in /home/eric/project_x/zig is newer than the .so file. Exit if none is.
4. Write the process id to '/tmp/zigar-build/project_x-3127ddfd.pid'. If the file exists already, read the process id and check if the process is still alive. Keep waiting until the other process has gone away.
5. Create the sub-directory project_x-3127ddfd in /tmp/zigar-build.
6. Create build-cfg.zig in /tmp/zigar-build/project_x-3127ddfd.
7. Copy /home/eric/project_x/zig/build.zig to /tmp/zigar-build/project_x-3127ddfd if it exists. If not, copy /home/eric/project_x/node_modules/zigar-compiler/zig/build.zig.
8. Copy /home/eric/project_x/zig/build.zig.zon to /tmp/zigar-build/project_x-3127ddfd if it exists.
9. Run the command zig build -Doptimize=ReleaseSmall -Dtarget=linux-x86_64-gnu.
10. If an error occurs, write the compiler output to /tmp/zigar-build/project_x-3127ddfd/log
11. Remove /tmp/zigar-build/project_x-3127ddfd if clean is true

The build directory would look like this afterward:

📄 build-cfg.zig
📄 build.zig
📄 build.zig.zon
📁 zig-cache

build-cfg.zig would contain the following:

pub const module_name = "hello";
pub const module_path = "/home/eric/project_x/zig/hello.zig";
pub const module_dir = "/home/eric/project_x/zig/hello";
pub const exporter_path = "/home/eric/project_x/node_modules/zigar-compiler/zig/exporter-c.zig";
pub const stub_path = "/home/eric/project_x/node_modules/zigar-compiler/zig/stub-c.zig";
pub const output_path = "/home/eric/project_x/lib/hello.zigar/linux.x64.so";
pub const use_libc = true;
pub const is_wasm = false;

Notes

If you have a custom build file that references files outside the directory holding your Zig file, you might want to create symlinks to them in that directory so the scan would pick up any modifications.

The random string attached to the name of the build directory is the first 8 letters of md5("/home/eric/project_x/zig/hello").

The content of build-cfg.zig is described here.