Metadata

Metadata

Abstract supertype for all metadata types.

MDString

A string metadata node.

MDString(val::String)

Create a new string metadata node from the given Julia string.

convert(String, md::MDString)

Get the string value of the given string metadata node.

MDNode

Abstract supertype for metadata nodes that can have operands.

See also: MDTuple for a concrete subtype.

operands(md::MDNode)

Get the operands of the given metadata node.

MDTuple

A tuple metadata node.

MDNode(vals::Vector) -> MDTuple

Create a new tuple metadata node from the given operands.

Passing nothing as a value will result in a null operand.

LLVM.ValueAsMetadata

Abstract type for values wrapped as metadata, for use in APIs that expect a LLVM.Metadata.

See also: Metadata(::Value) to convert back to a metadata.

Metadata(val::Value)

Wrap the given value as metadata, for use in APIs that expect a LLVM.Metadata.

When the value is already metadata wrapped as a value, this will simply return the original metadata.

LLVM.MetadataAsValue

Metadata wrapped as a regular value, for use in APIs that expect a LLVM.Value.

See also: Value(::Metadata) to convert back to a value.

Value(md::Metadata)

Wrap the given metadata as a value, for use in APIs that expect a LLVM.Value.

When the metadata is already a value wrapped as metadata, this will simply return the original value.

metadata(inst::Instruction)
metadata(inst::GlobalObject)

Iterate over the metadata of the given instruction or global object.

These iterators are mutable, and implement setindex! and delete! to modify the metadata.

NamedMDNode

A named metadata node, which is a collection of metadata nodes with a name.

metadata(mod)

Fetch the module-level named metadata. This can be inspected using a Dict-like interface. Mutation is different: There is no setindex! method, as named metadata is append-only. Instead, fetch the named metadata node using getindex, and push! to it.

name(node::NamedMDNode)

Get the name of the given named metadata node.

operands(node::NamedMDNode)

Get the operands of the given named metadata node.

push!(node::NamedMDNode, val::MDNode)

Add a metadata node to the given named metadata node.

DINode

a tagged DWARF-like metadata node.

tag(node::DINode)

Get the DWARF tag of the given node, or 0 if none. Requires LLVM 17+.

DIBuilder

A builder for constructing debug information metadata.

This object needs to be disposed of using dispose, which also finalizes the debug info. Call finalize! explicitly only if you need to use the finalized debug info (e.g. emit code) before disposing of the builder.

DIBuilder(mod::Module; allow_unresolved::Bool=true)

Create a new debug info builder that emits metadata into mod.

When allow_unresolved is true (the default), the builder collects unresolved metadata nodes attached to the module so that cycles can be resolved during dispose. When false, the builder errors on unresolved nodes instead.

dispose(builder::DIBuilder)

Finalize the debug info and dispose of the builder. Finalization populates the compile unit's enum/retained-type/global/imported-entity/macro arrays, seals each subprogram's retained-nodes list, and resolves remaining cycles. If no compile unit was registered with the builder, or the debug info was already finalized through finalize!, finalization is skipped: DIBuilder::finalize is not idempotent (e.g., re-finalizing accesses already-deleted temporary macro files).

finalize!(builder::DIBuilder)

Resolve any unresolved metadata nodes and mark all compile units finalized. Called automatically by dispose; call explicitly only if the DI-enriched module must be consumed (e.g. for code emission) before the builder is disposed of. Skipped if no compile unit has been registered, or if the debug info has already been finalized.

finalize_subprogram!(builder::DIBuilder, sp::DISubProgram)

Finalize a single subprogram early, sealing its retained-nodes list. After this, no more local variables can be added to sp. A no-op if sp was not tracked by builder (e.g. created elsewhere or already finalized).

Calling this is never required for correctness — dispose / finalize! finalize every tracked subprogram automatically. Use it only when streaming many subprograms through the builder and wanting to release their bookkeeping early.

DILocation

A location in the source code.

line(location::DILocation)

Get the line number of this debug location.

column(location::DILocation)

Get the column number of this debug location.

scope(location::DILocation)

Get the local scope associated with this debug location.

inlined_at(location::DILocation)

Get the "inline at" location associated with this debug location.

DIVariable

Abstract supertype for all variable-like metadata nodes.

DILocalVariable <: DIVariable

A local variable in the source code.

DIGlobalVariable <: DIVariable

A global variable in the source code.

file(var::DIVariable)

Get the file of the given variable.

scope(var::DIVariable)

Get the scope of the given variable.

line(var::DIVariable)

Get the line number of the given variable.

DIScope

Abstract supertype for lexical scopes and types (which are also declaration contexts).

file(scope::DIScope)

Get the metadata of the file associated with a given scope.

name(scope::DIScope)

Get the name of the given scope.

DIFile

A file in the source code.

directory(file::DIFile)

Get the directory of a given file.

filename(file::DIFile)

Get the filename of the given file.

source(file::DIFile)

Get the source of the given file, or nothing if the source is not available.

file!(builder::DIBuilder, filename::AbstractString, directory::AbstractString) -> DIFile

Create a new DIFile describing the given source file.

DILexicalBlock

A lexical block (a nested scope, typically a compound statement) in the source code.

DILexicalBlockFile

A lexical block that changes the current source file, e.g. due to an #include.

lexical_block!(builder::DIBuilder, scope::DIScope, file::DIFile,
              line::Integer, column::Integer) -> DILexicalBlock

Create a new DILexicalBlock describing a nested source scope.

lexical_block_file!(builder::DIBuilder, scope::DIScope, file::DIFile,
                  discriminator::Integer=0) -> DILexicalBlockFile

Create a new DILexicalBlockFile for tracking source-file changes within a lexical scope.

DIModule

A module in the source code (Clang modules / Fortran modules / Swift modules).

dimodule!(builder::DIBuilder, parent_scope::DIScope, name::AbstractString;
          config_macros::AbstractString="", include_path::AbstractString="",
          api_notes_file::AbstractString="") -> DIModule

Create a new DIModule describing a module in the source code.

DINamespace

A namespace in the source code.

namespace!(builder::DIBuilder, parent_scope::DIScope, name::AbstractString;
           export_symbols::Bool=false) -> DINamespace

Create a new DINamespace describing a namespace in the source code.

DIType

Abstract supertype for all type-like metadata nodes.

DIBasicType <: DIType

A primitive type (integer, floating-point, boolean, ...), built with basic_type!.

DIDerivedType <: DIType

A type derived from another type by adding qualifiers, reference/pointer indirection, a typedef name, or by describing a member/field. Built with pointer_type!, typedef_type!, member_type!, and the other qualifier/member factories.

DICompositeType <: DIType

An aggregate type (struct, union, class, array, vector, enumeration, ...). Built with struct_type!, union_type!, array_type!, etc.

DISubroutineType <: DIType

A function/subroutine type, listing the return and parameter types. Built with subroutine_type!.

name(typ::DIType)

Get the name of the given type.

sizeof(typ::DIType)

Get the size in bits of the given type.

offset(typ::DIType)

Get the offset in bits of the given type.

line(typ::DIType)

Get the line number of the given type.

flags(typ::DIType)

Get the flags of the given type.

align(typ::DIType)

Get the alignment in bits of the given type.

DIEnumerator

A single enumerator value in an enumeration type.

DISubrange

A subrange describing one dimension of an array or vector type.

basic_type!(builder::DIBuilder, name::AbstractString, size_in_bits::Integer,
           encoding::Integer; flags=API.LLVMDIFlagZero) -> DIBasicType

Create a new DIBasicType, such as an integer or floating-point type. encoding is a DW_ATE_* value (see the DWARF standard).

unspecified_type!(builder::DIBuilder, name::AbstractString) -> DIBasicType

Create a new unspecified type (DW_TAG_unspecified_type), e.g. a C++ decltype(nullptr).

nullptr_type!(builder::DIBuilder) -> DIBasicType

Create a new type representing a null pointer.

pointer_type!(builder::DIBuilder, pointee_type::DIType, size_in_bits::Integer;
             align_in_bits::Integer=0, address_space::Integer=0,
             name::AbstractString="") -> DIDerivedType

Create a new pointer type.

reference_type!(builder::DIBuilder, tag::Integer, type::DIType) -> DIDerivedType

Create a new reference type (C++ T& / T&&), with the given DWARF tag (e.g. DW_TAG_reference_type or DW_TAG_rvalue_reference_type).

lvalue_reference_type!(builder::DIBuilder, type::DIType) -> DIDerivedType

Create a C++ T& reference type. Shorthand for reference_type!(builder, DW_TAG_reference_type, type).

rvalue_reference_type!(builder::DIBuilder, type::DIType) -> DIDerivedType

Create a C++ T&& rvalue-reference type. Shorthand for reference_type!(builder, DW_TAG_rvalue_reference_type, type).

typedef_type!(builder::DIBuilder, type::DIType, name::AbstractString,
             file::DIFile, line::Integer, scope::DIScope;
             align_in_bits::Integer=0) -> DIDerivedType

Create a new typedef type.

qualified_type!(builder::DIBuilder, tag::Integer, type::DIType) -> DIDerivedType

Create a new qualified type, such as const T (DW_TAG_const_type) or volatile T (DW_TAG_volatile_type). See also the named convenience wrappers const_type! and volatile_type!.

const_type!(builder::DIBuilder, type::DIType) -> DIDerivedType

Create a const-qualified type. Shorthand for qualified_type!(builder, DW_TAG_const_type, type).

volatile_type!(builder::DIBuilder, type::DIType) -> DIDerivedType

Create a volatile-qualified type. Shorthand for qualified_type!(builder, DW_TAG_volatile_type, type).

artificial_type!(builder::DIBuilder, type::DIType) -> DIType

Create a new artificial type (DI_FLAG_ARTIFICIAL), e.g. an implicit this. The concrete subtype matches the input (e.g. a DIBasicType stays a DIBasicType).

object_pointer_type!(builder::DIBuilder, type::DIType;
                    implicit::Bool=true) -> DIType

Create a new type identifying an object pointer (DI_FLAG_OBJECT_POINTER). The concrete subtype matches the input. On LLVM 20+ an implicit::Bool keyword is accepted: when true (the default, matching LLVM ≤ 19 behavior) the clone also sets DI_FLAG_ARTIFICIAL.

member_type!(builder::DIBuilder, scope::DIScope, name::AbstractString,
            file::DIFile, line::Integer, size_in_bits::Integer,
            align_in_bits::Integer, offset_in_bits::Integer,
            type::DIType; flags=API.LLVMDIFlagZero) -> DIDerivedType

Create a new member (field) of a composite type.

bitfield_member_type!(builder::DIBuilder, scope::DIScope, name::AbstractString,
                    file::DIFile, line::Integer, size_in_bits::Integer,
                    offset_in_bits::Integer, storage_offset_in_bits::Integer,
                    type::DIType; flags=API.LLVMDIFlagZero) -> DIDerivedType

Create a new bit-field member of a composite type.

static_member_type!(builder::DIBuilder, scope::DIScope, name::AbstractString,
                  file::DIFile, line::Integer, type::DIType,
                  constant_val::Constant;
                  flags=API.LLVMDIFlagZero,
                  align_in_bits::Integer=0) -> DIDerivedType

Create a new static member of a composite type. constant_val is required: the underlying C entry point unconditionally cast<Constant>s it and crashes on null.

member_pointer_type!(builder::DIBuilder, pointee_type::DIType, class_type::DIType,
                   size_in_bits::Integer;
                   align_in_bits::Integer=0,
                   flags=API.LLVMDIFlagZero) -> DIDerivedType

Create a new pointer-to-member type for C++.

inheritance!(builder::DIBuilder, derived::DIType, base::DIType,
             base_offset::Integer, vbptr_offset::Integer=0;
             flags=API.LLVMDIFlagZero) -> DIDerivedType

Create a new inheritance relationship from derived to base.

struct_type!(builder::DIBuilder, scope::DIScope, name::AbstractString,
            file::DIFile, line::Integer, size_in_bits::Integer,
            align_in_bits::Integer, elements::Vector{<:Metadata};
            flags=API.LLVMDIFlagZero, derived_from=nothing,
            runtime_lang::Integer=0, vtable_holder=nothing,
            unique_id::AbstractString="") -> DICompositeType

Create a new struct type.

union_type!(builder::DIBuilder, scope::DIScope, name::AbstractString,
           file::DIFile, line::Integer, size_in_bits::Integer,
           align_in_bits::Integer, elements::Vector{<:Metadata};
           flags=API.LLVMDIFlagZero, runtime_lang::Integer=0,
           unique_id::AbstractString="") -> DICompositeType

Create a new union type.

class_type!(builder::DIBuilder, scope::DIScope, name::AbstractString,
           file::DIFile, line::Integer, size_in_bits::Integer,
           align_in_bits::Integer, offset_in_bits::Integer,
           elements::Vector{<:Metadata};
           flags=API.LLVMDIFlagZero, derived_from=nothing,
           vtable_holder=nothing, template_params=nothing,
           unique_id::AbstractString="") -> DICompositeType

Create a new C++ class type.

array_type!(builder::DIBuilder, size::Integer, align_in_bits::Integer,
           element_type::DIType, subscripts::Vector{<:Metadata}) -> DICompositeType

Create a new array type. Subscripts are typically built with get_or_create_subrange!.

vector_type!(builder::DIBuilder, size::Integer, align_in_bits::Integer,
            element_type::DIType, subscripts::Vector{<:Metadata}) -> DICompositeType

Create a new vector type. Subscripts are typically built with get_or_create_subrange!.

enumerator!(builder::DIBuilder, name::AbstractString, value::Integer;
            unsigned::Bool=false) -> DIEnumerator

Create a new enumerator for use inside an enumeration type.

enumeration_type!(builder::DIBuilder, scope::DIScope, name::AbstractString,
                 file::DIFile, line::Integer, size_in_bits::Integer,
                 align_in_bits::Integer, elements::Vector{<:Metadata};
                 class_ty=nothing) -> DICompositeType

Create a new enumeration type. elements should be a vector of DIEnumerator metadata nodes.

forward_decl!(builder::DIBuilder, tag::Integer, name::AbstractString,
             scope::DIScope, file::DIFile, line::Integer;
             runtime_lang::Integer=0, size_in_bits::Integer=0,
             align_in_bits::Integer=0,
             unique_id::AbstractString="") -> DICompositeType

Create a new forward declaration to a composite type.

replaceable_composite_type!(builder::DIBuilder, tag::Integer,
                          name::AbstractString, scope::DIScope,
                          file::DIFile, line::Integer;
                          runtime_lang::Integer=0, size_in_bits::Integer=0,
                          align_in_bits::Integer=0,
                          flags=API.LLVMDIFlagZero,
                          unique_id::AbstractString="") -> DICompositeType

Create a new replaceable composite type forward declaration.

get_or_create_subrange!(builder::DIBuilder, lower_bound::Integer, count::Integer)

Get or create a subrange metadata node, describing one dimension of an array or vector type.

subroutine_type!(builder::DIBuilder, file::DIFile,
                return_type::Union{DIType,Nothing},
                parameter_types::Vector{<:Metadata}=Metadata[];
                flags=API.LLVMDIFlagZero) -> DISubroutineType

Create a new subroutine type with the given return and parameter types. Pass nothing for return_type to describe a void-returning subroutine.

get_or_create_array!(builder::DIBuilder, elements::Vector{<:Metadata})

Get or create a generic metadata array node, used for lists such as elements fields of composite types.

get_or_create_type_array!(builder::DIBuilder, types::Vector{<:Metadata})

Get or create a metadata node for a type array, used for e.g. template parameter lists.

DIObjCProperty

An Objective-C @property descriptor.

objc_ivar!(builder::DIBuilder, name::AbstractString, file::DIFile,
          line::Integer, size_in_bits::Integer, align_in_bits::Integer,
          offset_in_bits::Integer, type::DIType, property_node::Metadata;
          flags=API.LLVMDIFlagZero) -> DIDerivedType

Create a new Objective-C instance variable.

objc_property!(builder::DIBuilder, name::AbstractString, file::DIFile,
              line::Integer, getter::AbstractString, setter::AbstractString,
              attributes::Integer, type::DIType) -> DIObjCProperty

Create a new Objective-C @property descriptor.

DISubProgram

A subprogram in the source code.

line(subprogram::DISubProgram)

Get the line number of the given subprogram.

subprogram!(builder::DIBuilder, scope::DIScope, name::AbstractString,
            file::DIFile, line::Integer, type::DISubroutineType;
            linkage_name::AbstractString="", scope_line::Integer=line,
            is_local_to_unit::Bool=false, is_definition::Bool=true,
            flags=API.LLVMDIFlagZero,
            is_optimized::Bool=false) -> DISubProgram

Create a new DISubProgram describing a function. When linkage_name is empty, LLVM falls back to name. scope_line defaults to the function's line, which is the usual case.

auto_variable!(builder::DIBuilder, scope::DIScope, name::AbstractString,
              file::DIFile, line::Integer, type::DIType;
              always_preserve::Bool=false, flags=API.LLVMDIFlagZero,
              align_in_bits::Integer=0) -> DILocalVariable

Create a new local variable descriptor (for a compiler-introduced automatic variable).

parameter_variable!(builder::DIBuilder, scope::DIScope, name::AbstractString,
                   arg_no::Integer, file::DIFile, line::Integer, type::DIType;
                   always_preserve::Bool=false,
                   flags=API.LLVMDIFlagZero) -> DILocalVariable

Create a new descriptor for a function parameter variable. arg_no is the 1-based parameter index.

DIExpression

A DWARF expression that modifies how a variable's value is expressed at runtime.

DIGlobalVariableExpression

A pairing of a DIGlobalVariable and its associated DIExpression.

expression!(builder::DIBuilder,
            addr::Vector{UInt64}=UInt64[]) -> DIExpression

Create a new DIExpression from the given array of opcodes (encoding a DWARF expression such as DW_OP_plus_uconst).

constant_value_expression!(builder::DIBuilder, value::Integer) -> DIExpression

Create a new DIExpression representing a single constant value.

variable(gve::DIGlobalVariableExpression)

Get the debug info global variable associated with the given expression.

expression(gve::DIGlobalVariableExpression)

Get the debug info expression associated with the given global-variable pair.

global_variable_expression!(builder::DIBuilder, scope::DIScope,
                          name::AbstractString, linkage::AbstractString,
                          file::DIFile, line::Integer, type::DIType,
                          local_to_unit::Bool, expression::DIExpression;
                          declaration=nothing,
                          align_in_bits::Integer=0) -> DIGlobalVariableExpression

Create a new global variable descriptor paired with a DWARF expression.

temp_global_variable_fwd_decl!(builder::DIBuilder, scope::DIScope,
                           name::AbstractString, linkage::AbstractString,
                           file::DIFile, line::Integer, type::DIType,
                           local_to_unit::Bool;
                           declaration=nothing,
                           align_in_bits::Integer=0) -> DIGlobalVariable

Create a new temporary forward declaration for a global variable.

DIImportedEntity

An imported entity, such as a C++ using declaration or module import.

imported_module_from_namespace!(builder::DIBuilder, scope::DIScope,
                             ns::DINamespace, file::DIFile,
                             line::Integer) -> DIImportedEntity

Create a new DIImportedEntity from a namespace.

imported_module_from_alias!(builder::DIBuilder, scope::DIScope,
                         imported::DIImportedEntity, file::DIFile,
                         line::Integer,
                         elements::Vector{<:Metadata}=Metadata[]) -> DIImportedEntity

Create a new DIImportedEntity from an alias.

imported_module_from_module!(builder::DIBuilder, scope::DIScope,
                          mod::DIModule, file::DIFile, line::Integer,
                          elements::Vector{<:Metadata}=Metadata[]) -> DIImportedEntity

Create a new DIImportedEntity from a module.

imported_declaration!(builder::DIBuilder, scope::DIScope, decl::Metadata,
                    file::DIFile, line::Integer, name::AbstractString,
                    elements::Vector{<:Metadata}=Metadata[]) -> DIImportedEntity

Create a new DIImportedEntity from a declaration.

DIMacro

A single preprocessor macro definition or undefinition.

DIMacroFile

A collection of macro records corresponding to a single source file.

macro!(builder::DIBuilder, parent_macrofile::Union{DIMacroFile,Nothing},
       line::Integer, record_type, name::AbstractString,
       value::AbstractString) -> DIMacro

Create a new DIMacro. record_type is a LLVMDWARFMacinfoRecordType value (e.g. LLVM.API.LLVMDWARFMacinfoRecordTypeDefine).

temp_macro_file!(builder::DIBuilder,
               parent_macrofile::Union{DIMacroFile,Nothing},
               line::Integer, file::DIFile) -> DIMacroFile

Create a new (temporary) DIMacroFile.

declare_before!(builder::DIBuilder, storage::Value, var::DILocalVariable,
                expr::DIExpression, debugloc::DILocation,
                instr::Instruction)

Insert a new dbg-declare describing storage as the runtime location of var, immediately before instr. Returns a DbgRecord on LLVM ≥ 19, or the legacy llvm.dbg.declare call Instruction on LLVM < 19.

declare_at_end!(builder::DIBuilder, storage::Value, var::DILocalVariable,
                expr::DIExpression, debugloc::DILocation,
                block::BasicBlock)

Insert a new dbg-declare at the end of block. Returns a DbgRecord on LLVM ≥ 19, or the legacy llvm.dbg.declare call Instruction on LLVM < 19.

value_before!(builder::DIBuilder, val::Value, var::DILocalVariable,
              expr::DIExpression, debugloc::DILocation,
              instr::Instruction)

Insert a new dbg-value describing val as the value of var, immediately before instr. Returns a DbgRecord on LLVM ≥ 19, or the legacy llvm.dbg.value call Instruction on LLVM < 19.

value_at_end!(builder::DIBuilder, val::Value, var::DILocalVariable,
              expr::DIExpression, debugloc::DILocation,
              block::BasicBlock)

Insert a new dbg-value at the end of block. Returns a DbgRecord on LLVM ≥ 19, or the legacy llvm.dbg.value call Instruction on LLVM < 19.

debuglocation(inst::Instruction) -> Union{DILocation,Nothing}

Get the debug location attached to the given instruction, or nothing.

debuglocation!(inst::Instruction, loc::DILocation)

Set the debug location of the given instruction.

debuglocation!(inst::Instruction)

Clear the debug location of the given instruction.

DICompileUnit

A compilation unit in the source code.

compile_unit!(builder::DIBuilder, lang, file::DIFile, producer::AbstractString;
             optimized::Bool=true, cmdline::AbstractString="",
             runtime_version::Integer=0,
             split_name::Union{AbstractString,Nothing}=nothing,
             emission_kind=API.LLVMDWARFEmissionFull,
             dwo_id::Integer=0,
             split_debug_inlining::Bool=true,
             debug_info_for_profiling::Bool=false,
             sysroot::AbstractString="", sdk::AbstractString="") -> DICompileUnit

Create a new DICompileUnit. lang is a LLVMDWARFSourceLanguage value (e.g. LLVM.API.LLVMDWARFSourceLanguageJulia). cmdline is a command-line string embedded verbatim in the emitted debug info.

temporary_mdnode(operands::Vector{<:Metadata}=Metadata[]) -> MDNode

Create a temporary metadata node in the task-local context with the given operands. Temporary nodes are useful for constructing cycles and must be either replaced via replace_uses! or disposed of via dispose_temporary.

dispose_temporary(md::Metadata)

Dispose of a temporary metadata node returned by temporary_mdnode.

replace_uses!(temp::Metadata, replacement::Metadata)

Replace all uses of temporary metadata temp with replacement, and dispose of temp. Method on the existing replace_uses! for Value.

DEBUG_METADATA_VERSION()

The current debug info version number, as supported by LLVM.

debug_metadata_version(mod::Module)

Get the debug info version number emitted in the given module, or 0 if none is attached.

strip_debuginfo!(mod::Module)

Strip the debug information from the given module.

subprogram(func::Function) -> DISubProgram

Get the subprogram of the given function, or nothing if the function has no subprogram.

subprogram!(builder::DIBuilder, scope::DIScope, name::AbstractString,
            file::DIFile, line::Integer, type::DISubroutineType;
            linkage_name::AbstractString="", scope_line::Integer=line,
            is_local_to_unit::Bool=false, is_definition::Bool=true,
            flags=API.LLVMDIFlagZero,
            is_optimized::Bool=false) -> DISubProgram

Create a new DISubProgram describing a function. When linkage_name is empty, LLVM falls back to name. scope_line defaults to the function's line, which is the usual case.

subprogram!(func::Function, sp::DISubProgram)

Set the subprogram of the given function.