GitHub

Metadata

LLVM.MDString — Method
MDString(val::AbstractString)

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

source
Core.String — Method
String(md::MDString)

Get the string value of the given string metadata node.

source
LLVM.MDNode — Type
MDNode

Abstract supertype for metadata nodes that can have operands.

See also: MDTuple for a concrete subtype.

Properties

md.operands

The operands of the metadata node, as a view of the node that supports indexing and iteration. Null operands are represented by nothing.

The view is mutable: assigning an operand, md.operands[i] = new, replaces it in place. LLVM keeps uniqued nodes (i.e., nodes that are neither distinct nor temporary) unique, so if the change makes the node identical to an existing one, the node is made distinct instead. Nodes that refer to temporary nodes are replaced by that existing node and deleted.

source
LLVM.MDTuple — Method
MDTuple(elements::AbstractVector) -> MDTuple

Create a new tuple metadata node with the given elements as its operands, or get the existing one, in the task-local context.

Passing nothing as an element will result in a null operand.

source
LLVM.MDNode — Method
MDNode(r::ConstantRange) -> MDTuple

Create !range metadata for the range r, in the task-local context. The range must not be empty or full, which !range metadata can't represent. Attach it to an instruction using inst.metadata[LLVM.MD_range] = MDNode(r).

source

Temporary nodes

LLVM.TemporaryMDNode — Type
TemporaryMDNode{T<:MDNode}

A temporary metadata node: a placeholder that other metadata can refer to before the node it stands for can be created, e.g., to create metadata that refers to itself.

The handle owns the temporary node, which needs to be replaced with replace_temporary!, or disposed of with dispose, which replaces its uses with null operands. Either one consumes the handle, after which disposing of it again does nothing, so the handle can be disposed of with @dispose or the do-block form of the constructor even if it was replaced.

Properties

temp.node

The temporary node, a T, for use as an operand of other metadata. Throws an ArgumentError once the handle has been consumed, which also invalidates the nodes that were obtained from it before.

source
LLVM.TemporaryMDNode — Method
TemporaryMDNode(operands=Metadata[]) -> TemporaryMDNode{MDTuple}
TemporaryMDNode(f::Function, operands=Metadata[])

Create a temporary tuple node with the given operands, in the task-local context. Passing nothing as an operand results in a null operand.

The do-block form calls f with the handle and disposes of it afterwards, unless f replaced it, and returns the result of f:

node = TemporaryMDNode() do temp
    replace_temporary!(temp, MDNode([temp.node, MDString("loop")]))
end
source
LLVM.replace_temporary! — Function
replace_temporary!(temp::TemporaryMDNode, replacement::Metadata) -> replacement

Replace every use of the temporary node temp with replacement, and delete the temporary node, consuming the handle.

A uniqued node that used temp can become identical to an existing node, in which case LLVM replaces it by that node and deletes it, invalidating it.

source
LLVM.dispose — Method
dispose(temp::TemporaryMDNode)

Delete the temporary node temp, replacing its uses with null operands, unless the handle has already been consumed.

source

Metadata <-> Value

LLVM.Metadata — Method
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.

source
LLVM.Value — Method
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.

source

Inspecting and attaching

LLVM.NamedMDNode — Type
NamedMDNode

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

Properties

node.name

The name of the named metadata node.

node.operands

The operands of the named metadata node, as a view of the node that supports indexing and iteration. The view is mutable, and supports:

  • push!(node.operands, md::MDNode): append an operand;

  • node.operands[i] = md::MDNode: replace an operand;

  • empty!(node.operands): remove all operands.

    node.next node.prev

The next or previous named metadata node in the module, or nothing if there is none.

source
LLVM.MDKind — Type
MDKind
MDKind(name::AbstractString; context=context())

The kinds of metadata, which index the metadata of instructions and global objects. The kinds that LLVM knows about have a fixed value, like MD_dbg (for !dbg), MD_tbaa or MD_invariant_load, while the kinds of other names are specific to a context, and can be looked up by name (in the active context by default).

Instead of a kind, the metadata of instructions and global objects can also be indexed by the name of the kind, like inst.metadata["tbaa"], which is looked up in the context of the instruction or global object.

source
LLVM.add_metadata! — Function
add_metadata!(obj::LLVM.GlobalObject, kind, node::MDNode)

Attach metadata to a global object, keeping the attachments of the same kind that it already has (unlike assigning to obj.metadata[kind], which replaces them). Global objects can have several attachments of one kind, e.g., a global variable that is described by several !dbg expressions. The kind can be an MDKind or the name of the kind. Returns obj.

source
LLVM.drop_unknown_metadata! — Function
drop_unknown_metadata!(inst::Instruction, known=())

Drop the metadata of an instruction, except for its debug location and other debug metadata, and the metadata of the known kinds (metadata kinds or their names), using LLVM's Instruction::dropUnknownNonDebugMetadata. Passes do this when they move an instruction to where metadata that depends on the instruction's original position (e.g., !range or !nonnull on a load that a condition guarded) may not hold anymore.

source
LLVM.copy_metadata! — Function
copy_metadata!(dest::Instruction, src::Instruction, kinds=())

Copy the metadata of src, including its debug location, to dest, e.g., when replacing an instruction by a new one. If kinds (metadata kinds or their names) are given, only the metadata of those kinds is copied, and the debug location only if they include MD_dbg. Metadata of dest is overwritten by that of src, but kept for kinds that src doesn't have.

This uses LLVM's Instruction::copyMetadata, so it follows that function's handling of the debug location: if src has none, LLVM 21 and later keep the debug location of dest, while earlier versions remove it, unless src has no metadata at all.

source

Debug information

LLVM.DINode — Type
DINode

a tagged DWARF-like metadata node.

Properties

node.tag

The DWARF tag of the node, or 0 if it has none. Requires LLVM 17+.

The properties of MDNode are available too.

source

Builder

LLVM.DIBuilder — Type
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.

The scope of declarations (types, subprograms, global variables, namespaces, modules and imported entities) can be nothing, for a declaration at the top level. Local variables, labels, lexical blocks and locations require a DILocalScope.

source
LLVM.DIBuilder — Method
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.

source
LLVM.dispose — Method
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).

source
LLVM.finalize! — Method
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.

source
LLVM.finalize_subprogram! — Function
finalize_subprogram!(builder::DIBuilder, sp::DISubprogram)

Materialize the retained nodes currently tracked for sp. Call this after adding its local variables if finalizing it early. dispose and finalize! finalize tracked subprograms automatically.

source

Location information

LLVM.DILocation — Type
DILocation

A location in the source code.

Properties

loc.line

The line number of the debug location, or -1 if unknown.

loc.column

The column number of the debug location.

loc.scope

The local scope of the debug location, a DILocalScope.

loc.inlined_at

The location that the code at this debug location has been inlined at, or nothing if it hasn't been inlined.

The properties of MDNode are available too.

source

Variables

LLVM.DIVariable — Type
DIVariable

Abstract supertype for all variable-like metadata nodes.

Properties

var.file

The file in which the variable is declared, or nothing if unknown.

var.scope

The scope of the variable, or nothing if unknown. The scope of a local variable is a DILocalScope.

var.line

The line number at which the variable is declared, or -1 if unknown.

The properties of DINode and MDNode are available too.

source

Scopes

LLVM.DIScope — Type
DIScope

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

Properties

scope.file

The file associated with the scope, or nothing if it has none.

scope.name

The name of the scope, or nothing if it has none.

The properties of DINode and MDNode are available too.

source

File

LLVM.DIFile — Type
DIFile

A file in the source code.

Properties

file.directory

The directory of the file.

file.filename

The name of the file.

file.source

The source code of the file, or nothing if it is not available.

The properties of DIScope, DINode and MDNode are available too.

source
LLVM.file! — Function
file!(builder::DIBuilder, filename::AbstractString, directory::AbstractString) -> DIFile

Create a new DIFile describing the given source file.

source

Lexical Block

LLVM.DILexicalBlock — Type
DILexicalBlock

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

source
LLVM.lexical_block! — Function
lexical_block!(builder::DIBuilder, scope::DILocalScope, file::DIFile,
              line::Integer, column::Integer) -> DILexicalBlock

Create a new DILexicalBlock describing a nested source scope.

source
LLVM.lexical_block_file! — Function
lexical_block_file!(builder::DIBuilder, scope::DILocalScope, file::DIFile;
                  discriminator::Integer=0) -> DILexicalBlockFile

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

source

Module

LLVM.DIModule — Type
DIModule

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

source
LLVM.dimodule! — Function
dimodule!(builder::DIBuilder, parent_scope::Union{DIScope,Nothing}, name::AbstractString;
          config_macros::AbstractString="", include_path::AbstractString="",
          api_notes_file::AbstractString="") -> DIModule

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

source

Namespace

LLVM.namespace! — Function
namespace!(builder::DIBuilder, parent_scope::Union{DIScope,Nothing}, name::AbstractString;
           export_symbols::Bool=false) -> DINamespace

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

source

Type

LLVM.DIType — Type
DIType

Abstract supertype for all type-like metadata nodes.

Properties

typ.name

The name of the type, or nothing if it has none.

typ.size_in_bits

The size in bits of the type.

typ.offset_in_bits

The offset in bits of the type, e.g., of a member within its structure.

typ.line

The line number at which the type is declared, or -1 if unknown.

typ.flags

The flags of the type, as an LLVM.API.LLVMDIFlags bitmask.

typ.align_in_bits

The alignment in bits of the type, or 0 if it has none.

The properties of DIScope, DINode and MDNode are available too.

source

Properties

Built-in factories for primitive types:

LLVM.basic_type! — Function
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).

source
LLVM.unspecified_type! — Function
unspecified_type!(builder::DIBuilder, name::AbstractString) -> DIBasicType

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

source
LLVM.nullptr_type! — Function
nullptr_type!(builder::DIBuilder) -> DIBasicType

Create a new type representing a null pointer.

source

Derived types (pointers, qualifiers, members, inheritance, ...):

LLVM.pointer_type! — Function
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.

source
LLVM.reference_type! — Function
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).

source
LLVM.lvalue_reference_type! — Function
lvalue_reference_type!(builder::DIBuilder, type::DIType) -> DIDerivedType

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

source
LLVM.rvalue_reference_type! — Function
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).

source
LLVM.typedef_type! — Function
typedef_type!(builder::DIBuilder, type::DIType, name::AbstractString,
             file::DIFile, line::Integer, scope::Union{DIScope,Nothing};
             align_in_bits::Integer=0) -> DIDerivedType

Create a new typedef type.

source
LLVM.qualified_type! — Function
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!.

source
LLVM.const_type! — Function
const_type!(builder::DIBuilder, type::DIType) -> DIDerivedType

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

source
LLVM.volatile_type! — Function
volatile_type!(builder::DIBuilder, type::DIType) -> DIDerivedType

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

source
LLVM.artificial_type! — Function
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).

source
LLVM.object_pointer_type! — Function
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. When implicit is true (the default, and the only behavior before LLVM 20) the clone also sets DI_FLAG_ARTIFICIAL.

source
LLVM.member_type! — Function
member_type!(builder::DIBuilder, scope::Union{DIScope,Nothing}, 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.

source
LLVM.bitfield_member_type! — Function
bitfield_member_type!(builder::DIBuilder, scope::Union{DIScope,Nothing}, 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.

source
LLVM.static_member_type! — Function
static_member_type!(builder::DIBuilder, scope::Union{DIScope,Nothing}, 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.

source
LLVM.member_pointer_type! — Function
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++.

source
LLVM.inheritance! — Function
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.

source

Composite types:

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

Create a new struct type.

source
LLVM.union_type! — Function
union_type!(builder::DIBuilder, scope::Union{DIScope,Nothing}, name::AbstractString,
           file::DIFile, line::Integer, size_in_bits::Integer,
           align_in_bits::Integer, elements::AbstractVector;
           flags=API.LLVMDIFlagZero, runtime_lang::Integer=0,
           unique_id::AbstractString="") -> DICompositeType

Create a new union type.

source
LLVM.class_type! — Function
class_type!(builder::DIBuilder, scope::Union{DIScope,Nothing}, name::AbstractString,
           file::DIFile, line::Integer, size_in_bits::Integer,
           align_in_bits::Integer, offset_in_bits::Integer,
           elements::AbstractVector;
           flags=API.LLVMDIFlagZero, derived_from=nothing,
           vtable_holder=nothing, template_params=nothing,
           unique_id::AbstractString="") -> DICompositeType

Create a new C++ class type.

source
LLVM.array_type! — Function
array_type!(builder::DIBuilder, size_in_bits::Integer, align_in_bits::Integer,
           element_type::DIType, subscripts::AbstractVector) -> DICompositeType

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

source
LLVM.vector_type! — Function
vector_type!(builder::DIBuilder, size_in_bits::Integer, align_in_bits::Integer,
            element_type::DIType, subscripts::AbstractVector) -> DICompositeType

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

source
LLVM.enumerator! — Function
enumerator!(builder::DIBuilder, name::AbstractString, value::Integer;
            unsigned::Bool=false, size_in_bits::Integer=64) -> DIEnumerator

Create a new enumerator for use inside an enumeration type. The value is interpreted as a signed or unsigned integer of size_in_bits bits, and must fit in it. Sizes other than 64 bits require LLVM 21+.

source
LLVM.enumeration_type! — Function
enumeration_type!(builder::DIBuilder, scope::Union{DIScope,Nothing}, name::AbstractString,
                 file::DIFile, line::Integer, size_in_bits::Integer,
                 align_in_bits::Integer, elements::AbstractVector;
                 underlying_type=nothing) -> DICompositeType

Create a new enumeration type. elements should be a vector of DIEnumerator metadata nodes, and underlying_type is the integer type of the enumeration, if it has one.

source
LLVM.forward_decl! — Function
forward_decl!(builder::DIBuilder, tag::Integer, name::AbstractString,
             scope::Union{DIScope,Nothing}, 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.

source
LLVM.replaceable_composite_type! — Function
replaceable_composite_type!(builder::DIBuilder, tag::Integer,
                          name::AbstractString, scope::Union{DIScope,Nothing},
                          file::DIFile, line::Integer;
                          runtime_lang::Integer=0, size_in_bits::Integer=0,
                          align_in_bits::Integer=0,
                          flags=API.LLVMDIFlagZero,
                          unique_id::AbstractString="")
    -> TemporaryMDNode{DICompositeType}

Create a temporary composite type, a placeholder for a type that refers to itself, e.g., through a pointer to it. Build the complete type with the temporary type as a placeholder, and then replace it with replace_temporary!, before the builder is finalized:

fwd = replaceable_composite_type!(dib, DW_TAG_structure_type, "Node", nothing, file, 1)
next = member_type!(dib, nothing, "next", file, 2, 64, 64, 0, pointer_type!(dib, fwd.node, 64))
node = struct_type!(dib, nothing, "Node", file, 1, 64, 64, [next])
replace_temporary!(fwd, node)
source
LLVM.replace_arrays! — Function
replace_arrays!(builder::DIBuilder, T::DICompositeType,
               elements::AbstractVector) -> DICompositeType

Replace the elements array of the given composite type T, and return the resulting type. Use the returned type instead of T, as LLVM can replace T with an existing, identical type. Requires LLVM 21+.

source
LLVM.subrange! — Function
subrange!(builder::DIBuilder, lower_bound::Integer, count::Integer) -> DISubrange

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

source
LLVM.subrange_type! — Function
subrange_type!(builder::DIBuilder, scope::Union{DIScope,Nothing}, name::AbstractString,
              file::DIFile, line::Integer, size_in_bits::Integer,
              align_in_bits::Integer, base_type::DIType;
              flags=API.LLVMDIFlagZero,
              lower_bound=nothing, upper_bound=nothing,
              stride=nothing, bias=nothing) -> DISubrangeType

Create a new subrange type. Requires LLVM 21+.

source
LLVM.set_type! — Function
set_type!(builder::DIBuilder, scope::Union{DIScope,Nothing}, name::AbstractString,
         file::DIFile, line::Integer, size_in_bits::Integer,
         align_in_bits::Integer, base_type::DIType) -> DIDerivedType

Create a new set type (DW_TAG_set_type). Requires LLVM 21+.

source
LLVM.dynamic_array_type! — Function
dynamic_array_type!(builder::DIBuilder, scope::Union{DIScope,Nothing}, name::AbstractString,
                  file::DIFile, line::Integer, size_in_bits::Integer,
                  align_in_bits::Integer, element_type::DIType,
                  subscripts::AbstractVector;
                  data_location=nothing, associated=nothing,
                  allocated=nothing, rank=nothing,
                  bit_stride=nothing) -> DICompositeType

Create a new dynamic array type (Fortran assumed-shape/deferred-shape arrays). Requires LLVM 21+.

source

Subroutine types:

LLVM.subroutine_type! — Function
subroutine_type!(builder::DIBuilder, file::DIFile,
                return_type::Union{DIType,Nothing},
                parameter_types::AbstractVector=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, and as the last parameter type of a variadic subroutine. The parameter types must be DITypes or nothing.

source

Objective-C:

LLVM.objc_ivar! — Function
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.

source
LLVM.objc_property! — Function
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.

source

Subprogram

LLVM.DISubprogram — Type
DISubprogram <: DILocalScope

A subprogram (a function) in the source code.

Properties

sp.line

The line number of the subprogram, or -1 if unknown.

sp.linkage_name

The linkage name of the subprogram, i.e., the (mangled) name of the function it describes, or nothing if it has none. Unlike the name of the function, this keeps the name that the function had when the debug info was created, e.g., when the function is renamed later.

The properties of DIScope, DINode and MDNode are available too.

source
LLVM.subprogram! — Function
subprogram!(builder::DIBuilder, scope::Union{DIScope,Nothing}, name::AbstractString,
            file::DIFile, line::Integer, type::DISubroutineType;
            linkage_name::AbstractString="", scope_line::Integer=line,
            local_to_unit::Bool=false, definition::Bool=true,
            flags=API.LLVMDIFlagZero, 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.

source
LLVM.replace_type! — Function
replace_type!(sp::DISubprogram, ty::DISubroutineType)

Replace the type of the given subprogram. Requires LLVM 21+.

source

Variables

Factories for local variables and parameters:

LLVM.auto_variable! — Function
auto_variable!(builder::DIBuilder, scope::DILocalScope, 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).

source
LLVM.parameter_variable! — Function
parameter_variable!(builder::DIBuilder, scope::DILocalScope, 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.

source

Expressions

LLVM.DIExpression — Type
DIExpression

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

source
LLVM.DIGlobalVariableExpression — Type
DIGlobalVariableExpression

A pairing of a DIGlobalVariable and its associated DIExpression.

Properties

gve.variable

The global variable described by the global variable expression.

gve.expression

The expression of the global variable expression, which describes the location of the variable.

The properties of MDNode are available too.

source
LLVM.expression! — Function
expression!(builder::DIBuilder,
            addr::AbstractVector{<:Integer}=UInt64[]) -> DIExpression

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

source
LLVM.global_variable_expression! — Function
global_variable_expression!(builder::DIBuilder, scope::Union{DIScope,Nothing},
                          name::AbstractString, linkage::AbstractString,
                          file::DIFile, line::Integer, type::DIType,
                          expression::DIExpression; local_to_unit::Bool=false,
                          declaration=nothing,
                          align_in_bits::Integer=0) -> DIGlobalVariableExpression

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

source
LLVM.temp_global_variable_fwd_decl! — Function
temp_global_variable_fwd_decl!(builder::DIBuilder, scope::Union{DIScope,Nothing},
                           name::AbstractString, linkage::AbstractString,
                           file::DIFile, line::Integer, type::DIType;
                           local_to_unit::Bool=false, declaration=nothing,
                           align_in_bits::Integer=0)
    -> TemporaryMDNode{DIGlobalVariable}

Create a temporary forward declaration of a global variable, to be replaced with the variable (e.g., gve.variable of a global_variable_expression!) using replace_temporary!.

source

Imported entities

LLVM.imported_module! — Function
imported_module!(builder::DIBuilder, scope::Union{DIScope,Nothing}, ns::DINamespace,
                 file::DIFile, line::Integer) -> DIImportedEntity
imported_module!(builder::DIBuilder, scope::Union{DIScope,Nothing},
                 entity::Union{DIModule,DIImportedEntity}, file::DIFile, line::Integer;
                 elements::AbstractVector=Metadata[]) -> DIImportedEntity

Create a new DIImportedEntity that imports a namespace (like C++'s using namespace), a module, or an alias of another imported entity into scope. The elements of an imported module or alias are its renamed entities.

source
LLVM.imported_declaration! — Function
imported_declaration!(builder::DIBuilder, scope::Union{DIScope,Nothing}, decl::DINode,
                      file::DIFile, line::Integer, name::AbstractString;
                      elements::AbstractVector=Metadata[])
    -> DIImportedEntity

Create a new DIImportedEntity that imports the declaration decl (e.g., a variable, subprogram or type) into scope, as name (like C++'s using).

source

Macros

LLVM.DIMacroFile — Type
DIMacroFile

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

source
LLVM.macro! — Function
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).

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

Create a new temporary DIMacroFile, for use as the parent of macro!. Unlike other temporary nodes, the builder replaces it when it is finalized, which invalidates the returned node.

source

Instruction-level insertion

Debug records are inserted at an InsertionPoint. The functions that insert them return an Instruction on LLVM ≤ 18 (legacy llvm.dbg.* intrinsics) and a LLVM.DbgRecord on LLVM ≥ 19 (the new #dbg_* record format). On LLVM 20 and later, dbg_label!(dib, label, location, pos) inserts a label record.

LLVM.dbg_declare! — Function
dbg_declare!(builder::DIBuilder, storage::Value, var::DILocalVariable,
             expr::DIExpression, debugloc::DILocation,
             pos::InsertionPoint{Instruction})

Insert a debug record that declares storage as the address of the variable var at the given position, e.g., LLVM.after(alloca). Returns a DbgRecord on LLVM ≥ 19, or the llvm.dbg.declare call Instruction on LLVM < 19.

Debug records can not be inserted at the end of a block that has a terminator; use LLVM.before(bb.terminator) instead. Several records inserted at a position that is before the debug records of an instruction (e.g., LLVM.after(inst) or LLVM.at_begin(bb)) end up in reverse order, as each one is inserted in front of the others. Use LLVM.before(inst) to append records to the ones of inst.

source
LLVM.dbg_value! — Function
dbg_value!(builder::DIBuilder, val::Value, var::DILocalVariable,
           expr::DIExpression, debugloc::DILocation,
           pos::InsertionPoint{Instruction})

Insert a debug record that describes val as the value of the variable var at the given position. Returns a DbgRecord on LLVM ≥ 19, or the llvm.dbg.value call Instruction on LLVM < 19. See dbg_declare! for which positions can be used.

source
LLVM.DbgRecord — Type
DbgRecord

A non-instruction debug record attached to a basic block, replacing the legacy llvm.dbg.* intrinsics in LLVM ≥ 19. Requires LLVM 19+.

Properties

record.kind

The kind of the debug record, an LLVM.API.LLVMDbgRecordKind: LLVMDbgRecordDeclare, LLVMDbgRecordValue or LLVMDbgRecordAssign for variable records, which describe the location of a source variable, or LLVMDbgRecordLabel for label records.

Variable records can be further inspected using the following properties:

  • record.variable: the source variable that is described;
  • record.expression: the expression that computes the variable's location;
  • record.value: the IR value used by that expression, or record.location_operands for expressions that use several values.

The source location of every record is available as record.debug_location.

record.debug_location

The source location of the debug record.

record.variable

The source variable described by a variable record.

record.expression

The expression that computes the location of the variable described by a variable record, in terms of its location_operands.

record.location_operands

The IR values that are used to compute the location of the variable described by a variable record, as a read-only view. There is usually only one, but records that use a !DIArgList can refer to several. Entries are nothing if the value has been deleted.

record.value

The IR value used to compute the location of the variable described by a variable record, or nothing if that value has been deleted. Records that refer to several values need to be inspected using their location_operands instead.

record.next
record.prev

The next or previous debug record attached to the same instruction, or nothing if there is none. prev requires LLVM 20+.

source
LLVM.DILabel — Type
DILabel

A debug-info label, describing a source-level code location by name. Requires LLVM 20+.

source
LLVM.label! — Function
label!(builder::DIBuilder, scope::DILocalScope, name::AbstractString,
       file::DIFile, line::Integer;
       always_preserve::Bool=false) -> DILabel

Create a new DILabel. Requires LLVM 20+.

source
LLVM.dbg_label! — Function
dbg_label!(builder::DIBuilder, label::DILabel, location::DILocation,
           pos::InsertionPoint{Instruction}) -> DbgRecord

Insert a debug record for the label label at the given position. See dbg_declare! for which positions can be used. Requires LLVM 20+.

source

The debug location of an instruction is available as its debug_location property (see inst.debug_location).

Compile Unit

LLVM.DICompileUnit — Type
DICompileUnit

A compilation unit in the source code.

Properties

cu.emission_kind

The amount of debug info that is emitted for the compile unit, as a LLVM.DebugEmissionKind.T value: NoDebug, FullDebug, LineTablesOnly or DebugDirectivesOnly. Julia's code generator emits subprograms and locations even when it doesn't emit debug info, marking their compile unit NoDebug. This differs from the LLVM.DWARFEmissionKind.T that compile_unit! takes, which LLVM's C API defines without DebugDirectivesOnly.

The properties of DIScope, DINode and MDNode are available too.

source
LLVM.compile_unit! — Function
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=LLVM.DWARFEmissionKind.Full,
             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 LLVM.DWARFSourceLanguage.T value (e.g. LLVM.DWARFSourceLanguage.Julia). cmdline is a command-line string embedded verbatim in the emitted debug info.

source

Other

The debug info of modules and functions is available as their debug_metadata_version and subprogram properties (see mod.debug_metadata_version and f.subprogram).