Build System Advanced Topics

// Analytics library for statistical calculations on metrics
const std = @import("std");

// Represents a named metric with associated numerical values
pub const Metric = struct {
    name: []const u8,
    values: []const f64,
};

// Calculates the arithmetic mean (average) of all values in a metric
// Returns the sum of all values divided by the count
pub fn mean(metric: Metric) f64 {
    var total: f64 = 0;
    for (metric.values) |value| {
        total += value;
    }
    return total / @as(f64, @floatFromInt(metric.values.len));
}

// Calculates the standard deviation of values in a metric
// Uses the population standard deviation formula: sqrt(sum((x - mean)^2) / n)
pub fn deviation(metric: Metric) f64 {
    const avg = mean(metric);
    var accum: f64 = 0;
    // Sum the squared differences from the mean
    for (metric.values) |value| {
        const delta = value - avg;
        accum += delta * delta;
    }
    // Return the square root of the variance
    return std.math.sqrt(accum / @as(f64, @floatFromInt(metric.values.len)));
}

// Classifies a metric as "variable" or "stable" based on its standard deviation
// Metrics with deviation > 3.0 are considered variable, otherwise stable
pub fn highlight(metric: Metric) []const u8 {
    return if (deviation(metric) > 3.0)
        "variable"
    else
        "stable";
}

//! Reporting module for displaying analytics metrics in various formats.
//! This module provides utilities to render metrics as human-readable text
//! or export them in CSV format for further analysis.

const std = @import("std");
const analytics = @import("analytics");

/// Renders a metric's statistics to a writer in a human-readable format.
/// Outputs the metric name, number of data points, mean, standard deviation,
/// and performance profile label.
///
/// Parameters:
///   - metric: The analytics metric to render
///   - writer: Any writer interface that supports the print() method
///
/// Returns an error if writing to the output fails.
pub fn render(metric: analytics.Metric, writer: anytype) !void {
    try writer.print("metric: {s}\n", .{metric.name});
    try writer.print("count: {}\n", .{metric.values.len});
    try writer.print("mean: {d:.2}\n", .{analytics.mean(metric)});
    try writer.print("deviation: {d:.2}\n", .{analytics.deviation(metric)});
    try writer.print("profile: {s}\n", .{analytics.highlight(metric)});
}

/// Exports a metric's statistics as a CSV-formatted string.
/// Creates a two-row CSV with headers and a single data row containing
/// the metric's name, mean, deviation, and highlight label.
///
/// Parameters:
///   - metric: The analytics metric to export
///   - allocator: Memory allocator for the resulting string
///
/// Returns a heap-allocated CSV string, or an error if allocation or formatting fails.
/// Caller is responsible for freeing the returned memory.
pub fn csv(metric: analytics.Metric, allocator: std.mem.Allocator) ![]u8 {
    return std.fmt.allocPrint(
        allocator,
        "name,mean,deviation,label\n{s},{d:.3},{d:.3},{s}\n",
        .{ metric.name, analytics.mean(metric), analytics.deviation(metric), analytics.highlight(metric) },
    );
}

const std = @import("std");
const analytics = @import("analytics");

/// Serializes a metric into a JSON-formatted string representation.
/// 
/// Creates a formatted JSON object containing the metric's name, calculated mean,
/// standard deviation, and performance profile classification. The caller owns
/// the returned memory and must free it when done.
///
/// Returns an allocated string containing the JSON representation, or an error
/// if allocation fails.
pub fn emitJson(metric: analytics.Metric, allocator: std.mem.Allocator) ![]u8 {
    return std.fmt.allocPrint(
        allocator,
        "{{\n  \"name\": \"{s}\",\n  \"mean\": {d:.3},\n  \"deviation\": {d:.3},\n  \"profile\": \"{s}\"\n}}\n",
        .{ metric.name, analytics.mean(metric), analytics.deviation(metric), analytics.highlight(metric) },
    );
}

// Import standard library for core functionality
const std = @import("std");
// Import analytics module for metric data structures
const analytics = @import("analytics");
// Import reporting module for metric rendering
const reporting = @import("reporting");
// Import adapters module for data format conversion
const adapters = @import("adapters");

/// Application entry point demonstrating workspace dependency usage
/// Shows how to use multiple workspace modules together for metric processing
pub fn main() !void {
    // Create a fixed-size buffer for stdout operations to avoid dynamic allocation
    var stdout_buffer: [512]u8 = undefined;
    // Initialize a buffered writer for stdout to improve I/O performance
    var writer_state = std.fs.File.stdout().writer(&stdout_buffer);
    const out = &writer_state.interface;

    // Create a sample metric with response time measurements in milliseconds
    const metric = analytics.Metric{
        .name = "response_ms",
        .values = &.{ 12.0, 12.4, 11.9, 12.1, 17.0, 12.3 },
    };

    // Render the metric using the reporting module's formatting
    try reporting.render(metric, out);

    // Initialize general purpose allocator for JSON serialization
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    // Ensure allocator cleanup on function exit
    defer _ = gpa.deinit();

    // Convert metric to JSON format using the adapters module
    const json = try adapters.emitJson(metric, gpa.allocator());
    // Free allocated JSON string when done
    defer gpa.allocator().free(json);

    // Output the JSON representation of the metric
    try out.print("json export: {s}\n", .{json});
    // Flush buffered output to ensure all data is written
    try out.flush();
}

const std = @import("std");

/// Represents a target/optimization combination in the build matrix
/// Each combo defines a unique build configuration with a descriptive name
const Combo = struct {
    /// Human-readable identifier for this build configuration
    name: []const u8,
    /// Target query specifying the CPU architecture, OS, and ABI
    query: std.Target.Query,
    /// Optimization level (Debug, ReleaseSafe, ReleaseFast, or ReleaseSmall)
    optimize: std.builtin.OptimizeMode,
};

pub fn build(b: *std.Build) void {
    // Define a matrix of target/optimization combinations to build
    // This demonstrates cross-compilation capabilities and optimization strategies
    const combos = [_]Combo{
        // Native build with debug symbols for development
        .{ .name = "native-debug", .query = .{}, .optimize = .Debug },
        // Linux x86_64 build optimized for maximum performance
        .{ .name = "linux-fast", .query = .{ .cpu_arch = .x86_64, .os_tag = .linux, .abi = .gnu }, .optimize = .ReleaseFast },
        // WebAssembly build optimized for minimal binary size
        .{ .name = "wasi-small", .query = .{ .cpu_arch = .wasm32, .os_tag = .wasi }, .optimize = .ReleaseSmall },
    };

    // Create a top-level step that builds all target/optimize combinations
    // Users can invoke this with `zig build matrix`
    const matrix_step = b.step("matrix", "Build every target/optimize pair");

    // Track the run step for the first (host) executable to create a sanity check
    var host_run_step: ?*std.Build.Step = null;

    // Iterate through each combo to create and configure build artifacts
    for (combos, 0..) |combo, index| {
        // Resolve the target query into a concrete target specification
        // This validates the query and fills in any unspecified fields with defaults
        const resolved = b.resolveTargetQuery(combo.query);
        
        // Create a module with the resolved target and optimization settings
        // Using createModule allows precise control over compilation parameters
        const module = b.createModule(.{
            .root_source_file = b.path("matrix/app.zig"),
            .target = resolved,
            .optimize = combo.optimize,
        });

        // Create an executable artifact with a unique name for this combo
        // The name includes the combo identifier to distinguish build outputs
        const exe = b.addExecutable(.{
            .name = b.fmt("matrix-{s}", .{combo.name}),
            .root_module = module,
        });

        // Install the executable to zig-out/bin for distribution
        b.installArtifact(exe);
        
        // Add this executable's build step as a dependency of the matrix step
        // This ensures all executables are built when running `zig build matrix`
        matrix_step.dependOn(&exe.step);

        // For the first combo (assumed to be the native/host target),
        // create a run step for quick testing and validation
        if (index == 0) {
            // Create a command to run the host executable
            const run_cmd = b.addRunArtifact(exe);
            
            // Forward any command-line arguments to the executable
            if (b.args) |args| {
                run_cmd.addArgs(args);
            }
            
            // Create a dedicated step for running the host variant
            const run_step = b.step("run-host", "Run host variant for sanity checks");
            run_step.dependOn(&run_cmd.step);
            
            // Store the run step for later use in the matrix step
            host_run_step = run_step;
        }
    }

    // If a host run step was created, add it as a dependency to the matrix step
    // This ensures that building the matrix also runs a sanity check on the host executable
    if (host_run_step) |run_step| {
        matrix_step.dependOn(run_step);
    }
}