chore: add comment to build.zig

Author: jinzhongjia

build.zig

@@ -3,34 +3,41 @@ const builtin = @import("builtin");
 
 const Build = std.Build;
 
+// Minimum required Zig version for this project
 const min_zig_string = "0.12.0";
 const current_zig = builtin.zig_version;
 
 // NOTE: we should note that when enable tls support we cannot compile with musl
 
+// Compile-time check to ensure the Zig version meets the minimum requirement
 comptime {
     const min_zig = std.SemanticVersion.parse(min_zig_string) catch unreachable;
     if (current_zig.order(min_zig) == .lt) {
         @compileError(std.fmt.comptimePrint("Your Zig version v{} does not meet the minimum build requirement of v{}", .{ current_zig, min_zig }));
     }
 }
 
+// Define logger and useful type aliases
 const log = std.log.scoped(.WebUI);
 const OptimizeMode = std.builtin.OptimizeMode;
 const CrossTarget = std.Target.Query;
 const Compile = Build.Step.Compile;
 const Module = Build.Module;
 
+// Default build configuration options
 const default_isStatic = true;
 const default_enableTLS = false;
 
 pub fn build(b: *Build) !void {
+    // Parse command-line options or use defaults
     const isStatic = b.option(bool, "is_static", "whether lib is static") orelse default_isStatic;
     const enableTLS = b.option(bool, "enable_tls", "whether lib enable tls") orelse default_enableTLS;
 
+    // Standard build options for target and optimization
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});
 
+    // TLS support has some limitations
     if (enableTLS) {
         log.info("enable TLS support", .{});
         if (!target.query.isNative()) {
@@ -39,15 +46,16 @@ pub fn build(b: *Build) !void {
         }
     }
 
-    // create a options for command parameter
+    // Create build options that will be used as a module
     const flags_options = b.addOptions();
 
-    // add option
+    // Configure compile-time options
     flags_options.addOption(bool, "enableTLS", enableTLS);
 
-    // create a new module for flags options
+    // Create a module that exposes the options
     const flags_module = flags_options.createModule();
 
+    // Get the webui dependency with appropriate options
     const webui = b.dependency("webui", .{
         .target = target,
         .optimize = optimize,
@@ -56,6 +64,7 @@ pub fn build(b: *Build) !void {
         .verbose = .err,
     });
 
+    // Create the webui module that applications can import
     const webui_module = b.addModule("webui", .{
         .root_source_file = b.path(b.pathJoin(&.{ "src", "webui.zig" })),
         .imports = &.{
@@ -65,22 +74,26 @@ pub fn build(b: *Build) !void {
             },
         },
     });
+    // Link against the webui library
     webui_module.linkLibrary(webui.artifact("webui"));
     if (!isStatic) {
+        // For dynamic libraries, install the shared library
         b.installArtifact(webui.artifact("webui"));
     }
 
-    // generate docs
+    // Setup documentation generation
     generate_docs(b, optimize, target, flags_module);
 
-    // build examples
+    // Build example applications
     build_examples(b, optimize, target, webui_module, webui.artifact("webui")) catch |err| {
         log.err("failed to build examples: {}", .{err});
         std.process.exit(1);
     };
 }
 
+// Function to generate API documentation
 fn generate_docs(b: *Build, optimize: OptimizeMode, target: Build.ResolvedTarget, flags_module: *Module) void {
+    // Create a temporary object for documentation generation
     const webui_lib = b.addObject(.{
         .name = "webui_lib",
         .root_source_file = b.path(b.pathJoin(&.{ "src", "webui.zig" })),
@@ -90,8 +103,10 @@ fn generate_docs(b: *Build, optimize: OptimizeMode, target: Build.ResolvedTarget
 
     webui_lib.root_module.addImport("flags", flags_module);
 
+    // Create a build step for documentation
     const docs_step = b.step("docs", "Generate docs");
 
+    // Setup documentation installation
     const docs_install = b.addInstallDirectory(.{
         .source_dir = webui_lib.getEmittedDocs(),
         .install_dir = .prefix,
@@ -101,15 +116,18 @@ fn generate_docs(b: *Build, optimize: OptimizeMode, target: Build.ResolvedTarget
     docs_step.dependOn(&docs_install.step);
 }
 
+// Function to build all example applications
 fn build_examples(b: *Build, optimize: OptimizeMode, target: Build.ResolvedTarget, webui_module: *Module, webui_lib: *Compile) !void {
 
-    // we use lazyPath to get absolute path of package
+    // Get the absolute path to the examples directory
     var lazy_path = b.path("examples");
 
+    // Create a step to build all examples
     const build_all_step = b.step("examples", "build all examples");
 
     const examples_path = lazy_path.getPath(b);
 
+    // Open the examples directory for iteration
     var iter_dir = std.fs.openDirAbsolute(
         examples_path,
         .{ .iterate = true },
@@ -123,6 +141,7 @@ fn build_examples(b: *Build, optimize: OptimizeMode, target: Build.ResolvedTarge
 
     var itera = iter_dir.iterate();
 
+    // Iterate through all subdirectories in the examples directory
     while (try itera.next()) |val| {
         if (val.kind != .directory) {
             continue;
@@ -131,32 +150,37 @@ fn build_examples(b: *Build, optimize: OptimizeMode, target: Build.ResolvedTarge
         const example_name = val.name;
         const path = b.pathJoin(&.{ "examples", example_name, "main.zig" });
 
+        // Create an executable for each example
         const exe = b.addExecutable(.{
             .name = example_name,
             .root_source_file = b.path(path),
             .target = target,
             .optimize = optimize,
         });
 
+        // Add the webui module and link against the library
         exe.root_module.addImport("webui", webui_module);
         exe.linkLibrary(webui_lib);
 
+        // Setup installation
         const exe_install = b.addInstallArtifact(exe, .{});
 
         build_all_step.dependOn(&exe_install.step);
 
+        // Create a run step for the example
         const exe_run = b.addRunArtifact(exe);
         exe_run.step.dependOn(&exe_install.step);
 
+        // Set the working directory for the run
         const cwd = b.path(b.pathJoin(&.{ "examples", example_name }));
-
         exe_run.setCwd(cwd);
 
+        // Create a named step to run this specific example
         const step_name = try std.fmt.allocPrint(b.allocator, "run_{s}", .{example_name});
-
         const step_desc = try std.fmt.allocPrint(b.allocator, "run_{s}", .{example_name});
 
         const exe_run_step = b.step(step_name, step_desc);
         exe_run_step.dependOn(&exe_run.step);
     }
 }
+