My first experience with Zig Build System

The Zig programming language was catching my attention for a while and I decided to try it. The code looks easy to read even for me, who has never tried it before. I find super refreshing the language ideas like cross-compilation, no hidden control flows, no hidden heap allocation, and all this minimalist approach. Yet the comptime, error handling, and build system seems fantastic!

Ok, but I won't try to write Zig code in this post. My first endeavor is to see about the promises of good C compatibility and nice tools. So why not try to resurrect an old C project using the Zig Build System?

Zig compiles C code

I have a pretty old C project from when I was learning C in 2011. Oh God, almost 15 years! Maybe I'm even another person :) and it has probably been six years that I haven't touched any C or C++ code.

The project

The project is trivial, it’s the Minesweeper game. Do you know that one that came installed in Windows 98, maybe even earlier? My first contact with a computer was it. No internet, the PC was used only for writing and printing documents. As a child I only played Mines randomly (dying in a few clicks) and did some sketches in MS Paint. I had no idea how a computer program was made, not even a clue, but I was already curious about it. Even earlier I had a Sega Genesis and wondered how the Sonic games were made.

Ok, no more nostalgic trips, as I was saying the project is a Mines game, but for the terminal. You play by running it in the terminal and typing the number of the square you wanna open or flag. It was one of my first attempts to build anything in C that was not a college task.

Installing Zig

Installing Zig should be just downloading and uncompressing it to a folder in your system. Let’s see if it's as easy as promised!

I'm on a MacBook Pro with a M2 chip. So it's the macOS on the aarch64 architecture. The doc says I just need to download, uncompress, and add it to the path. Cool, not six hours downloading and installing Visual Studio!

After that I got the folder zig-macos-aarch64-0.13.0. Then I open the terminal and try to run the zig binary:

# Go to the folder where I uncompressed Zig
cd ~/Zig/zig-macos-aarch64-0.13.0

# Test if the Zig binary is working
./zig version

This leads me to the first issue. macOS doesn't wanna run it. A popup says it can't scan the file for malware! It's a bit annoying that it doesn't give the option to run it anyway, so we need to allow Zig in the settings.

After that we can run again, allow the popup, and finally see the output:

./zig version
0.13.0

Now we can add it in the path so we can use it from any folder. So we need to append the Zig path to the PATH system variable. I do this configuration in the file .zshrc, but depending on your setup it could be on .bashrc or even another file:

# Open the file in a editor - VS Code in my case
code ~/.zshrc

# Add the following line in the file replacing your user name
export PATH="$PATH:/Users/your-user-name/Zig/zig-macos-aarch64-0.13.0"

After saving the file, I'll open a new terminal and see if it works:

zig version
0.13.0

Ok, not too bad, let's move on!

Hello world?

How easy is it to compile a C hello world using the Zig tooling? First create a C file and let's try to compile it!

File test.c:

#include <stdio.h>

int main() {
    printf("Hello world?\n");
    return 0;
}

Then we can run zig in the terminal to see the options and one caught my attention:

run              Create executable and run immediately

Let's try it:

zig run test.c
Hello world?

Yes, promises delivered! But I'm not seeing the generated executable file anywhere. So what about build?

zig build test.c 
info: initialize build.zig template file with 'zig init'
info: see 'zig --help' for more options
error: no build.zig file found, in the current directory or any parent directories

Nope, this is for when you have a build.zig file! It should be build-exe!

zig build-exe test.c
./test
Hello world?

Ok, that's it. Pretty smooth so far!

Building the Mines

The project has only three C files in the src folder:

mines.c
mlib.c
mlib.h

Awful names, mlib stands for matrix lib or mines lib? The code was also in Portuguese, I kindly asked AI to translate it to English and it worked on the first try. Here is the project on GitHub!

Now let's work on how to build the C files under the src folder. First I ran the zig init in the folder. It generates a few files, but the ones I kept are the build.zig and build.zig.zon. They had a lot of options and comments, but starting with the build.zig.zon I left only the essential for this project and most of it is self explanatory:

.{
    .name = "mines",
    .version = "0.1.0",
    .minimum_zig_version = "0.13.0",

    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
        "README.md",
    },
}

This is probably used to declare dependencies and in case we want to publish the project somewhere. I will be very mad if zon doesn't stand for Zig Object Notation. Regarding a Zig package manager I couldn't find much in my 10 seconds Google search.

So, what is really necessary is the build.zig file. This was not supper intuitive to me and I couldn't find extensive docs on it, only tutorials covering the basics. After some punching thru knife edges (Brazilian saying, does it make any sense?) the build script looks surprisingly easy to understand:

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Declare the mlib, and add the C source file
    const lib = b.addStaticLibrary(.{
        .name = "mlib",
        .target = target,
        .optimize = optimize,
        .link_libc = true,
    });
    lib.addCSourceFile(.{ .file = b.path("src/mlib.c") });

    // Declare the executable, link mlib, and add the C source file
    const exe = b.addExecutable(.{
        .name = "mines",
        .target = target,
        .optimize = optimize,
    });
    exe.linkLibrary(lib);
    exe.addCSourceFile(.{ .file = b.path("src/mines.c") });

    // Create the executable `mines` file under `./zig-out/bin/`
    b.installArtifact(exe);
}

I can't believe it took me hours jumping in a few GitHub repos to figure this out. After running zig build we can find the game executable in zig-out/bin/mines.

And here is how the game looks after running it (./zig-out/bin/mines):

The goal of the game is to open the squares that don't have a mine. The number on a square represents how many mines the square has on its eight neighbors. We can flag a square as a mine, in this case a P will appear. If you open all squares that don't have a mine you win, opening a mine BOOM, you lose!

A good project to start getting some practice in a new language.

In the end

The build API seems not super stable yet (surely we still are in Zig 0.13.0) and I couldn't find extensive docs on it. The official doc is a tutorial and doesn't cover everything especially regarding C building. Off course I can be missing stuff. What helped a lot was to see some examples from allyourcodebase (eg. SDL with the build system replaced by Zig).

But even with these skill issues on my end I believe Zig has huge potential! The philosophy of the language is pretty good. Using the same language and tools on the build system is awesome. I'm sure the docs and tutorials will grow in quality and numbers while the language is more used. Here is one right?

See you next time!