Zig 0.17.0-dev (Split by item)

This is an example of documentation generated by ZigDoc, an alternative to Zig's built-in Auto Doc feature. See also examples in other modes/formats. The project being documented here (as the example) is the Zig library itself.

run

Run pkg-config for the given library name and parse the output, returning the arguments that should be passed to zig to link the given library.

PkgConfig.run
pub fn run(
    maker: *Maker,
    step: *Step,
    arena: Allocator,
    progress_node: std.Progress.Node,
    lib_name: []const u8,
    /// If true, reports failure error messages on step rather than returning
    /// error.PackageNotFound or error.PkgConfigUnavailable,
    force: bool,
) RunError!Result

File

lib/compiler/Maker/PkgConfig.zig:24

Code

pub fn run(
    maker: *Maker,
    step: *Step,
    arena: Allocator,
    progress_node: std.Progress.Node,
    lib_name: []const u8,
    /// If true, reports failure error messages on step rather than returning
    /// error.PackageNotFound or error.PkgConfigUnavailable,
    force: bool,
) RunError!Result {
    const pc = &maker.pkg_config;
    const graph = maker.graph;

    const pkg_config_exe = getExe(graph);
    const pkgs = try getPkgs(maker, step, progress_node, force);
    const found_index = pkgs.find(lib_name) orelse {
        if (force) return step.fail(maker, "{s}: package not found: {s}", .{ pkg_config_exe, lib_name });
        return error.PackageNotFound;
    };
    const pkg = pkgs.all[found_index];

    const stdout = try captureChildProcess(maker, step, arena, .{
        .argv = &.{ pkg_config_exe, pkg.name, "--cflags", "--libs" },
        .progress_node = progress_node,
        .allow_failure = !force,
    });

    const parsed = std.zig.PkgConfig.parse(arena, stdout) catch |err| switch (err) {
        error.InvalidPkgConfigOutput => {
            if (force) return step.fail(maker, "{s} package {s} invalid output: {s}", .{
                pkg_config_exe, lib_name, stdout,
            });
            return error.PkgConfigUnavailable;
        },
        else => |e| return e,
    };
    if (force or pc.debug) {
        for (parsed.unknown_flags) |unknown_flag| {
            return step.fail(maker, "{s} package {s} unknown flag: {s}", .{ pkg_config_exe, lib_name, unknown_flag });
        }
    }

    return parsed;
}