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

    const Examples = enum {
        all,
        demo,
        continuous,
        // elements:
        alignment,
        button,
        input,
        popup,
        progress,
        scrollable,
        // layouts:
        vertical,
        horizontal,
        grid,
        mixed,
        // styles:
        text,
        palette,
        // error handling
        errors,
    };

    const example = b.option(Examples, "example", "Example to build and/or run. (default: all)") orelse .all;
    const debug_rendering = b.option(bool, "debug", "Enable debug rendering. Highlight origin's, size's, padding's, gap's, etc. (default: false)") orelse false;
    // NOTE do not support debug rendering in release builds
    if (debug_rendering == true and optimize != .Debug) @panic("Cannot enable debug rendering in non-debug builds.");

    const options = b.addOptions();
    options.addOption(bool, "debug", debug_rendering);
    const options_module = options.createModule();

    // dependencies
    const zg = b.dependency("zg", .{
        .target = target,
        .optimize = optimize,
    });

    // library
    const lib = b.addModule("zterm", .{
        .root_source_file = b.path("src/root.zig"),
        .target = target,
        .optimize = optimize,
    });
    lib.addImport("code_point", zg.module("code_point"));
    lib.addImport("build_options", options_module);

    //--- Examples ---
    const examples = std.meta.fields(Examples);
    inline for (examples) |e| {
        if (@as(Examples, @enumFromInt(e.value)) == .all) continue; // skip `.all` entry
        const demo = b.addExecutable(.{
            .name = e.name,
            .root_source_file = b.path(switch (@as(Examples, @enumFromInt(e.value))) {
                .demo => "examples/demo.zig",
                .continuous => "examples/continuous.zig",
                // elements:
                .alignment => "examples/elements/alignment.zig",
                .button => "examples/elements/button.zig",
                .input => "examples/elements/input.zig",
                .popup => "examples/elements/popup.zig",
                .progress => "examples/elements/progress.zig",
                .scrollable => "examples/elements/scrollable.zig",
                // layouts:
                .vertical => "examples/layouts/vertical.zig",
                .horizontal => "examples/layouts/horizontal.zig",
                .grid => "examples/layouts/grid.zig",
                .mixed => "examples/layouts/mixed.zig",
                // styles:
                .text => "examples/styles/text.zig",
                .palette => "examples/styles/palette.zig",
                // error handling
                .errors => "examples/errors.zig",
                .all => unreachable, // should never happen
            }),
            .target = target,
            .optimize = optimize,
        });
        // import dependencies
        demo.root_module.addImport("zterm", lib);
        // mapping of user selected example to compile step
        if (@intFromEnum(example) == e.value or example == .all) b.installArtifact(demo);
    }

    // zig build test
    const lib_unit_tests = b.addTest(.{
        .root_source_file = b.path("src/root.zig"),
        .target = target,
        .optimize = optimize,
    });
    lib_unit_tests.root_module.addImport("code_point", zg.module("code_point"));
    lib_unit_tests.root_module.addImport("DisplayWidth", zg.module("DisplayWidth"));
    lib_unit_tests.root_module.addImport("build_options", options_module);

    const run_lib_unit_tests = b.addRunArtifact(lib_unit_tests);

    const test_step = b.step("test", "Run unit tests");
    test_step.dependOn(&run_lib_unit_tests.step);
}

const std = @import("std");