RepliBuild Internals

extract_symbols(binary_path::String, registry::TypeRegistry; demangle::Bool=true, method::Symbol=:nm)

Extract symbols from compiled binary using specified method.

Methods

• :nm - Fast, basic symbol extraction
• :objdump - Detailed with debug info (TODO)
• :all - Try all methods and merge (TODO)

Returns vector of SymbolInfo objects.

is_enum_like(cpp_type::String)::Bool

Check if a C++ type looks like an enum based on naming conventions. Returns false — enum detection is unreliable by name alone (uppercase names are more likely structs/classes). Real enum identification uses DWARF metadata via _is_enum_type() in DispatchLogic.jl which checks __enum__ prefixed keys.

is_function_pointer_like(cpp_type::String)::Bool

Check if a C++ type contains function pointer syntax. Looks for patterns: (name), ()(args), (^name) (blocks)

is_struct_like(cpp_type::String)::Bool

Check if a C++ type looks like a struct/class based on naming conventions. Structs typically: start with uppercase, contain only alphanumeric + underscore.

wrap_basic(config::RepliBuildConfig, library_path::String; generate_docs::Bool=true)

Generate basic Julia wrapper from binary symbols only (no headers required).

Quality: ~40% - Conservative types, placeholder signatures, requires manual refinement. Use when: Headers not available, quick prototyping, binary-only distribution.

wrap_library(config::RepliBuildConfig, library_path::String;
             headers::Vector{String}=String[],
             generate_tests::Bool=false,
             generate_docs::Bool=true)

Generate Julia wrapper for compiled library.

Always uses introspective (DWARF metadata) wrapping when metadata is available, otherwise falls back to basic symbol-only extraction with conservative types.

Arguments

• config: RepliBuildConfig with wrapper settings
• library_path: Path to compiled library (.so, .dylib, .dll)
• headers: Optional header files (currently unused, reserved for future)
• generate_tests: Generate test file (default: false, TODO)
• generate_docs: Include comprehensive documentation (default: true)

Returns

Path to generated Julia wrapper file

ParamInfo

Information about a function parameter.

SymbolInfo

Comprehensive information about a symbol extracted from binary/headers.

TypeRegistry

TypeStrictness

Assemble LLVM IR text (.ll) to bitcode (.bc). Uses Julia's own libLLVM via the C API (LLVMParseIRInContext + LLVMWriteBitcodeToFile) to guarantee bitcode version compatibility with Base.llvmcall. Falls back to Clangunifiedjll, then system llvm-as.

Build type registry from functions. Collects all unique types used in the codebase.

Complete compilation workflow: discover sources, compile, link, create binary. This is the main entry point for building a project.

Compile a single C++ file to LLVM IR. Returns (irfilepath, success, exitcode).

Compile multiple C++ files to LLVM IR (with parallel support). Returns vector of IR file paths.

Compute a content hash for the entire project: replibuild.toml + source files + git HEAD. Returns a hex string that changes when anything relevant changes.

Convert C++ type to Julia type. Basic type mapping - can be enhanced with type registry.

Arguments

• cpp_type: C++ type string
• struct_names: Set of known struct/class names from DWARF
• enum_names: Set of known enum names from DWARF

Create executable from LLVM IR. Returns path to executable file.

Create shared library from LLVM IR. Returns path to library file.

Comprehensive C/C++ type to Julia type mapping. Handles all standard C/C++ types including sized integers, pointers, and qualifiers.

Extract class name from method signature (only considers '::' in the function-name prefix). Example: "Calculator::compute(int, int)" -> "Calculator" Example: "sum_vector(std::vector<int> const&)" -> "" (free function)

Extract compilation metadata from source files and binary. This is the core of automatic wrapper generation!

Extract return types and struct definitions from DWARF debug info. Returns: (returntypesdict, structdefsdict)

• returntypes: Dict{mangledname => {ctype, juliatype, size}}
• structdefs: Dict{structname => {members: [{name, type, offset}]}}

Extract function name from demangled signature. Example: "Calculator::compute(int, int, char)" -> "compute" Example: "sumvector(std::vector<int, std::allocator<int> > const&)" -> "sumvector"

Extract mangled symbol name from nm output.

Extract STL method symbols from the compiled binary. Uses nm to find mangled names of template-instantiated STL methods. Returns Dict mapping normalized container type -> vector of method info dicts.

Extract symbol information from compiled binary using nm. Returns vector of symbol dictionaries with mangled/demangled names.

Generate a C/C++ shim file to instantiate requested macros as typed functions so they appear in the DWARF metadata and can be wrapped.

Generate a dummy C++ file to explicitly instantiate requested templates so they appear in the DWARF metadata.

Get type size in bytes from C/C++ type name.

Infer return type from demangled function signature using pattern matching. This is a fallback when DWARF debug info is unavailable for a given function.

Check if the project-level cache is valid. Returns true if all artifacts exist and the content hash matches, meaning the build can be skipped entirely.

Link multiple LLVM IR files and optimize. Returns linked IR path (String) or original IR files (Vector{String}) on llvm-link failure.

Check if source file needs recompilation (based on mtime).

Parse function signatures from symbol information. Infers parameter types and return types from demangled names.

Parse parameter types from demangled signature. Example: "add(int, int)" -> [{"type": "int", "julia_type": "Cint"}, ...]

sanitize_ir_for_julia(ir_text::String) -> String

Sanitize LLVM IR text for compatibility with Julia's internal LLVM (18). Strips LLVM 19–22 attributes/instructions, debug metadata, and converts varargs function bodies to extern declarations (vastart/vaend can't be JIT-compiled). Uses inlinehint (not alwaysinline) to avoid recursive inliner explosion on large modules.

Coverage by LLVM version: 19: GEP nuw, #dbg* records, inrange(), captures(), deadonunwind, initializes(), allocptr, icmp samesign, range(), trunc nuw/nsw, zext/uitofp nneg 20: GEP nusw, or disjoint, fptrunc/fpext fast-math flags, ptrtoaddr→ptrtoint 21: (covered by 19 patterns — captures/deadon_unwind/allocptr landed here) 22: ptrtoaddr instruction

This is the single source of truth for IR compatibility — used by both the C source LTO pipeline and the MLIR AOT thunks pipeline.

Save compilation metadata to JSON file next to binary. This enables automatic wrapper generation!

Save the project hash after a successful build.

Create a default configuration and save to file.

Get full build path (project_root + paths.build)

Get full cache path (project_root + cache.directory)

Get compiler flags

Get all include directories (from config)

Get library output name (uses config or auto-generates)

Get wrapper module name (uses config or auto-generates)

Get full output path (project_root + paths.output)

Get all C++ source files (from config)

Should use cache?

Should run parallel compilation?

Check if a stage is in the workflow

Load RepliBuildConfig from TOML file. This is the ONLY function that parses TOML - all other modules use this.

Merge compile flags into config (creates new config). Used for runtime overrides like: compile(sources, flags=["-O3"])

Print configuration summary

Save configuration to TOML file. Only saves user-configurable settings (not runtime data).

Validate config and throw error if invalid.

Validate configuration and return list of errors (empty if valid).

Update both source files and include dirs (creates new config). Used after discovery completes.

Update include directories in config (creates new config). Used after discovery finds include paths.

Update source files in config (creates new config). Used after discovery finds C++ sources.

Nested struct for [binary] section

Nested struct for [cache] section

Nested struct for [compile] section

Nested struct for [dependencies] section

Nested struct for a single dependency

Nested struct for [discovery] section

Nested struct for [llvm] section

Nested struct for [link] section

Nested struct for [paths] section

Nested struct for [project] section

Main immutable configuration structure. All modules receive this struct - it's the single source of truth.

Nested struct for [types] section - Type validation settings

Nested struct for [workflow] section

Nested struct for [wrap] section

discover(target_dir::String=pwd(); force::Bool=false, unsafe::Bool=false, build::Bool=false, wrap::Bool=false) -> String

Main discovery pipeline - scans project and generates configuration.

Process:

1. Check for existing replibuild.toml (project identified by presence of replibuild.toml)
2. Scan all files and categorize
3. Detect and analyze binaries
4. Walk AST dependencies using clang
5. Generate or update replibuild.toml with discovered data
6. Optionally run build and wrap pipeline

Arguments

• target_dir: Project directory (default: current directory)
• force: Force rediscovery even if replibuild.toml exists
• unsafe: Bypass safety checks (use with extreme caution)
• build: Automatically run build() after discovery (default: false)
• wrap: Automatically run wrap() after build (requires build=true, default: false)

Safety Features

• Discovery is scoped ONLY to target_dir and subdirectories
• Will not scan outside the project root
• Skips .git, build, node_modules, .cache directories

Returns

• Path to generated replibuild.toml file

Examples

# Discover only
toml_path = RepliBuild.Discovery.discover()

# Discover and build
toml_path = RepliBuild.Discovery.discover(build=true)

# Full pipeline: discover → build → wrap
toml_path = RepliBuild.Discovery.discover(build=true, wrap=true)

# Then use the TOML path:
RepliBuild.build(toml_path)
RepliBuild.wrap(toml_path)

export_vtable_json(vtinfo::VtableInfo, output_path::String)

Export vtable information to JSON for inspection or use by other tools.

parse_dwarf_output(dwarf_text::String) -> Dict{String, ClassInfo}

Parse llvm-dwarfdump output to extract class and vtable information.

parse_symbol_table(nm_output::String) -> Tuple{Dict{String, UInt64}, Dict{String, UInt64}}

Parse nm output to extract vtable and method addresses. Returns (vtableaddresses, methodaddresses).

parse_vtables(binary_path::String) -> VtableInfo

Extract complete vtable information from a binary using DWARF and symbol table.

Arguments

• binary_path: Path to compiled binary with debug info

Returns

• VtableInfo containing classes, vtable addresses, and method addresses

read_vtable_data(binary_path::String, vtable_addr::UInt64, num_entries::Int) -> Vector{UInt64}

Read actual vtable function pointers from binary at given address.

Information about a C++ class with virtual methods

Information about a data member (field)

Information about a virtual method

Complete vtable information from binary