The replibuild.toml Reference

replibuild.toml is the interface. Every piece of library-specific knowledge lives in this file and nowhere else — not in a generator fork, not in a patch, not in a hand-written shim. discover() writes what it can see by scanning; the rest is what you have to tell it, and §2 is the list of exactly what that is.

The file is read in one place (ConfigurationManager.load_config) and frozen into an immutable RepliBuildConfig. Everything below is what that parser actually does — including the keys it validates loudly, the keys it warns about, and the handful it currently accepts and ignores.

1. How the file is created and maintained

toml = RepliBuild.discover("path/to/project")      # writes replibuild.toml
RepliBuild.discover("path/to/project", force=true) # rescan, preserving intent keys

Discovery scans sources, walks the #include graph, picks wrap.language from the file extensions it found, and writes a config that compiles. It cannot infer anything that is not visible in the source tree's shape — see §2.

Forced re-discovery preserves hand-curated keys. discover(force=true) regenerates the file, and without carry-over it would emit these empty, silently destroying your intent. The preserved set (Discovery.PRESERVED_TOML_KEYS) is:

A regenerated non-empty value wins; an empty or absent one gets the preserved value. If you add a new user-intent key to the schema, add it to that list too — otherwise the next forced re-discovery eats it. (This is not hypothetical: the stl_test fixture was red for six weeks because [types].templates vanished on every run.)

Anything not in that table is regenerated from the scan. Notably [compile] flags, include_dirs, and [dependencies] are not preserved — keep a hand-written config under version control rather than relying on force=true to round-trip it.

save_config only writes keys with non-default or non-empty values, so a round-tripped file is smaller than the full schema. Absent keys take the parse-time defaults in §3, which are not always the same as what discover() writes — the divergences are flagged in the tables.

2. What discovery cannot know

This is the important section. Everything here is information that exists only in a human's head or in the upstream build system, and that RepliBuild will not guess. Omit it and you get a build that succeeds and a wrapper that is missing things or is wrong.

2.1 C++ templates and the STL — "STL needs STL in the TOML"

A template that is never instantiated does not exist in the binary. The compiler emits DWARF for code it generated; an uninstantiated std::vector<int> generated nothing, so there is nothing to read. No amount of header scanning changes this — the information is not missing, it was never created.

So you name the instantiations you want, and RepliBuild writes a stub .cpp that forces them:

[types]
templates        = ["std::vector<int>", "std::string", "std::map<int, int>"]
template_headers = ["<vector>", "<string>", "<map>"]

• templates entries are C++ type spellings, exactly as you would write them in template class X;.
• Common STL headers are auto-detected from the type name (std::vector → <vector>, std::map → <map>, and the same for unordered_map, set, unordered_set, deque, list, basic_string/string). template_headers is for everything else — your own headers, or a library's:

  templates        = ["fmt::basic_memory_buffer<char>"]
  template_headers = ["<fmt/format.h>"]

• Typedef spellings are expanded for you where an explicit instantiation would otherwise be invalid C++: std::string → std::basic_string<char>, and the same for wstring / u16string / u32string.
• Entries starting with < are emitted as #include <…>; anything else becomes #include "…".

Once instantiated, the STL method symbols are extracted (extract_stl_method_symbols) and become container accessor thunks. A C++ library whose public API is STL-free needs none of this — box2d 2.4 reports stl_methods = 0 and declares no templates.

2.2 Preprocessor macros

Macros do not survive compilation, so they are absent from both the symbol table and DWARF. RepliBuild generates a typed C/C++ shim function per declared macro, compiles it into the library, and wraps the resulting real symbol.

[wrap]
shim_headers = ["lua.h", "lauxlib.h"]     # what the shim TU #includes

# Function-like macro: `args` present → emits MACRO(arg0, arg1)
[wrap.macros.lua_pop]
ret  = "void"
args = ["lua_State*", "int"]

# Value macro: `args` ABSENT → emits the bare MACRO expression
[wrap.macros.LUA_REGISTRYINDEX]
ret = "int"

• ret and args are C type strings, pasted verbatim into generated C. They are not Julia types. (Contrast §2.3, which is Julia types — this asymmetry is the single easiest mistake to make in this file.)
• The presence of the args key is the switch, not its contents: args = [] means a zero-argument function-like macro (MACRO()), while omitting args entirely means a value macro (MACRO).
• Shims are emitted with __attribute__((used, visibility("default"))) so they survive -fvisibility=hidden builds and LTO internalization — without that, projects like box2d3 would silently lose every macro.
• In Julia the replibuild_shim_ prefix is stripped: you call lua_pop(L, 1).

2.3 Variadic functions

DWARF records that a function is variadic. It cannot record what you intend to pass. Declare one entry per concrete overload:

[wrap.varargs]
lua_pushfstring = [
    ["Cstring"],
    ["Cint"],
    ["Cstring", "Cint"],
]

Three rules, each of which has bitten someone:

1. List only the variadic arguments. The fixed parameters (lua_State*, the const char* fmt) come from DWARF and are prepended automatically.
2. The names are Julia types, not C types. Allowed: Any, Bool, Cstring, Cwstring, Cchar, Cuchar, Cshort, Cushort, Cint, Cuint, Clong, Culong, Clonglong, Culonglong, Cintmax_t, Cuintmax_t, Csize_t, Cssize_t, Cptrdiff_t, Cwchar_t, Cfloat, Cdouble, Cintptr_t, Cuintptr_t, the sized Int*/UInt*/Float* types, and Ptr{Name}. Anything else is a hard error naming the entry.
3. It is a list of lists. f = ["Cint"] is one overload taking… nothing coherent; the parser rejects it and tells you to write f = [["Cint"]].

Vararg wrappers lower as true variadic calls (the @ccall semicolon form), so the x86-64 SysV variadic protocol — including the AL register-count setup that gates the callee's va_start — is formally correct, float varargs included. A Ptr{X} overload sanitizes to _PtrX in the generated function name.

2.4 char* return ownership

Whether a returned char* must be freed, and by what, is not in DWARF and not reliably in the name. Declare it:

[wrap.cstring_owned]
cJSON_Print     = "cJSON_free"
sqlite3_mprintf = "sqlite3_free"

The wrapper copies the string into Julia and then frees the C buffer through the named symbol. Undeclared functions get the default policy — Union{String,Nothing}, where NULL is a value rather than an exception, and the buffer is left alone. Every Cstring-returning function additionally gets a raw <name>_ptr variant that returns the pointer unchanged for lifetime-sensitive callers. The value must be a non-empty string; anything else is warned about and ignored.

2.5 Header-only aggregates need -fstandalone-debug

Clang's default "limited" debug info emits a header-only aggregate that no TU instantiates as a DW_AT_declaration-only stub. Those are exactly the "def" structs a caller is supposed to fill in — b2BodyDef, b2FixtureDef, llama_model_params, llama_context_params — so they wrap to empty Julia structs and the API becomes uncallable.

[compile]
flags = ["-O2", "-fPIC", "-std=c++17", "-fstandalone-debug"]

DWARF is RepliBuild's input format, so this flag is load-bearing, not bloat. Reach for it whenever a struct you can see in the header comes out with no fields.

2.6 Excluding what is not the library

A repository is usually more than the library: tests, examples, GUI testbeds, vendored third-party trees, alternative backends, other CPU architectures. The dependency resolver walks the whole tree, so anything compilable gets compiled and lands in the DWARF the wrapper is generated from.

[dependencies.box2d]
type = "git"
url  = "https://github.com/erincatto/box2d.git"
tag  = "v2.4.1"
exclude = ["testbed", "unit-test", "extern", "docs"]

exclude entries are matched against the path relative to the dependency root, and the match is deliberately generous — an entry hits if it equals the filename, or is a prefix, suffix, or any substring of the relative path. That is why "ggml-cuda/" and "tools/" work as directory filters and "xmltest.cpp" works as a file filter, and also why a very short entry can over-match: prefer "tests" over "t", and keep a trailing / on directory entries. Excluding aggressively is normal — llama.cpp's config excludes roughly thirty paths, each with a comment explaining why.

The walker additionally drops directories named test, tests, testes, example, examples, fuzzing, build, .git, doc, and docs on its own, so those need no entry (several Hub configs list them anyway, harmlessly).

2.7 Include roots

The resolver adds <clone>, <clone>/include and <clone>/src automatically. Anything at a different depth must be named:

[compile]
include_dirs = [
    ".replibuild_cache/deps/llamacpp/ggml/include",
    ".replibuild_cache/deps/llamacpp/ggml/src",
]

Entries are passed through verbatim as -I<dir>. Relative paths resolve against the directory containing replibuild.toml, because build() runs there.

2.8 Link libraries

[link]
link_libraries = ["m", "pthread", "dl"]   # → -lm -lpthread -ldl
link_dirs      = ["/opt/thing/lib"]       # → -L/opt/thing/lib

A shared library links happily with sin left undefined, so omitting -lm is not a build error — it is a .so whose DT_NEEDED chain is short. That matters beyond the obvious runtime failure: the Tier-1 slice pre-flight scopes symbol lookup to the library plus its DT_NEEDED chain, so on miniaudio a missing -lm demoted all 51 slices that declare sin/pow/log back to ccall with no other sign.

2.9 Defines the build system would have supplied

Upstream's CMake or Makefile often injects defines that no header declares. Without them a TU fails to compile, or a subsystem is silently absent:

[compile]
flags = [
    "-O2", "-fPIC",
    "-DGGML_USE_CPU",                 # else the backend registry is empty
    '-DGGML_VERSION="0.18.1"',        # else ggml.c is the one TU that won't build
]

[compile.defines]                     # equivalent, emitted as -Dkey=value
SQLITE_THREADSAFE = "1"

[compile.defines] always emits -Dkey=value; for a bare -DFOO with no value, use [compile] flags. Both feed the compile fingerprint, so changing either correctly invalidates the per-file IR cache.

2.10 Tier 1 (C only)

Opt in per package. See Zero-cost LTO dispatch for what a slice is:

[wrap.tier1]
enable = true

2.11 Pinning content, not just a name

A git tag is a mutable ref. commit is the only check that survives a cache wipe:

[dependencies.lua]
type   = "git"
url    = "https://github.com/lua/lua.git"
tag    = "v5.4.7"
commit = "1ab3208a1fceb12fca8f24ba57d6e13c5bff15e3"

It must be a full 40-hex object name — abbreviated SHAs are rejected at config load, because they are ambiguous against future history. A mismatch after clone/checkout is a hard error, not a warning.

3. Section reference

Types are TOML types. "Default" is what the parser uses when the key is absent; where discover() writes something different, that is called out.

[project]

[paths]

[discovery]

[compile]

Changing flags, defines, or include_dirs correctly invalidates the per-file IR cache — it is keyed on a compile fingerprint as well as source mtime.

[link]

[binary]

[wrap]

[wrap.varargs] (preserved)

Typed overloads for variadic functions. Julia type names, variadic arguments only, list-of-lists. See §2.3 for the full rules and the allowed type names.

[wrap.varargs]
lua_pushfstring = [["Cstring"], ["Cint"], ["Cstring", "Cint"]]

[wrap.macros] (preserved)

One sub-table per macro. ret and args are C type strings; the presence of args selects function-like vs value macro. See §2.2.

[wrap.macros.deflateInit]
ret  = "int"
args = ["z_stream*", "int"]

[wrap.macros.ZLIB_VERSION]
ret = "const char*"

[wrap.cstring_owned] (preserved)

function name = "deallocator symbol". See §2.4.

[wrap.tier1] (preserved)

C projects only. Routes eligible functions through Base.llvmcall on a per-function bitcode slice instead of ccall.

[wrap.tier1]
enable       = true
max_slice_kb = 64
allow_setjmp = false
exclude      = ["lua_error"]

Requires [link] promote_statics = true (the default) and the in-process C pipeline. On a fallback or ingest build there is no promoted module, so Tier 1 disables itself for the whole wrap with a warning rather than shipping unverified slices. Every non-accepted function emits exactly the ccall it would have emitted with Tier 1 off, and the module exports TIER1_FUNCTIONS::Set{String}.

The wrap prints two counts — N slices accepted then N slices emitted (M functions). A gap between them is the ABI shape gate refusing a Cstring or struct crossing, not a failure.

[types]

Strictness modes: strict fails on any type that cannot be mapped exactly; warn reports the imperfect mapping and continues (Ptr{Cvoid} for complex pointers); permissive falls back silently. This governs type mapping; it does not relax the exact-or-opaque rule for struct layouts, which is unconditional.

[dependencies]

Each dependency is a named sub-table. Both spellings work:

[dependencies.cjson]
type    = "git"
url     = "https://github.com/DaveGamble/cJSON.git"
tag     = "v1.7.18"
commit  = "acc76239bee01d8e9c858ae2cab296704e52d916"
exclude = ["test", "fuzzing"]

[dependencies]
pugixml = { type = "git", url = "https://github.com/zeux/pugixml.git", tag = "v1.15" }

Git dependencies clone into .replibuild_cache/deps/<name>/ and re-checkout on tag change. Resolved sources merge into the compilation graph before [compile] runs, so they are compiled with the same toolchain and flags as your own files — which is exactly why the resulting DWARF is consistent across the whole project.

[ingest]

Experimental, C only. The presence of this section is the mode switch: no compilation happens, only DWARF extraction and wrapper generation over a .so you built yourself (with -g). Ingested libraries dispatch through Tier 3 (ccall) exclusively — no LTO bitcode, no Tier-1 slices, no Tier-2 thunks, and the C++ API surface of an ingested binary is unsupported.

Generate it with RepliBuild.ingest("/path/to/libfoo.so", headers=[...]) rather than by hand.

[llvm]

[cache]

[workflow]

Validated against the five known stage names (an unknown one is a config validation error), but not currently consulted — the pipeline runs its fixed order. Do not use it to skip a stage; call the individual verbs instead.

4. Interactions and precedence

• wrap.language decides more than the generator. It selects the toolchain (JLL clang + in-process libLLVM for c; system clang++ + the external pipeline for cpp) and the default value of [link] enable_lto. Setting it wrong produces a build that works and a wrapper that is missing the whole reason you chose the other one.
• [wrap.tier1] requires [link] promote_statics and the in-process C path. fallback = true, ingest mode, or a C++ project all disable Tier 1 for the whole wrap, loudly.
• enable_lto and [wrap.tier1] are independent knobs and both can emit. Slicing did not replace the whole-module call-site path.
• [ingest] wins over source-build keys. A config with both gets warnings naming [compile] source_files and any git/local dependency, and proceeds in ingest mode.
• [binary] output_name is overridden in ingest mode when left empty, so wrap() finds the library where it expects it.
• [cache] directory is the cache path; [paths] cache is inert. Likewise [paths] source and [paths] include.

5. What fails loudly, what warns, what is ignored

Knowing which is which is the difference between a five-minute fix and an afternoon.

Hard error at config load

• [dependencies.<n>] commit that is not a full 40-hex object name.
• [wrap.varargs.<f>] that is not a list, or whose entries are not lists — with a message showing the correct shape.
• validate_config!: empty project.name; non-existent project.root; a [compile] source_files entry that does not exist on disk; an optimization_level outside 0/1/2/3/s/z; an unknown [workflow] stages entry; an invalid binary.type / wrap.style / llvm.toolchain / types.strictness value reaching validation.

Hard error later in the pipeline

• A resolved dependency HEAD that disagrees with the declared commit.
• A macro shim #include that resolved outside the project/dependency tree.
• A vararg overload naming a type outside the allowed set (§2.3).
• A wrapper whose ccall signatures would name an undeclared type — refused before it is written.
• A generated wrapper containing an unqualified error("…") call — refused, because a library that defines its own error symbol would rebind it and take out every failure path in the module.

Warning, then proceeds

• Missing [project] section or project.name.
• An unparseable uuid (a new one is generated).
• [ingest] without library → the section is dropped and you are in source-build mode.
• [ingest] alongside source_files or fetchable dependencies.
• Invalid binary.type / wrap.style / llvm.toolchain → default substituted.
• A [wrap.cstring_owned] value that is not a non-empty string → entry ignored.
• A struct whose layout cannot be modelled consistently → degrades to a correctly-sized opaque region (capped at ten warnings plus a summary).

Accepted and ignored

• [discovery] (whole section), [workflow] stages, [wrap] style, [binary] strip_symbols, [paths] source / include / cache.
• extra_link_libs outside [ingest].
• Any key not in the schema — TOML parses it, the config drops it. There is no unknown-key warning, so a typo'd key name is silent. Check your spelling against §3 when a setting appears to have no effect.

6. Worked configurations

A C library from git, with Tier 1

[project]
name    = "lua"
version = "5.4.7"
root    = "."

[dependencies.lua]
type    = "git"
url     = "https://github.com/lua/lua.git"
tag     = "v5.4.7"
commit  = "1ab3208a1fceb12fca8f24ba57d6e13c5bff15e3"
exclude = ["onelua.c", "lua.c", "luac.c", "ltests.c"]   # the interpreter, not the library

[compile]
flags = ["-O1", "-fPIC", "-DLUA_USE_LINUX"]

[link]
enable_lto         = false      # whole-module payload stays off
optimization_level = "2"

[binary]
type = "shared"

[wrap]
language     = "c"
shim_headers = ["lua.h", "lauxlib.h", "lualib.h"]

[wrap.tier1]
enable = true

[wrap.varargs]
lua_pushfstring = [["Cstring"], ["Cint"], ["Cdouble"], ["Cstring", "Cint"]]

[wrap.macros.lua_pop]
ret  = "void"
args = ["lua_State*", "int"]

[wrap.macros.LUA_REGISTRYINDEX]
ret = "int"

[types]
strictness              = "warn"
allow_unknown_structs   = true
allow_function_pointers = true

[cache]
enabled = true

A C++ library with templates

[project]
name    = "fmt"
version = "12.1.0"
root    = "."

[dependencies.fmt]
type    = "git"
url     = "https://github.com/fmtlib/fmt.git"
tag     = "12.1.0"
commit  = "407c905e45ad75fc29bf0f9bb7c5c2fd3475976f"
exclude = ["test", "doc", "support", "benchmark"]

[compile]
flags = ["-O2", "-fPIC", "-std=c++20"]

[link]
enable_lto         = false      # C++ default; Tier 2/3
optimization_level = "2"

[wrap]
language = "cpp"

[types]
strictness       = "warn"
templates        = ["fmt::basic_memory_buffer<char>"]
template_headers = ["<fmt/format.h>"]

[cache]
enabled = true

A pre-built C binary (ingest)

[project]
name = "foo"

[ingest]
library         = "/path/to/libfoo.so"      # must have been built with -g
headers         = ["/path/to/include"]
extra_link_libs = ["m", "pthread"]

[wrap]
language = "c"

7. Troubleshooting index