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

Source line 1

Fields

owner: *std.Build

The one responsible for creating this module.

root_source_file: ?LazyPath
import_table: std.array_hash_map.String(*Module)

The modules that are mapped into this module's import table. Use addImport rather than modifying this field directly in order to maintain step dependency edges.

resolved_target: ?std.Build.ResolvedTarget = null
optimize: ?std.builtin.Optimize = null
dwarf_format: ?std.dwarf.Format
c_macros: ArrayList([]const u8)
include_dirs: ArrayList(IncludeDir)
lib_paths: ArrayList(LazyPath)
rpaths: ArrayList(RPath)
frameworks: std.array_hash_map.String(LinkFrameworkOptions)
link_objects: ArrayList(LinkObject)
strip: ?bool
unwind_tables: ?std.builtin.UnwindTables
single_threaded: ?bool
stack_protector: ?bool
stack_check: ?bool
sanitize_c: ?std.zig.SanitizeC
sanitize_thread: ?bool
fuzz: ?bool
code_model: std.builtin.CodeModel
valgrind: ?bool
pic: ?bool
red_zone: ?bool
omit_frame_pointer: ?bool
error_tracing: ?bool
link_libc: ?bool
link_libcpp: ?bool
no_builtin: ?bool
patchable_function_entry: u16
export_symbol_names: []const []const u8 = &.{}

Symbols to be exported when compiling to WebAssembly.

cached_graph: Graph = .{ .modules = &.{}, .names = &.{} }

Caches the result of getGraph when called multiple times. Use getGraph instead of accessing this field directly.

std.Build.Module.addAfterIncludePath

function

Source line 464

pub fn addAfterIncludePath(m: *Module, lazy_path: LazyPath) void

Parameters

m: *Module
lazy_path: LazyPath

std.Build.Module.addAnonymousImport

function

Source line 313

Creates a new module and adds it to be used with @import.

pub fn addAnonymousImport(m: *Module, name: []const u8, options: CreateOptions) void

Parameters

m: *Module
name: []const u8
options: CreateOptions

std.Build.Module.addAssemblyFile

function

Source line 442

pub fn addAssemblyFile(m: *Module, source: LazyPath) void

Parameters

m: *Module
source: LazyPath

std.Build.Module.addCMacro

function

Source line 530

Equvialent to the following C code, applied to all C source files owned by this Module:

#define name value

name and value need not live longer than the function call.

pub fn addCMacro(m: *Module, name: []const u8, value: []const u8) void

Parameters

m: *Module
name: []const u8
value: []const u8

std.Build.Module.addConfigHeader

function

Source line 482

pub fn addConfigHeader(m: *Module, config_header: *Step.ConfigHeader) void

Parameters

m: *Module
config_header: *Step.ConfigHeader

std.Build.Module.addCSourceFile

function

Source line 415

pub fn addCSourceFile(m: *Module, source: CSourceFile) void

Parameters

m: *Module
source: CSourceFile

std.Build.Module.addCSourceFiles

function

Source line 391

Handy when you have many non-Zig source files and want them all to have the same flags.

pub fn addCSourceFiles(m: *Module, options: AddCSourceFilesOptions) void

Parameters

std.Build.Module.AddCSourceFilesOptions

container

Source line 380

Fields

root: ?LazyPath = null

When provided, files are relative to root rather than the package that owns the Compile step.

files: []const []const u8
flags: []const []const u8 = &.{}
language: ?CSourceLanguage = null

By default, determines language of each file individually based on its file extension

std.Build.Module.addEmbedPath

function

Source line 500

pub fn addEmbedPath(m: *Module, lazy_path: LazyPath) void

Parameters

m: *Module
lazy_path: LazyPath

std.Build.Module.addFrameworkPath

function

Source line 494

pub fn addFrameworkPath(m: *Module, directory_path: LazyPath) void

Parameters

m: *Module
directory_path: LazyPath

std.Build.Module.addImport

function

Source line 306

Adds an existing module to be used with @import.

pub fn addImport(m: *Module, name: []const u8, module: *Module) void

Parameters

m: *Module
name: []const u8
module: *Module

std.Build.Module.addIncludePath

function

Source line 476

pub fn addIncludePath(m: *Module, lazy_path: LazyPath) void

Parameters

m: *Module
lazy_path: LazyPath

std.Build.Module.addLibraryPath

function

Source line 506

pub fn addLibraryPath(m: *Module, directory_path: LazyPath) void

Parameters

m: *Module
directory_path: LazyPath

std.Build.Module.addObject

function

Source line 454

pub fn addObject(m: *Module, object: *Step.Compile) void

Parameters

m: *Module
object: *Step.Compile

std.Build.Module.addObjectFile

function

Source line 448

pub fn addObjectFile(m: *Module, object: LazyPath) void

Parameters

m: *Module
object: LazyPath

std.Build.Module.addOptions

function

Source line 321

Converts a set of key-value pairs into a Zig source file, and then inserts it into the Module's import table with the specified name. This makes the options importable via @import("module_name").

pub fn addOptions(m: *Module, module_name: []const u8, options: *Step.Options) void

Parameters

m: *Module
module_name: []const u8
options: *Step.Options

std.Build.Module.addRPath

function

Source line 512

pub fn addRPath(m: *Module, directory_path: LazyPath) void

Parameters

m: *Module
directory_path: LazyPath

std.Build.Module.addRPathSpecial

function

Source line 518

pub fn addRPathSpecial(m: *Module, bytes: []const u8) void

Parameters

m: *Module
bytes: []const u8

std.Build.Module.addSystemFrameworkPath

function

Source line 488

pub fn addSystemFrameworkPath(m: *Module, directory_path: LazyPath) void

Parameters

m: *Module
directory_path: LazyPath

std.Build.Module.addSystemIncludePath

function

Source line 470

pub fn addSystemIncludePath(m: *Module, lazy_path: LazyPath) void

Parameters

m: *Module
lazy_path: LazyPath

std.Build.Module.addWin32ResourceFile

function

Source line 429

Deprecated. This functionality will be moved to an external package: https://codeberg.org/ziglang/rc

Resource files must have the extension .rc. Can be called regardless of target. The .rc file will be ignored if the target object format does not support embedded resources.

pub fn addWin32ResourceFile(m: *Module, source: RcSourceFile) void

Parameters

m: *Module
source: RcSourceFile

std.Build.Module.ArrayList

alias

Source line 7

Alias of std.ArrayList

std.Build.Module.assert

alias

Source line 4

Alias of std.debug.assert

std.Build.Module.create

function

Source line 297

pub fn create(owner: *std.Build, options: CreateOptions) *Module

Parameters

owner: *std.Build
options: CreateOptions

std.Build.Module.CreateOptions

container

Source line 191

Unspecified options here will be inherited from parent Module when inserted into an import table.

Fields

root_source_file: ?LazyPath = null

This could either be a generated file, in which case the module contains exactly one file, or it could be a path to the root source file of directory of files which constitute the module. If null, it means this module is made up of only link_objects.

imports: []const Import = &.{}

The table of other modules that this module can access via @import. Imports are allowed to be cyclical, so this table can be added to after the Module is created via addImport.

target: ?std.Build.ResolvedTarget = null
optimize: ?std.builtin.Optimize = null
link_libc: ?bool = null

true requires a compilation that includes this Module to link libc. false causes a build failure if a compilation that includes this Module would link libc. null neither requires nor prevents libc from being linked.

link_libcpp: ?bool = null

true requires a compilation that includes this Module to link libc++. false causes a build failure if a compilation that includes this Module would link libc++. null neither requires nor prevents libc++ from being linked.

single_threaded: ?bool = null
strip: ?bool = null
unwind_tables: ?std.builtin.UnwindTables = null
dwarf_format: ?std.dwarf.Format = null
code_model: std.builtin.CodeModel = .default
stack_protector: ?bool = null
stack_check: ?bool = null
sanitize_c: ?std.zig.SanitizeC = null
sanitize_thread: ?bool = null
fuzz: ?bool = null
valgrind: ?bool = null

Whether to emit machine code that integrates with Valgrind.

pic: ?bool = null

Position Independent Code

red_zone: ?bool = null
omit_frame_pointer: ?bool = null

Whether to omit the stack frame pointer. Frees up a register and makes it more difficult to obtain stack traces. Has target-dependent effects.

error_tracing: ?bool = null
no_builtin: ?bool = null
patchable_function_entry: u16 = 0

std.Build.Module.CSourceFile

container

Source line 118

Fields

file: LazyPath
flags: []const []const u8 = &.{}
language: ?CSourceLanguage = null

By default, determines language of each file individually based on its file extension

std.Build.Module.CSourceFile.dupe

function

Source line 124

pub fn dupe(file: CSourceFile, graph: *const std.Build.Graph) CSourceFile

Parameters

file: CSourceFile
graph: *const std.Build.Graph

std.Build.Module.CSourceFiles

container

Source line 108

Fields

root: LazyPath
files: []const []const u8

files is relative to root, which is the build root by default

flags: []const []const u8
language: ?CSourceLanguage

By default, determines language of each file individually based on its file extension

std.Build.Module.CSourceLanguage

container

Source line 83

Fields

c
cpp
objective_c
objective_cpp
assembly

Standard assembly

assembly_with_preprocessor

Assembly with the C preprocessor

std.Build.Module.CSourceLanguage.clangIdentifier

function

Source line 96

The value passed to "-x" CLI flag of Clang.

pub fn clangIdentifier(self: CSourceLanguage) [:0]const u8

Parameters

std.Build.Module.getGraph

function

Source line 566

Given that root is the root Module of a compilation, return all Module in the module graph, including root itself. root is guaranteed to be the first module in the returned slice.

pub fn getGraph(root: *Module) Graph

Parameters

root: *Module

std.Build.Module.Graph

container

Source line 558

Elements of modules and names are matched one-to-one.

Fields

modules: []const *Module
names: []const []const u8

std.Build.Module.Import

container

Source line 237

Fields

name: []const u8
module: *Module

std.Build.Module.IncludeDir

container

Source line 162

Fields

path: LazyPath
path_system: LazyPath
path_after: LazyPath
framework_path: LazyPath
framework_path_system: LazyPath
other_step: *Step.Compile
config_header_step: *Step.ConfigHeader
embed_path: LazyPath

std.Build.Module.init

function

Source line 242

pub fn init( m: *Module, owner: *std.Build, value: union(enum) { options: CreateOptions, existing: *const Module }, ) void

Parameters

m: *Module
owner: *std.Build
value: union(enum) { options: CreateOptions, existing: *const Module }

std.Build.Module.LazyPath

alias

Source line 5

Alias of std.Build.LazyPath

std.Build.Module.linkFramework

function

Source line 374

pub fn linkFramework(m: *Module, name: []const u8, options: LinkFrameworkOptions) void

Parameters

m: *Module
name: []const u8
options: LinkFrameworkOptions

std.Build.Module.LinkFrameworkOptions

container

Source line 173

Fields

needed: bool = false

Causes dynamic libraries to be linked regardless of whether they are actually depended on. When false, dynamic libraries with no referenced symbols will be omitted by the linker.

weak: bool = false

Marks all referenced symbols from this library as weak, meaning that if a same-named symbol is provided by another compilation unit, instead of emitting a "duplicate symbol" error, the linker will resolve all references to the symbol with the strong version.

When the linker encounters two weak symbols, the chosen one is determined by the order compilation units are provided to the linker, priority given to later ones.

std.Build.Module.linkLibrary

function

Source line 459

pub fn linkLibrary(m: *Module, library: *Step.Compile) void

Parameters

m: *Module
library: *Step.Compile

std.Build.Module.linkLibraryOrObject

function

Source line 537

fn linkLibraryOrObject(m: *Module, other: *Step.Compile) void

Parameters

m: *Module
other: *Step.Compile

std.Build.Module.LinkObject

container

Source line 59

Fields

static_path: LazyPath
other_step: *Step.Compile
system_lib: SystemLib
assembly_file: LazyPath
c_source_file: *CSourceFile
c_source_files: *CSourceFiles
win32_resource_file: *RcSourceFile

Deprecated. This functionality will be moved to an external package: https://codeberg.org/ziglang/rc

std.Build.Module.linkSystemLibrary

function

Source line 344

pub fn linkSystemLibrary( m: *Module, name: []const u8, options: LinkSystemLibraryOptions, ) void

Parameters

m: *Module
name: []const u8
options: LinkSystemLibraryOptions

std.Build.Module.LinkSystemLibraryOptions

container

Source line 325

Fields

needed: bool = false

Causes dynamic libraries to be linked regardless of whether they are actually depended on. When false, dynamic libraries with no referenced symbols will be omitted by the linker.

weak: bool = false

Marks all referenced symbols from this library as weak, meaning that if a same-named symbol is provided by another compilation unit, instead of emitting a "duplicate symbol" error, the linker will resolve all references to the symbol with the strong version.

When the linker encounters two weak symbols, the chosen one is determined by the order compilation units are provided to the linker, priority given to later ones.

use_pkg_config: SystemLib.UsePkgConfig = .yes
preferred_link_mode: std.builtin.LinkMode = .dynamic
search_strategy: SystemLib.SearchStrategy = .paths_first

std.Build.Module.Module

alias

Source line 1

Alias of std.Build.Module

std.Build.Module.RcSourceFile

container

Source line 135

Deprecated. This functionality will be moved to an external package: https://codeberg.org/ziglang/rc

Fields

file: LazyPath
flags: []const []const u8 = &.{}

Any option that rc.exe accepts will work here, with the exception of:

Implicitly defined options: /x (ignore the INCLUDE environment variable) /D_DEBUG or /DNDEBUG depending on the optimization mode

include_paths: []const LazyPath = &.{}

Include paths that may or may not exist yet and therefore need to be specified as a LazyPath. Each path will be appended to the flags as /I <resolved path>.

std.Build.Module.RcSourceFile.dupe

function

Source line 153

pub fn dupe(file: RcSourceFile, graph: *const std.Build.Graph) RcSourceFile

Parameters

file: RcSourceFile
graph: *const std.Build.Graph

std.Build.Module.requireKnownTarget

function

Source line 551

fn requireKnownTarget(m: *Module) *const std.Target

Parameters

m: *Module

std.Build.Module.RPath

container

Source line 54

Fields

lazy_path: LazyPath
special: []const u8

std.Build.Module.std

alias

Source line 3

Alias of std

std.Build.Module.Step

alias

Source line 6

Alias of std.Build.Step

std.Build.Module.SystemLib

container

Source line 71

Fields

name: []const u8
needed: bool
weak: bool
use_pkg_config: UsePkgConfig
preferred_link_mode: std.builtin.LinkMode
search_strategy: SystemLib.SearchStrategy

std.Build.Module.SystemLib.SearchStrategy

alias

Source line 80

Alias of std.Build.Configuration.SystemLib.SearchStrategy

std.Build.Module.SystemLib.UsePkgConfig

alias

Source line 79

Alias of std.Build.Configuration.SystemLib.UsePkgConfig

Source code

std/Build/Module.zig

const Module = @This();

const std = @import("std");
const assert = std.debug.assert;
const LazyPath = std.Build.LazyPath;
const Step = std.Build.Step;
const ArrayList = std.ArrayList;

/// The one responsible for creating this module.
owner: *std.Build,
root_source_file: ?LazyPath,
/// The modules that are mapped into this module's import table.
/// Use `addImport` rather than modifying this field directly in order to
/// maintain step dependency edges.
import_table: std.array_hash_map.String(*Module),

resolved_target: ?std.Build.ResolvedTarget = null,
optimize: ?std.builtin.Optimize = null,
dwarf_format: ?std.dwarf.Format,

c_macros: ArrayList([]const u8),
include_dirs: ArrayList(IncludeDir),
lib_paths: ArrayList(LazyPath),
rpaths: ArrayList(RPath),
frameworks: std.array_hash_map.String(LinkFrameworkOptions),
link_objects: ArrayList(LinkObject),

strip: ?bool,
unwind_tables: ?std.builtin.UnwindTables,
single_threaded: ?bool,
stack_protector: ?bool,
stack_check: ?bool,
sanitize_c: ?std.zig.SanitizeC,
sanitize_thread: ?bool,
fuzz: ?bool,
code_model: std.builtin.CodeModel,
valgrind: ?bool,
pic: ?bool,
red_zone: ?bool,
omit_frame_pointer: ?bool,
error_tracing: ?bool,
link_libc: ?bool,
link_libcpp: ?bool,
no_builtin: ?bool,
patchable_function_entry: u16,

/// Symbols to be exported when compiling to WebAssembly.
export_symbol_names: []const []const u8 = &.{},

/// Caches the result of `getGraph` when called multiple times.
/// Use `getGraph` instead of accessing this field directly.
cached_graph: Graph = .{ .modules = &.{}, .names = &.{} },

pub const RPath = union(enum) {
    lazy_path: LazyPath,
    special: []const u8,
};

pub const LinkObject = union(enum) {
    static_path: LazyPath,
    other_step: *Step.Compile,
    system_lib: SystemLib,
    assembly_file: LazyPath,
    c_source_file: *CSourceFile,
    c_source_files: *CSourceFiles,
    /// Deprecated. This functionality will be moved to an external package:
    /// https://codeberg.org/ziglang/rc
    win32_resource_file: *RcSourceFile,
};

pub const SystemLib = struct {
    name: []const u8,
    needed: bool,
    weak: bool,
    use_pkg_config: UsePkgConfig,
    preferred_link_mode: std.builtin.LinkMode,
    search_strategy: SystemLib.SearchStrategy,

    pub const UsePkgConfig = std.Build.Configuration.SystemLib.UsePkgConfig;
    pub const SearchStrategy = std.Build.Configuration.SystemLib.SearchStrategy;
};

pub const CSourceLanguage = enum {
    c,
    cpp,

    objective_c,
    objective_cpp,

    /// Standard assembly
    assembly,
    /// Assembly with the C preprocessor
    assembly_with_preprocessor,

    /// The value passed to "-x" CLI flag of Clang.
    pub fn clangIdentifier(self: CSourceLanguage) [:0]const u8 {
        return switch (self) {
            .c => "c",
            .cpp => "c++",
            .objective_c => "objective-c",
            .objective_cpp => "objective-c++",
            .assembly => "assembler",
            .assembly_with_preprocessor => "assembler-with-cpp",
        };
    }
};

pub const CSourceFiles = struct {
    root: LazyPath,
    /// `files` is relative to `root`, which is
    /// the build root by default
    files: []const []const u8,
    flags: []const []const u8,
    /// By default, determines language of each file individually based on its file extension
    language: ?CSourceLanguage,
};

pub const CSourceFile = struct {
    file: LazyPath,
    flags: []const []const u8 = &.{},
    /// By default, determines language of each file individually based on its file extension
    language: ?CSourceLanguage = null,

    pub fn dupe(file: CSourceFile, graph: *const std.Build.Graph) CSourceFile {
        return .{
            .file = file.file.dupe(graph),
            .flags = graph.dupeStrings(file.flags),
            .language = file.language,
        };
    }
};

/// Deprecated. This functionality will be moved to an external package:
/// https://codeberg.org/ziglang/rc
pub const RcSourceFile = struct {
    file: LazyPath,
    /// Any option that rc.exe accepts will work here, with the exception of:
    /// - `/fo`: The output filename is set by the build system
    /// - `/p`: Only running the preprocessor is not supported in this context
    /// - `/:no-preprocess` (non-standard option): Not supported in this context
    /// - Any MUI-related option
    /// https://learn.microsoft.com/en-us/windows/win32/menurc/using-rc-the-rc-command-line-
    ///
    /// Implicitly defined options:
    ///  /x (ignore the INCLUDE environment variable)
    ///  /D_DEBUG or /DNDEBUG depending on the optimization mode
    flags: []const []const u8 = &.{},
    /// Include paths that may or may not exist yet and therefore need to be
    /// specified as a LazyPath. Each path will be appended to the flags
    /// as `/I <resolved path>`.
    include_paths: []const LazyPath = &.{},

    pub fn dupe(file: RcSourceFile, graph: *const std.Build.Graph) RcSourceFile {
        return .{
            .file = file.file.dupe(graph),
            .flags = graph.dupeStrings(file.flags),
            .include_paths = LazyPath.dupeList(file.include_paths, graph),
        };
    }
};

pub const IncludeDir = union(enum) {
    path: LazyPath,
    path_system: LazyPath,
    path_after: LazyPath,
    framework_path: LazyPath,
    framework_path_system: LazyPath,
    other_step: *Step.Compile,
    config_header_step: *Step.ConfigHeader,
    embed_path: LazyPath,
};

pub const LinkFrameworkOptions = struct {
    /// Causes dynamic libraries to be linked regardless of whether they are
    /// actually depended on. When false, dynamic libraries with no referenced
    /// symbols will be omitted by the linker.
    needed: bool = false,
    /// Marks all referenced symbols from this library as weak, meaning that if
    /// a same-named symbol is provided by another compilation unit, instead of
    /// emitting a "duplicate symbol" error, the linker will resolve all
    /// references to the symbol with the strong version.
    ///
    /// When the linker encounters two weak symbols, the chosen one is
    /// determined by the order compilation units are provided to the linker,
    /// priority given to later ones.
    weak: bool = false,
};

/// Unspecified options here will be inherited from parent `Module` when
/// inserted into an import table.
pub const CreateOptions = struct {
    /// This could either be a generated file, in which case the module
    /// contains exactly one file, or it could be a path to the root source
    /// file of directory of files which constitute the module.
    /// If `null`, it means this module is made up of only `link_objects`.
    root_source_file: ?LazyPath = null,

    /// The table of other modules that this module can access via `@import`.
    /// Imports are allowed to be cyclical, so this table can be added to after
    /// the `Module` is created via `addImport`.
    imports: []const Import = &.{},

    target: ?std.Build.ResolvedTarget = null,
    optimize: ?std.builtin.Optimize = null,

    /// `true` requires a compilation that includes this Module to link libc.
    /// `false` causes a build failure if a compilation that includes this Module would link libc.
    /// `null` neither requires nor prevents libc from being linked.
    link_libc: ?bool = null,
    /// `true` requires a compilation that includes this Module to link libc++.
    /// `false` causes a build failure if a compilation that includes this Module would link libc++.
    /// `null` neither requires nor prevents libc++ from being linked.
    link_libcpp: ?bool = null,
    single_threaded: ?bool = null,
    strip: ?bool = null,
    unwind_tables: ?std.builtin.UnwindTables = null,
    dwarf_format: ?std.dwarf.Format = null,
    code_model: std.builtin.CodeModel = .default,
    stack_protector: ?bool = null,
    stack_check: ?bool = null,
    sanitize_c: ?std.zig.SanitizeC = null,
    sanitize_thread: ?bool = null,
    fuzz: ?bool = null,
    /// Whether to emit machine code that integrates with Valgrind.
    valgrind: ?bool = null,
    /// Position Independent Code
    pic: ?bool = null,
    red_zone: ?bool = null,
    /// Whether to omit the stack frame pointer. Frees up a register and makes it
    /// more difficult to obtain stack traces. Has target-dependent effects.
    omit_frame_pointer: ?bool = null,
    error_tracing: ?bool = null,
    no_builtin: ?bool = null,
    patchable_function_entry: u16 = 0,
};

pub const Import = struct {
    name: []const u8,
    module: *Module,
};

pub fn init(
    m: *Module,
    owner: *std.Build,
    value: union(enum) { options: CreateOptions, existing: *const Module },
) void {
    const graph = owner.graph;
    const arena = graph.arena;

    switch (value) {
        .options => |options| {
            m.* = .{
                .owner = owner,
                .root_source_file = if (options.root_source_file) |lp| lp.dupe(graph) else null,
                .import_table = .empty,
                .resolved_target = options.target,
                .optimize = options.optimize,
                .link_libc = options.link_libc,
                .link_libcpp = options.link_libcpp,
                .dwarf_format = options.dwarf_format,
                .c_macros = .empty,
                .include_dirs = .empty,
                .lib_paths = .empty,
                .rpaths = .empty,
                .frameworks = .empty,
                .link_objects = .empty,
                .strip = options.strip,
                .unwind_tables = options.unwind_tables,
                .single_threaded = options.single_threaded,
                .stack_protector = options.stack_protector,
                .stack_check = options.stack_check,
                .sanitize_c = options.sanitize_c,
                .sanitize_thread = options.sanitize_thread,
                .fuzz = options.fuzz,
                .code_model = options.code_model,
                .valgrind = options.valgrind,
                .pic = options.pic,
                .red_zone = options.red_zone,
                .omit_frame_pointer = options.omit_frame_pointer,
                .error_tracing = options.error_tracing,
                .export_symbol_names = &.{},
                .no_builtin = options.no_builtin,
                .patchable_function_entry = options.patchable_function_entry,
            };

            m.import_table.ensureUnusedCapacity(arena, options.imports.len) catch @panic("OOM");
            for (options.imports) |dep| {
                m.import_table.putAssumeCapacity(dep.name, dep.module);
            }
        },
        .existing => |existing| {
            m.* = existing.*;
        },
    }
}

pub fn create(owner: *std.Build, options: CreateOptions) *Module {
    const graph = owner.graph;
    const arena = graph.arena;
    const m = arena.create(Module) catch @panic("OOM");
    m.init(owner, .{ .options = options });
    return m;
}

/// Adds an existing module to be used with `@import`.
pub fn addImport(m: *Module, name: []const u8, module: *Module) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.import_table.put(arena, graph.dupeString(name), module) catch @panic("OOM");
}

/// Creates a new module and adds it to be used with `@import`.
pub fn addAnonymousImport(m: *Module, name: []const u8, options: CreateOptions) void {
    const module = create(m.owner, options);
    return addImport(m, name, module);
}

/// Converts a set of key-value pairs into a Zig source file, and then inserts it into
/// the Module's import table with the specified name. This makes the options importable
/// via `@import("module_name")`.
pub fn addOptions(m: *Module, module_name: []const u8, options: *Step.Options) void {
    addImport(m, module_name, options.createModule());
}

pub const LinkSystemLibraryOptions = struct {
    /// Causes dynamic libraries to be linked regardless of whether they are
    /// actually depended on. When false, dynamic libraries with no referenced
    /// symbols will be omitted by the linker.
    needed: bool = false,
    /// Marks all referenced symbols from this library as weak, meaning that if
    /// a same-named symbol is provided by another compilation unit, instead of
    /// emitting a "duplicate symbol" error, the linker will resolve all
    /// references to the symbol with the strong version.
    ///
    /// When the linker encounters two weak symbols, the chosen one is
    /// determined by the order compilation units are provided to the linker,
    /// priority given to later ones.
    weak: bool = false,
    use_pkg_config: SystemLib.UsePkgConfig = .yes,
    preferred_link_mode: std.builtin.LinkMode = .dynamic,
    search_strategy: SystemLib.SearchStrategy = .paths_first,
};

pub fn linkSystemLibrary(
    m: *Module,
    name: []const u8,
    options: LinkSystemLibraryOptions,
) void {
    const graph = m.owner.graph;
    const arena = graph.arena;

    const target = m.requireKnownTarget();
    if (std.zig.target.isLibCLibName(target, name)) {
        m.link_libc = true;
        return;
    }
    if (std.zig.target.isLibCxxLibName(target, name)) {
        m.link_libcpp = true;
        return;
    }

    m.link_objects.append(arena, .{
        .system_lib = .{
            .name = graph.dupeString(name),
            .needed = options.needed,
            .weak = options.weak,
            .use_pkg_config = options.use_pkg_config,
            .preferred_link_mode = options.preferred_link_mode,
            .search_strategy = options.search_strategy,
        },
    }) catch @panic("OOM");
}

pub fn linkFramework(m: *Module, name: []const u8, options: LinkFrameworkOptions) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.frameworks.put(arena, graph.dupeString(name), options) catch @panic("OOM");
}

pub const AddCSourceFilesOptions = struct {
    /// When provided, `files` are relative to `root` rather than the
    /// package that owns the `Compile` step.
    root: ?LazyPath = null,
    files: []const []const u8,
    flags: []const []const u8 = &.{},
    /// By default, determines language of each file individually based on its file extension
    language: ?CSourceLanguage = null,
};

/// Handy when you have many non-Zig source files and want them all to have the same flags.
pub fn addCSourceFiles(m: *Module, options: AddCSourceFilesOptions) void {
    const b = m.owner;
    const graph = m.owner.graph;
    const arena = graph.arena;

    for (options.files) |path| {
        if (std.fs.path.isAbsolute(path)) {
            std.debug.panic(
                "file paths added with 'addCSourceFiles' must be relative, found absolute path '{s}'",
                .{path},
            );
        }
    }

    const c_source_files = arena.create(CSourceFiles) catch @panic("OOM");
    c_source_files.* = .{
        .root = options.root orelse b.path(""),
        .files = b.graph.dupeStrings(options.files),
        .flags = b.graph.dupeStrings(options.flags),
        .language = options.language,
    };
    m.link_objects.append(arena, .{ .c_source_files = c_source_files }) catch @panic("OOM");
}

pub fn addCSourceFile(m: *Module, source: CSourceFile) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    const c_source_file = arena.create(CSourceFile) catch @panic("OOM");
    c_source_file.* = source.dupe(graph);
    m.link_objects.append(arena, .{ .c_source_file = c_source_file }) catch @panic("OOM");
}

/// Deprecated. This functionality will be moved to an external package:
/// https://codeberg.org/ziglang/rc
///
/// Resource files must have the extension `.rc`.
/// Can be called regardless of target. The .rc file will be ignored
/// if the target object format does not support embedded resources.
pub fn addWin32ResourceFile(m: *Module, source: RcSourceFile) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    const target = m.requireKnownTarget();
    // Only the PE/COFF format has a Resource Table, so for any other target
    // the resource file is ignored.
    if (target.ofmt != .coff) return;

    const rc_source_file = arena.create(RcSourceFile) catch @panic("OOM");
    rc_source_file.* = source.dupe(graph);
    m.link_objects.append(arena, .{ .win32_resource_file = rc_source_file }) catch @panic("OOM");
}

pub fn addAssemblyFile(m: *Module, source: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.link_objects.append(arena, .{ .assembly_file = source.dupe(graph) }) catch @panic("OOM");
}

pub fn addObjectFile(m: *Module, object: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.link_objects.append(arena, .{ .static_path = object.dupe(graph) }) catch @panic("OOM");
}

pub fn addObject(m: *Module, object: *Step.Compile) void {
    assert(object.kind == .obj or object.kind == .test_obj);
    m.linkLibraryOrObject(object);
}

pub fn linkLibrary(m: *Module, library: *Step.Compile) void {
    assert(library.kind == .lib);
    m.linkLibraryOrObject(library);
}

pub fn addAfterIncludePath(m: *Module, lazy_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .path_after = lazy_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addSystemIncludePath(m: *Module, lazy_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .path_system = lazy_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addIncludePath(m: *Module, lazy_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .path = lazy_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addConfigHeader(m: *Module, config_header: *Step.ConfigHeader) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .config_header_step = config_header }) catch @panic("OOM");
}

pub fn addSystemFrameworkPath(m: *Module, directory_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .framework_path_system = directory_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addFrameworkPath(m: *Module, directory_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .framework_path = directory_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addEmbedPath(m: *Module, lazy_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.include_dirs.append(arena, .{ .embed_path = lazy_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addLibraryPath(m: *Module, directory_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.lib_paths.append(arena, directory_path.dupe(graph)) catch @panic("OOM");
}

pub fn addRPath(m: *Module, directory_path: LazyPath) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.rpaths.append(arena, .{ .lazy_path = directory_path.dupe(graph) }) catch @panic("OOM");
}

pub fn addRPathSpecial(m: *Module, bytes: []const u8) void {
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.rpaths.append(arena, .{ .special = graph.dupeString(bytes) }) catch @panic("OOM");
}

/// Equvialent to the following C code, applied to all C source files owned by
/// this `Module`:
/// ```c
/// #define name value
/// ```
/// `name` and `value` need not live longer than the function call.
pub fn addCMacro(m: *Module, name: []const u8, value: []const u8) void {
    const b = m.owner;
    const graph = m.owner.graph;
    const arena = graph.arena;
    m.c_macros.append(arena, b.fmt("-D{s}={s}", .{ name, value })) catch @panic("OOM");
}

fn linkLibraryOrObject(m: *Module, other: *Step.Compile) void {
    const graph = m.owner.graph;
    const arena = graph.arena;

    _ = other.getEmittedBin(); // Indicate there is a dependency on the outputted binary.

    if (other.rootModuleTarget().os.tag == .windows and other.isDynamicLibrary()) {
        _ = other.getEmittedImplib(); // Indicate dependency on the outputted implib.
    }

    m.link_objects.append(arena, .{ .other_step = other }) catch @panic("OOM");
    m.include_dirs.append(arena, .{ .other_step = other }) catch @panic("OOM");
}

fn requireKnownTarget(m: *Module) *const std.Target {
    const resolved_target = &(m.resolved_target orelse
        @panic("this API requires the Module to be created with a known 'target' field"));
    return &resolved_target.result;
}

/// Elements of `modules` and `names` are matched one-to-one.
pub const Graph = struct {
    modules: []const *Module,
    names: []const []const u8,
};

/// Given that `root` is the root `Module` of a compilation, return all
/// `Module` in the module graph, including `root` itself. `root` is guaranteed
/// to be the first module in the returned slice.
pub fn getGraph(root: *Module) Graph {
    if (root.cached_graph.modules.len != 0) {
        return root.cached_graph;
    }

    const arena = root.owner.graph.arena;

    var modules: std.array_hash_map.Auto(*std.Build.Module, []const u8) = .empty;
    var next_idx: usize = 0;

    modules.putNoClobber(arena, root, "root") catch @panic("OOM");

    while (next_idx < modules.count()) {
        const mod = modules.keys()[next_idx];
        next_idx += 1;
        modules.ensureUnusedCapacity(arena, mod.import_table.count()) catch @panic("OOM");
        for (mod.import_table.keys(), mod.import_table.values()) |import_name, other_mod| {
            modules.putAssumeCapacity(other_mod, import_name);
        }
    }

    const result: Graph = .{
        .modules = modules.keys(),
        .names = modules.values(),
    };
    root.cached_graph = result;
    return result;
}