A lightweight, header-only C++17 binding library for Lua.
A header-only C++ and Lua glue/bridge library (b stands for bridge). Built on modern C++17, bLua provides a small, non-intrusive interface for seamless interoperability between C++ and Lua.
- Modern C++17: Leverages fold expressions and template metaprogramming for compact bindings.
- Header-only: Single header file
bLua.hwith no extra libraries to build—just drop it into your project and use. - Member Function Support: Easily binds regular functions, member functions, and
constmember functions. - Rich Type Support: Built-in support for
std::string_view,std::string, primitive types, custom user classes, plusstd::vector/std::map↔ Lua table helpers. - Non-intrusive: No need to inherit from any base class or decorate classes with intrusive macros.
- Configurable ownership: Owning / non-owning / custom deleter so Lua
__gcdoes not free C++-owned pointers. - Stable type names: User-provided metatable names (demangled
typeidfallback on GCC/Clang). - API DX: Constructors, properties, enums, and arity-based free-function overloads.
- Modern CMake: First-class support for
find_package(bLua),FetchContent, and CTest unit testing.
| Runtime | Status | Notes |
|---|---|---|
| Lua 5.4 | Supported (CI) | Primary target |
| Lua 5.3 | Supported (CI) | |
| Lua 5.2 | Supported (CI configuration) | Version-neutral getter wrappers |
| Lua 5.1 / LuaJIT | Supported (CI configuration) | Private compatibility helpers; no Lua API macro overrides |
Register a class and its member functions (supports global functions, member functions, const member functions, etc.):
#include "bLua.h"
// Register global functions
bLua::reg_global_func(L, "newA", newA);
bLua::reg_global_func(L, "printA", printA);
// Register class with a stable name (recommended); default ownership is owning (delete on __gc)
bLua::reg_class<A>(L, "A");
bLua::reg_class_func(L, "get_this", &A::get_this);
bLua::reg_class_func(L, "get_int", &A::get_int);
bLua::reg_class_func(L, "get_int_const", &A::get_int_const);
bLua::reg_class_func(L, "set_int", &A::set_int);
bLua::reg_class_func(L, "get_string", &A::get_string);
bLua::reg_class_func(L, "set_string", &A::set_string);
// Non-owning (C++ keeps ownership; __gc does not delete)
// bLua::reg_class_non_owning<A>(L, "A");
// Custom deleter:
// bLua::reg_class_with_deleter<A>(L, my_free_A, "A");
// Constructor / property / enum / overload
bLua::reg_constructor<A, int>(L, "A_new");
bLua::reg_property(L, "a", &A::m_a); // get_a / set_a
bLua::reg_enum<Color>(L, "Color", {{"Red", Color::Red}, {"Green", Color::Green}});
bLua::reg_global_overload(L, "add", add1, add2); // dispatch by argument countThen invoke them in Lua:
local a = newA()
a:set_int(123)
print("a:get_int() ", a:get_int())
a:set_string("abc")
print("a:get_string() ", a:get_string())bLua::reg_class<A>(L, "A"); // copied, state-local name
bLua::push(L, cpp_owned, bLua::ownership::non_owning);
// Names now require the state; replaces the former process-global API:
bLua::set_type_name<B>(L, "B"); // before registration
bLua::reg_class<B>(L);
const char* name = bLua::get_type_name<B>(L); // borrowed until state closes / name changes- Each Lua state has independent names and default ownership/deleters. The wrapper's destruction policy is fixed at creation, independent of subsequent registrations elsewhere.
- Identical class registrations are idempotent. Renaming/reconfiguring a registered class,
or registering another type with the same name, throws
std::runtime_error. - Within one state, the same address and type reuse one live userdata. An explicit
push(L, ptr, ownership)with conflicting ownership is rejected, never silently adopted. Implicit pushes/returned pointers reuse an existing wrapper's policy; class defaults apply only to new wrappers. Different types at the same address are rejected (no inheritance casts). - Constructors always return Lua-owned objects, even for a non-owning class default.
Custom deleters must match the allocation and must not throw; each wrapper calls its captured
deleter at most once. Repeated
__gcis harmless; methods/properties reject finalized objects. - Borrowed C++ objects must outlive every Lua reference. This is not a weak pointer to C++:
external destruction cannot be detected automatically. Never give multiple Lua states owning
wrappers for the same C++ allocation. Raw pointers returned to C++ are borrowed; keep a Lua
reference rooted while using them.
const char*/string_viewresults also borrow Lua storage. - Registration/stack helpers called directly from C++ throw on validation errors. Do not invoke them from an unguarded C callback and let C++ exceptions cross Lua. Normal registered callbacks translate native exceptions to Lua errors after C++ temporaries have unwound.
call_lua_global_func / call_lua_table_func return an error string for Lua execution,
missing functions/tables, native exceptions, and result/argument conversion failures. The
caller's Lua stack is restored. Result values are converted before updating outputs, so a
conversion failure does not partially overwrite them. Debug/traceback is optional; arbitrary
Lua error objects get a safe fallback message. Function/path lookup uses raw table keys,
not __index metamethods. Assignment/allocation failures in user-defined C++ result types are
not a transactional guarantee.
Numbers, booleans and strings are checked rather than silently coerced. Integer conversions
reject fractions/range overflow; values pushed as integers must fit lua_Integer. Lua 5.1/5.2
and LuaJIT number precision still depends on their runtime build (usually double).
Missing numeric/string results are errors, not zero/empty defaults. Nullable class pointers and
const char* accept nil; C++ callbacks receiving null pointers must handle them.
The protected boundary covers ordinary Lua errors and C++ exceptions, not recoverable Lua
allocator exhaustion, arbitrary host callbacks that call lua_error across live C++ RAII,
or hostile metatable/registry modification. Use a Lua library built as C with its normal
protected-call ABI, C++ exceptions enabled, and trusted host callbacks/deleters. Lua OOM can
longjmp over C++ temporaries during allocations; treat it as fatal rather than resume execution.
reg_global_overload dispatches by argument count only and rejects duplicate arities before
replacing the global function. Same-arity, type-based overload resolution is not implemented;
use distinct Lua names or an explicit static_cast when selecting a C++ overloaded function.
reg_property creates get_name/set_name methods, not Lua field accessors. Const data members
are getter-only; const getter functions can be paired with a setter.
std::vector<int> v = bLua::to_vector<int>(L, index);
bLua::push_vector(L, v);
std::map<std::string, int> m = bLua::to_map<std::string, int>(L, index);
bLua::push_map(L, m);Conversions support nested vectors/maps and the supported scalar/pointer types. Vectors read
Lua's 1-based sequence (rawlen); holes and non-sequence fields are not a dense-array contract.
Maps preserve lua_next's key. Key types are strict: numeric keys work with map<int, V>;
map<string, V> rejects numeric/mixed keys rather than stringifying them. Failures restore the
stack. Empty tables convert to empty containers.
int output_int = 0;
std::string output_str;
uint64_t output_int64 = 0;
int input_int = 123;
std::string input_str = "test";
auto err = bLua::call_lua_global_func(L, "global_func_name",
std::tie(output_int, output_str, output_int64),
input_int, input_str);
if (err) {
printf("ret error: %s\n", err.value().c_str());
} else {
printf("%d %s %llu\n", output_int, output_str.c_str(), output_int64);
}function _G.test.func.test(a, b)
return a - b
endauto err = bLua::call_lua_table_func(L, {"_G", "test", "func"}, "test",
std::tie(output_int),
input_int, input_int2);For complete examples, refer to test/test.cpp and test/test.lua. See also CHANGELOG.md.
Copy bLua.h into your project directory and #include "bLua.h".
include(FetchContent)
FetchContent_Declare(
bLua
GIT_REPOSITORY https://github.com/esrrhs/bLua.git
GIT_TAG master
)
FetchContent_MakeAvailable(bLua)
target_link_libraries(your_target PRIVATE bLua::bLua)After installing, use it directly in CMakeLists.txt:
find_package(bLua REQUIRED)
target_link_libraries(your_target PRIVATE bLua::bLua)The installed bLua prefix may be moved. Lua is an external dependency, not bundled with
bLua: the consumer must independently discover an ABI-compatible Lua installation (and the
same runtime family/version its host uses). Set LUA_INCLUDE_DIR / LUA_LIBRARY when needed,
especially for LuaJIT or machines with multiple versions. Exported bLua targets reference
Lua::Lua, not the producer's Lua paths; find_dependency(Lua) resolves them on the consumer.
Build and run tests using modern CMake:
# Configure
cmake -B build -DCMAKE_BUILD_TYPE=Release
# Build test executable
cmake --build build
# Run unit tests
ctest --test-dir build --output-on-failure
# Debug with test-only ASan/UBSan (GCC/Clang)
cmake -B build/sanitize -DCMAKE_BUILD_TYPE=Debug -DBLUA_ENABLE_SANITIZERS=ON
cmake --build build/sanitize
ctest --test-dir build/sanitize --output-on-failureThe CTest suite includes integration, regressions, intentional C++/Lua failure-exit checks,
and install → move prefix → separate find_package consumer build/run. Checks remain enabled
in Release. CI config covers GCC/Clang × Lua 5.1–5.4, LuaJIT, macOS, Windows, and Linux Debug /
ASan+UBSan. Windows builds pinned official Lua 5.4.7 sources with MSVC; LuaJIT foreign unwinding is preserved.
This describes the workflow configuration, not proof that unpushed CI has run.