Skip to content
Standard libraryZig 0.17.0Official documentation
Sourcestd/Build/Step/ObjCopy.zig

Source line 1

Fields

step: Step
input_file: std.Build.LazyPath
basename: Configuration.OptionalString
output_file: Configuration.GeneratedFileIndex
debug_file: ?DebugFile
format: ?Format
only_section: Configuration.OptionalString
pad_to: ?u64
strip: Strip
compress_debug: bool
add_sections: std.ArrayList(AddSection) = .empty
update_sections: std.ArrayList(Configuration.Step.ObjCopy.UpdateSection) = .empty

std.Build.Step.ObjCopy.addSection

function

Source line 108

pub fn addSection(oc: *ObjCopy, section_name: []const u8, options: AddSectionOptions) void

Parameters

oc: *ObjCopy
section_name: []const u8
options: AddSectionOptions

std.Build.Step.ObjCopy.AddSection

container

Source line 28

Fields

section_name: Configuration.String
file_path: std.Build.LazyPath

std.Build.Step.ObjCopy.AddSectionOptions

container

Source line 104

Fields

file_path: std.Build.LazyPath

std.Build.Step.ObjCopy.base_tag

constant

Source line 22

Step.Tag

std.Build.Step.ObjCopy.Configuration

alias

Source line 5

Alias of std.Build.Configuration

std.Build.Step.ObjCopy.create

function

Source line 59

pub fn create(owner: *std.Build, input_file: std.Build.LazyPath, options: Options) *ObjCopy

Parameters

owner: *std.Build
input_file: std.Build.LazyPath
options: Options

std.Build.Step.ObjCopy.DebugFile

container

Source line 33

Fields

std.Build.Step.ObjCopy.Format

container

Source line 24

Fields

binary
hex
elf

std.Build.Step.ObjCopy.getOutput

function

Source line 119

pub fn getOutput(oc: *const ObjCopy) std.Build.LazyPath

Parameters

oc: *const ObjCopy

std.Build.Step.ObjCopy.getOutputSeparatedDebug

function

Source line 123

pub fn getOutputSeparatedDebug(oc: *const ObjCopy) ?std.Build.LazyPath

Parameters

oc: *const ObjCopy

std.Build.Step.ObjCopy.ObjCopy

alias

Source line 1

Alias of std.Build.Step.ObjCopy

std.Build.Step.ObjCopy.Options

container

Source line 38

Fields

basename: ?[]const u8 = null
format: ?Format = null
only_section: ?[]const u8 = null
pad_to: ?u64 = null
compress_debug: bool = false
strip: Strip = .none
separate_debug_file: ?SeparateDebugFile = null

Put the stripped out debug sections in a separate file. note: the basename is baked into the elf file to specify the link to the separate debug file. see https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html

Makes getOutputSeparatedDebug return non-null.

std.Build.Step.ObjCopy.Options.SeparateDebugFile

container

Source line 54

Fields

basename: ?[]const u8

std.Build.Step.ObjCopy.SectionFlags

alias

Source line 26

Alias of std.Build.Configuration.Step.ObjCopy.SectionFlags

std.Build.Step.ObjCopy.std

alias

Source line 3

Alias of std

std.Build.Step.ObjCopy.Step

alias

Source line 4

Alias of std.Build.Step

std.Build.Step.ObjCopy.Strip

alias

Source line 25

Alias of std.Build.Configuration.Step.ObjCopy.Strip

std.Build.Step.ObjCopy.updateSection

function

Source line 91

pub fn updateSection(oc: *ObjCopy, section_name: []const u8, options: UpdateSectionOptions) void

Parameters

oc: *ObjCopy
section_name: []const u8
options: UpdateSectionOptions

std.Build.Step.ObjCopy.UpdateSectionOptions

container

Source line 86

Fields

alignment: ?std.mem.Alignment = null
flags: SectionFlags = .default
Source code

std/Build/Step/ObjCopy.zig

const ObjCopy = @This();

const std = @import("std");
const Step = std.Build.Step;
const Configuration = std.Build.Configuration;

step: Step,
input_file: std.Build.LazyPath,
basename: Configuration.OptionalString,
output_file: Configuration.GeneratedFileIndex,
debug_file: ?DebugFile,

format: ?Format,
only_section: Configuration.OptionalString,
pad_to: ?u64,
strip: Strip,
compress_debug: bool,

add_sections: std.ArrayList(AddSection) = .empty,
update_sections: std.ArrayList(Configuration.Step.ObjCopy.UpdateSection) = .empty,

pub const base_tag: Step.Tag = .obj_copy;

pub const Format = enum { binary, hex, elf };
pub const Strip = Configuration.Step.ObjCopy.Strip;
pub const SectionFlags = Configuration.Step.ObjCopy.SectionFlags;

pub const AddSection = struct {
    section_name: Configuration.String,
    file_path: std.Build.LazyPath,
};

pub const DebugFile = struct {
    basename: Configuration.OptionalString,
    output_file: Configuration.GeneratedFileIndex,
};

pub const Options = struct {
    basename: ?[]const u8 = null,
    format: ?Format = null,
    only_section: ?[]const u8 = null,
    pad_to: ?u64 = null,

    compress_debug: bool = false,
    strip: Strip = .none,

    /// Put the stripped out debug sections in a separate file.
    /// note: the `basename` is baked into the elf file to specify the link to the separate debug file.
    /// see https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html
    ///
    /// Makes `getOutputSeparatedDebug` return non-null.
    separate_debug_file: ?SeparateDebugFile = null,

    pub const SeparateDebugFile = struct {
        basename: ?[]const u8,
    };
};

pub fn create(owner: *std.Build, input_file: std.Build.LazyPath, options: Options) *ObjCopy {
    const graph = owner.graph;
    const wc = &graph.wip_configuration;
    const oc = graph.create(ObjCopy);
    oc.* = .{
        .step = .init(.{
            .tag = base_tag,
            .name = owner.fmt("objcopy {f}", .{input_file}),
            .owner = owner,
        }),
        .input_file = input_file,
        .basename = if (options.basename) |s| .init(wc.addString(s) catch @panic("OOM")) else .none,
        .output_file = graph.addGeneratedFile(&oc.step),
        .debug_file = if (options.separate_debug_file) |df| .{
            .basename = if (df.basename) |s| .init(wc.addString(s) catch @panic("OOM")) else .none,
            .output_file = graph.addGeneratedFile(&oc.step),
        } else null,
        .format = options.format,
        .only_section = if (options.only_section) |s| .init(wc.addString(s) catch @panic("OOM")) else .none,
        .pad_to = options.pad_to,
        .strip = options.strip,
        .compress_debug = options.compress_debug,
    };
    input_file.addStepDependencies(&oc.step);
    return oc;
}

pub const UpdateSectionOptions = struct {
    alignment: ?std.mem.Alignment = null,
    flags: SectionFlags = .default,
};

pub fn updateSection(oc: *ObjCopy, section_name: []const u8, options: UpdateSectionOptions) void {
    const graph = oc.step.owner.graph;
    const arena = graph.arena;
    const wc = &graph.wip_configuration;
    oc.update_sections.append(arena, .{
        .flags = .{
            .section_flags = options.flags,
            .alignment = .init(options.alignment),
        },
        .section_name = wc.addString(section_name) catch @panic("OOM"),
    }) catch @panic("OOM");
}

pub const AddSectionOptions = struct {
    file_path: std.Build.LazyPath,
};

pub fn addSection(oc: *ObjCopy, section_name: []const u8, options: AddSectionOptions) void {
    const graph = oc.step.owner.graph;
    const arena = graph.arena;
    const wc = &graph.wip_configuration;
    oc.add_sections.append(arena, .{
        .section_name = wc.addString(section_name) catch @panic("OOM"),
        .file_path = options.file_path,
    }) catch @panic("OOM");
    options.file_path.addStepDependencies(&oc.step);
}

pub fn getOutput(oc: *const ObjCopy) std.Build.LazyPath {
    return .{ .generated = .{ .index = oc.output_file } };
}

pub fn getOutputSeparatedDebug(oc: *const ObjCopy) ?std.Build.LazyPath {
    const df = oc.debug_file orelse return null;
    return .{ .generated = .{ .index = df.output_file } };
}