API Reference

build(toml_path="replibuild.toml"; clean=false)

Compile C++ project → library (.so/.dylib/.dll)

What it does:

1. Compiles your C++ code to LLVM IR
2. Links and optimizes IR
3. Generates library file
4. Extracts metadata (DWARF + symbols) for wrapping

What it does NOT do:

• Does NOT generate Julia wrappers (use wrap() for that)

Arguments

• toml_path: Path to replibuild.toml configuration file (default: "replibuild.toml")
• clean: Clean before building (default: false)

Returns

Library path (String)

Examples

# Build using replibuild.toml in current directory
RepliBuild.build()

# Build with specific config file
RepliBuild.build("path/to/replibuild.toml")

# Clean build
RepliBuild.build(clean=true)

# Then generate Julia wrappers:
RepliBuild.wrap("replibuild.toml")

check_environment(; verbose=true, throw_on_error=false) -> ToolchainStatus

Run environment diagnostics to verify LLVM 21+, MLIR, CMake, and other toolchain requirements.

Prints a colorful report showing which tools are found, their versions, and installation instructions for anything missing. Use throw_on_error=true to abort on missing requirements.

Example

status = RepliBuild.check_environment()
status.ready          # true if Tier 1 (ccall) builds will work
status.tier2_ready    # true if MLIR JIT tier is also available

clean(toml_path="replibuild.toml")

Remove build artifacts (build/, julia/, caches)

Arguments

• toml_path: Path to replibuild.toml configuration file (default: "replibuild.toml")

Examples

# Clean using replibuild.toml in current directory
RepliBuild.clean()

# Clean specific project
RepliBuild.clean("path/to/replibuild.toml")

discover(target_dir="."; force=false, build=false, wrap=false) -> String

Scan C++ project and generate replibuild.toml configuration file.

This is the entry point for new projects. Run this first to set up RepliBuild.

Arguments

• target_dir: Project directory to scan (default: current directory)
• force: Force rediscovery even if replibuild.toml exists (default: false)
• build: Automatically run build() after discovery (default: false)
• wrap: Automatically run wrap() after build (requires build=true, default: false)

Returns

Path to generated replibuild.toml file

Workflow

Basic workflow (step-by-step):

# 1. Discover and create config
toml_path = RepliBuild.discover()

# 2. Build the library
RepliBuild.build(toml_path)

# 3. Generate Julia wrappers
RepliBuild.wrap(toml_path)

Chained workflow (automated):

# Discover → Build → Wrap (all at once)
toml_path = RepliBuild.discover(build=true, wrap=true)

# Or just discover and build
toml_path = RepliBuild.discover(build=true)

Examples

# Discover current directory
RepliBuild.discover()

# Discover another directory
RepliBuild.discover("path/to/cpp/project")

# Force regenerate config
RepliBuild.discover(force=true)

# Full automated pipeline
RepliBuild.discover(build=true, wrap=true)

info(toml_path="replibuild.toml")

Show project status (config, library, wrapper)

Arguments

• toml_path: Path to replibuild.toml configuration file (default: "replibuild.toml")

Examples

# Show info for current directory
RepliBuild.info()

# Show info for specific project
RepliBuild.info("path/to/replibuild.toml")

list_registry()

Print all registered packages in the global RepliBuild registry.

register(toml_path::String; name="", verified=false) -> RegistryEntry

Hash and store a replibuild.toml in the global registry (~/.replibuild/registry/). Name is inferred from [project].name if not provided. Called automatically by discover().

scaffold_package(name::String; path::String=".") -> String

Generate a standardized Julia package for distributing RepliBuild wrappers.

Creates a complete package with Project.toml, replibuild.toml, source stub, deps/build.jl hook, and test skeleton. Edit the replibuild.toml to point at your C/C++ source, then Pkg.build() compiles and wraps automatically.

Example

RepliBuild.scaffold_package("MyEigenWrapper")

search(query::String="")

Search the RepliBuild Hub for available packages. Matches against names, descriptions, tags, and language. Call with no arguments to list everything.

RepliBuild.search()           # list all hub packages
RepliBuild.search("json")     # filter by keyword

unregister(name::String)

Remove a package from the global registry.

use(name::String; force_rebuild=false, verbose=true) -> Module

Load a wrapper by registry name. Resolves dependencies, checks environment, builds if needed, and returns the loaded Julia module.

Example

Lua = RepliBuild.use("lua")
Lua.luaL_newstate()

wrap(toml_path="replibuild.toml"; headers=String[])

Generate Julia wrapper from compiled library

What it does:

1. Loads metadata from build (DWARF + symbols)
2. Generates Julia module with ccall wrappers
3. Creates type definitions from C++ structs
4. Saves to julia/ directory

Requirements:

• Must run build() first
• Metadata must exist in julia/compilation_metadata.json

Arguments

• toml_path: Path to replibuild.toml configuration file (default: "replibuild.toml")
• headers: C++ headers for advanced wrapping (optional)

Returns

Path to generated Julia wrapper file

Examples

# Generate wrapper using replibuild.toml in current directory
RepliBuild.wrap()

# Generate wrapper with specific config file
RepliBuild.wrap("path/to/replibuild.toml")

# With headers for better type info
RepliBuild.wrap("replibuild.toml", headers=["mylib.h"])