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.

cmdInit

Maker.cmdInit
fn cmdInit(gpa: Allocator, graph: *Graph, args: []const []const u8) !void

File

lib/compiler/Maker.zig:1777

Code

fn cmdInit(gpa: Allocator, graph: *Graph, args: []const []const u8) !void {
    const arena = graph.arena;
    const io = graph.io;
    const default_build_zig_basename = std.zig.build_zig_basename;

    var template: enum { example, minimal } = .example;
    {
        var i: usize = 0;
        while (i < args.len) : (i += 1) {
            const arg = args[i];
            if (mem.startsWith(u8, arg, "-")) {
                if (mem.eql(u8, arg, "-m") or mem.eql(u8, arg, "--minimal")) {
                    template = .minimal;
                } else if (mem.eql(u8, arg, "-h") or mem.eql(u8, arg, "--help")) {
                    try Io.File.stdout().writeStreamingAll(io, usage_init);
                    return process.cleanExit(io);
                } else {
                    fatal("unrecognized parameter: {q}", .{arg});
                }
            } else {
                fatal("unexpected extra parameter: {q}", .{arg});
            }
        }
    }

    const cwd_path = try std.zig.getResolvedCwd(io, arena);
    const cwd_basename = Dir.path.basename(cwd_path);
    const sanitized_root_name = try sanitizeExampleName(arena, cwd_basename);

    const rng: std.Random.IoSource = .{ .io = io };
    const fingerprint: Package.Fingerprint = .generate(rng.interface(), sanitized_root_name);

    switch (template) {
        .example => {
            var templates = Templates.find(gpa, io, graph.zig_lib_directory);
            defer templates.deinit(io);

            const s = Dir.path.sep_str;
            const template_paths = [_][]const u8{
                default_build_zig_basename,
                Package.Manifest.basename,
                "src" ++ s ++ "main.zig",
                "src" ++ s ++ "root.zig",
            };
            var ok_count: usize = 0;

            for (template_paths) |template_path| {
                if (templates.write(arena, io, Io.Dir.cwd(), sanitized_root_name, template_path, fingerprint)) |_| {
                    log.info("created {s}", .{template_path});
                    ok_count += 1;
                } else |err| switch (err) {
                    error.PathAlreadyExists => log.info("preserving already existing file: {s}", .{
                        template_path,
                    }),
                    else => log.err("unable to write {s}: {t}", .{ template_path, err }),
                }
            }

            if (ok_count == template_paths.len) {
                log.info("see `zig build --help` for a menu of options", .{});
            }
            return process.cleanExit(io);
        },
        .minimal => {
            Templates.writeSimpleFile(io, Package.Manifest.basename,
                \\.{{
                \\    .name = .{s},
                \\    .version = "0.0.1",
                \\    .minimum_zig_version = "{s}",
                \\    .paths = .{{""}},
                \\    .fingerprint = 0x{x},
                \\}}
                \\
            , .{
                sanitized_root_name,
                builtin.zig_version_string,
                fingerprint.int(),
            }) catch |err| switch (err) {
                else => fatal("failed to create {q}: {t}", .{ Package.Manifest.basename, err }),
                error.PathAlreadyExists => fatal("refusing to overwrite {q}", .{Package.Manifest.basename}),
            };
            Templates.writeSimpleFile(io, default_build_zig_basename,
                \\const std = @import("std");
                \\
                \\pub fn build(b: *std.Build) void {{
                \\    _ = b; // stub
                \\}}
                \\
            , .{}) catch |err| switch (err) {
                else => fatal("failed to create {q}: {t}", .{ default_build_zig_basename, err }),
                // `build.zig` already existing is okay: the user has just used `zig init` to set up
                // their `build.zig.zon` *after* writing their `build.zig`. So this one isn't fatal.
                error.PathAlreadyExists => {
                    log.info("successfully populated {q}, preserving existing {q}", .{
                        Package.Manifest.basename, default_build_zig_basename,
                    });
                    return process.cleanExit(io);
                },
            };
            log.info("successfully populated {q} and {q}", .{ Package.Manifest.basename, default_build_zig_basename });
            return process.cleanExit(io);
        },
    }
}