构建系统高级主题

// 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)
// 使用总体标准差公式：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
// 偏差 > 3.0 的度量被认为是可变的，否则是稳定的
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.
// ! 或以 CSV 格式导出它们以进行进一步分析。

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
// /   - metric: 要渲染的分析指标
// /   - writer: Any writer interface that supports the print() method
// /   - writer: 支持 print() 方法的任何写入器接口
///
// / 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.
// / 将指标的统计数据导出为 CSV 格式的字符串。
// / Creates a two-row CSV with headers and a single data row containing
// / 创建一个包含标题的两行 CSV，以及一个包含
// / the metric's name, mean, deviation, and highlight label.
// / 指标名称、平均值、偏差和高亮标签的单行数据。
///
/// Parameters:
// /   - metric: The analytics metric to export
// /   - metric: 要导出的分析指标
// /   - allocator: Memory allocator for the resulting string
// /   - allocator: 用于结果字符串的内存分配器
///
// / Returns a heap-allocated CSV string, or an error if allocation or formatting fails.
// / 返回一个堆分配的 CSV 字符串，如果分配或格式化失败，则返回错误。
// / 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");

//  将度量序列化为JSON格式的字符串表示。
///
//  创建一个格式化的JSON对象，包含度量名称、计算的平均值、
//  标准差和性能配置文件分类。调用者拥有
//  返回的内存，并在使用完毕后必须释放。
///
//  返回一个包含JSON表示的已分配字符串，如果分配失败则返回错误。
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
// 导入 analytics 模块以获取度量数据结构
const analytics = @import("analytics");
// Import reporting module for metric rendering
// 导入 reporting 模块以进行度量渲染
const reporting = @import("reporting");
// Import adapters module for data format conversion
// 导入 adapters 模块以进行数据格式转换
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
    // 初始化一个缓冲写入器以提高标准输出I/O性能
    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
    // 使用 reporting 模块的格式化功能渲染度量
    try reporting.render(metric, out);

    // Initialize general purpose allocator for JSON serialization
    // 初始化用于JSON序列化的通用分配器
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    // Ensure allocator cleanup on function exit
    // 确保函数退出时清理分配器
    defer _ = gpa.deinit();

    // Convert metric to JSON format using the adapters module
    // 使用 adapters 模块将度量转换为JSON格式
    const json = try adapters.emitJson(metric, gpa.allocator());
    // Free allocated JSON string when done
    // 完成后释放已分配的JSON字符串
    defer gpa.allocator().free(json);

    // Output the JSON representation of the metric
    // 输出度量的JSON表示
    try out.print("json export: {s}\n", .{json});
    // Flush buffered output to ensure all data is written
    // 刷新缓冲输出以确保所有数据写入
    try out.flush();
}

const std = @import("std");

/// 表示构建矩阵中目标/优化组合的结构
/// 每个组合定义具有描述性名称的唯一构建配置
const Combo = struct {
    // 构建配置的人类可读标识符
    name: []const u8,
    // 指定CPU架构、操作系统和ABI的目标查询
    query: std.Target.Query,
    // 优化级别（Debug、ReleaseSafe、ReleaseFast或ReleaseSmall）
    optimize: std.builtin.OptimizeMode,
};

pub fn build(b: *std.Build) void {
    // 定义要构建的目标/优化组合矩阵
    // 这演示了交叉编译能力和优化策略
    const combos = [_]Combo{
        // 用于开发的带调试符号的原生构建
        .{ .name = "native-debug", .query = .{}, .optimize = .Debug },
        // 针对最大性能优化的Linux x86_64构建
        .{ .name = "linux-fast", .query = .{ .cpu_arch = .x86_64, .os_tag = .linux, .abi = .gnu }, .optimize = .ReleaseFast },
        // 针对最小二进制大小优化的WebAssembly构建
        .{ .name = "wasi-small", .query = .{ .cpu_arch = .wasm32, .os_tag = .wasi }, .optimize = .ReleaseSmall },
    };

    // 创建构建所有目标/优化组合的顶级步骤
    // 用户可以使用`zig build matrix`调用
    const matrix_step = b.step("matrix", "Build every target/optimize pair");

    // 跟踪第一个（主机）可执行文件的运行步骤以创建健全性检查
    var host_run_step: ?*std.Build.Step = null;

    // 迭代每个组合以创建和配置构建工件
    for (combos, 0..) |combo, index| {
        // 将目标查询解析为具体的目标规范
        // 这验证查询并用默认值填充任何未指定的字段
        const resolved = b.resolveTargetQuery(combo.query);

        // 使用解析的目标和优化设置创建模块
        // 使用createModule允许对编译参数进行精确控制
        const module = b.createModule(.{
            .root_source_file = b.path("matrix/app.zig"),
            .target = resolved,
            .optimize = combo.optimize,
        });

        // 为此组合创建具有唯一名称的可执行文件工件
        // 名称包括组合标识符以区分构建输出
        const exe = b.addExecutable(.{
            .name = b.fmt("matrix-{s}", .{combo.name}),
            .root_module = module,
        });

        // 将可执行文件安装到zig-out/bin以便分发
        b.installArtifact(exe);

        // 将此可执行文件的构建步骤添加为矩阵步骤的依赖项
        // 这确保在运行`zig build matrix`时构建所有可执行文件
        matrix_step.dependOn(&exe.step);

        // 对于第一个组合（假定为主机/宿主目标），
        // 为快速测试和验证创建运行步骤
        if (index == 0) {
            // 创建运行主机可执行文件的命令
            const run_cmd = b.addRunArtifact(exe);

            // 将任何命令行参数转发到可执行文件
            if (b.args) |args| {
                run_cmd.addArgs(args);
            }

            // 创建用于运行主机变体的专用步骤
            const run_step = b.step("run-host", "Run host variant for sanity checks");
            run_step.dependOn(&run_cmd.step);

            // 存储运行步骤以供矩阵步骤后续使用
            host_run_step = run_step;
        }
    }

    // 如果创建了主机运行步骤，将其添加为矩阵步骤的依赖项
    // 这确保构建矩阵也在主机可执行文件上运行健全性检查
    if (host_run_step) |run_step| {
        matrix_step.dependOn(run_step);
    }
}