--[[
Terra build system, C header generator and LuaJIT ffi binding generator.
Written by Cosmin Apreutesei. Public Domain.
Features:
* compiles and links shared libraries.
* creates C header files and LuaJIT ffi bindings.
* supports structs, methods, global functions and global vars.
* dependent struct and function pointer types are declared automatically.
* tuples and function pointers are typedef'ed with friendly unique names.
* struct typedefs are anonymous (except when forward declarations are
needed because of circular references) which allows the same struct
definition to appear in multiple ffi bindings without raising an error.
* auto-assigns methods to types via ffi.metatype.
* enables getters and setters via ffi.metatype.
* publishes global numbers and bitmask values as enums.
* diff-friendly deterministic output.
Terra type and function object attributes for controlling the output:
* `cname` : type/function name override.
* `opaque` : declare a type but don't define it.
* `cprefix` : prefix method names.
* `private` : tag method as private.
* `public_methods`: specify which methods to publish.
* `const_args`: specify which args have the const qualifier.
Conventions:
* method names that start with an underscore are private by default.
Usage:
local lib = require'terra.binder'.lib
MyStruct.cname = 'my_struct_t'
MyStruct.opaque = true
MyStruct.methods.myMethod.cname = 'my_method'
MyStruct.public_methods = {foo=1,bar=1,...}
MyFunc.cname = 'my_func'
MyOverloadedFunc.cname = {'my_func', 'my_func2'}
MyFuncPointer.type.cname = 'myfunc_callback_t'
MyFunc.const_args = {nil, true} --make arg#2 const (for passing Lua strings)
local mylib = lib'mylib'
mylib(MyStruct) --publish Terra struct MyStruct and its dependent types.
mylib(MyFunc) --publish Terra function MyFunc and its dependent types.
mylib(_M, 'SP_', 'CP_') --publish all SP_FOO enums as CP_FOO.
mylib(_M) --publish all all-uppercase keys from _M as C enums.
mylib:build{
linkto = {'lib1', 'lib2', ...},
optimize = false, --for faster compile time when developing.
}
mylib:gen_ffi_binding()
mylib:gen_c_header()
Note:
C and LuaJIT ffi cannot handle all types of circular struct dependencies
that Terra can handle, in particular you can't declare a struct with
forward-declared struct fields (unlike Terra, C eager-completes types).
This means that you might need to add some types manually in some rare cases.
]]
See the source code for more info.