C++11 API for creating Lua bindings

Overview
=head1 NAME

luacxx - C++11 binding and modules for Lua

=head1 SYNOPSIS

    // Create a new Lua environment to play with.
    auto env = lua::create();

    // Introduce a global into Lua
    env["foo"] = "No time";

    // Run some Lua code directly
    lua::run_string("assert(foo == 'No time')");

    // Retrieve a global
    auto value = env["foo"].get<std::string>();
    assert(value == "No time");

=head1 DESCRIPTION

Luacxx is a C++ library that helps you write Lua bindings for C++ and C code.
It also contains complete bindings for several major C and C++ libraries.

B<Luacxx plays well with others.> Luacxx does not try to cover up Lua's C API
or its stack-based model. In fact, Luacxx and Lua C API's can and must be
mixed freely, and Luacxx works transparently over Lua's stack, so you can work
using either one. There is absolutely no harm in mixing the two together.

B<Luacxx is fast>. A binding's overhead of calling into C and converting
arguments can be significant for simple methods. Luacxx has been built
specifically for efficiency, so it has avoided much of the overhead
that plagues other bindings (and older versions of Luacxx!).

Luacxx's overhead is around that of an extra function call, which means that a
C++ binding will be faster than equivalent Lua code for all but the most
trivial of cases. For instance, this math-intensive benchmark has the
QQuaternion binding performing ~150% faster than an API-indentical quaternion
written in Lua:

    quat = QQuaternion:new(2, 3, 7, 5);
    for i=1, MAX do
        -- Do some CPU-intensive matrix math, as well as creating a temporary.
        quat = quat * QQuaternion:new(2, 2, 2, 2);
        quat:normalize();
    end

    // My numbers
    Benchmark Runs: 10000
    C++:      0.824ms ( 1.00 relative to C++)
    Lua:     21.514ms (26.10 relative to C++)
    Luacxx:  13.579ms (16.47 relative to C++)

B<Luacxx is frugal>. Luacxx takes advantage of C++'s memory efficiency.
Objects pushed on the Lua stack are instantiated directly on new Lua userdata,
and with only 4 bytes of Luacxx-specific metadata appended to the end.
lua_touserdata works out-of-the-box, and the returned value can be cast
directly to the intended C++ type.

B<Luacxx is open-ended>. Much of Luacxx is built using class templates. This
allows you to add new support for your own types without needing to recompile
Luacxx. Once a new template specialization for your type is found, all of
Luacxx's APIs will be able to use it.

B<Luacxx is comprehensive>. Luacxx includes bindings for over 150 Qt classes,
as well as automatic introspection support for QObjects. It also has
preliminary support for Gtk's introspection system, allowing any project with
GObject introspection support to work with Luacxx.

B<Luacxx is not a generator>. Luacxx doesn't write header files or extra
boilerplate. Everything can be done using just a C++11 compiler.

=head2 OVERVIEW

This library is designed to work in tandem with Lua's existing C API, so it
does not provide a complete facade. On the contrary, I find Lua's C API to be
amazingly well-designed, so I've tried to ensure that Luacxx can be intermixed
freely with Lua's C API. In fact, most of the Lua C API has no analog in
Luacxx - I just use the original, like in the following example:

    // Add all arguments
    int add_several(lua_State* const state)
    {
        // Get each argument
        int sum = 0;
        for (int i = 1; i <= lua_gettop(state); ++i) {
            sum += lua::get<int>(state, i);
        }

        // Return the value
        lua::push(state, sum);
        lua_replace(state, 1);
        return 1;
    }

That being said, there are several places where Luacxx greatly simplify common
tasks. For instance, Lua has a number of lua_push* functions that can be
replaced with Luacxx's lua::push template and appropriate specializations. You
can extend this specialization with your own types, and Luacxx's other
features will immediately support them.

C++11 also adds support for variadic templates, which can be used to provide a
way to push a function of any arity into Lua without needing to write the
marshalling code yourself or running a preprocessor:

    // Standard C API is, of course, supported
    int create_foo(lua_State* const);
    lua::push(state, create_foo);

    // Fundamental types work, too
    int sum(int a, int b);
    lua::push(state, sum);

    // As do pointers to userdata and conversions to C++ strings.
    void changeTitle(QWindow* window, const std::string& title);
    lua::push(state, changeTitle);

    // Even lambdas work too, with a bit of help
    lua::push_function< int(int, int) >(state, [](int first, int second) {
        return first + second;
    });

=head1 STYLE

STL conventions are used for naming and case, though not slavishly, to
infer that a template-heavy C++ dialect is used. However, adherance to Lua's
conventions is preferred over that of C++.

=head1 BUILDING

   git clone https://github.com/dafrito/luacxx.git
   cd luacxx

    autoreconf -i

    mkdir build
    cd build

    ../configure --prefix=$HOME

    make

=head1 REQUIRED DEPENDENCIES

=head2 C++11 compiler

Luacxx depends heavily on C++11 features for its operation. It would be a
large undertaking to remove the use of these new features, and not without a
significant loss in the expressiveness of the code.

Luacxx has been built successfully using the following compilers:

    gcc version 4.8.3 20140911 (Red Hat 4.8.3-7) (GCC)
    gcc version 4.8.3 20140624 (Red Hat 4.8.3-1) (GCC)
    clang version 3.4 (tags/RELEASE_34/final)

=head2 Lua 5.2

Luacxx uses Lua as its underlying foundation. It would not be possible to
remove it without rewriting the project, though support for older Lua versions
be added.

Luacxx has been built successfully using the following versions:

    Lua 5.2.2  Copyright (C) 1994-2013 Lua.org, PUC-Rio

=head1 OPTIONAL DEPENDENCIES

=head2 Linux kernel

If available, bindings for the Linux kernel headers will be compiled.

    yum install kernel-headers

This binding is minimal; see linux/* for what is available.

=head2 Qt 5 - http://qt-project.org/doc/qt-5/index.html

This binding is mostly complete for Qt5Core and Qt5Gui; see
Qt5Core/*, Qt5Gui/*, et all for what is supported.

This binding is only partially complete for Qt5Network and Qt5Widgets.

=head2 libevdev

If available, bindings for the evdev input library will be compiled.

    yum install libevdev-devel

This binding is complete; see libevdev.hpp for information.

=head2 gobject-introspection

If available, Gtk's GObject introspection model will be available to Lua.

    yum install gobject-introspection-devel

This binding is functional, but not complete. See search/GIRepository.cpp for more
details.

=head2 libinput - http://wayland.freedesktop.org/libinput/doc/latest/index.html

If available, bindings for the libinput input handling library will be
compiled.

    yum install mtdev-devel systemd-devel

This binding is complete; see libinput.hpp for more information.

=head2 ncurses - http://invisible-island.net/ncurses/ncurses.html

If available, bindings for the ncurses terminal library will be compiled.

    yum install ncurses-devel

This binding is complete; see ncurses.hpp for more information.

=head2 gbm - http://www.mesa3d.org/

If available, bindings for Mesa's generic buffer management will be compiled.

    yum install mesa-libgbm-devel

This binding is complete; see gbm.hpp for more information.

=head2 nanomsg - http://nanomsg.org/

If available, bindings for the nanomsg IPC library will be compiled.

    yum install nanomsg-devel

This binding is complete; see nanomsg.hpp for further information.

=head2 DRM - http://dri.freedesktop.org/wiki/

If available, bindings for the direct rendering manager will be compiled.

    yum install libdrm-devel

This binding is partially complete; see xf86drmMode.hpp for information.

=head2 EGL - https://www.khronos.org/registry/egl/

If available, bindings for the EGL graphics standard will be compiled.

    yum install mesa-libEGL-devel

This binding is complete; see egl.hpp for further information.

=head1 BUILD PROCESS

Compile this file with autoreconf, producing a ./configure script

    autoreconf -i;

If this command fails, you've likely found a bug in the project. Please report
it, even if it's just dropping by via IRC.

Create a build directory (optional, but assumed here)

    mkdir build;
    cd build;

Run the output of this file, creating this project's Makefiles.

   ../configure --prefix=$HOME;

If this command fails, you have a missing dependency.  Look at this file
for a detailed listing of the prerequisites.

=head1 BUILD CONFIGURATION FILES

=head2 configure.ac

This is the Autoconf file for Luacxx and its underlying projects. It
provides the configuration for how to compile Luacxx itself. The language
this file is written is likely unfamiliar unless you have worked with the
Autotools, but the syntax is simple: it's little more than a macro language
to write shell scripts.

=head2 Makefile.am

This file contains the commands to implement Makefile targets like check
and run. It also included the src/Makefile.am.

This file can be updated to add new build targets (e.g. for new executables or
for other build processes).

=head2 src/Makefile.am

This file contains the listing of source files for each library and executable
produced by this project including the unit tests.

This file must be updated whenever source files are added or removed from the
project.

=head2 MAKE TARGETS

=head4 make lua

Runs a Lua interpreter with package.path and package.cpath set up to use this
repository's bindings and sources files.

=head4 make run

Runs the Luacxx demo.

=head4 make debug

Runs the Luacxx demo under gdb. When you are ready to run the application,
you will need to pass the location of the demo source code, like so:

    (gdb) r ../src/demo.lua

=head4 make valgrind

Runs the Luacxx demo under valgrind. This is useful for debugging memory
leaks and segfaults.

=head4 make check

Runs Luacxx's test suite.

=head4 make checkvalgrind

Runs Luacxx's test suite under valgrind.

=head4 make install

Installs Luacxx's executables and libraries to configure's --prefix.

For an install limited to your own home directory, ./configure --prefix=$HOME
would be sufficient. Note that pkg-config must be configured to include other
home-installed packages: on Fedora, appending the following to ~/.bashrc would
work:

    export PKG_CONFIG_PATH=$HOME/lib/pkgconfig

Followed by the build process

    ./configure --prefix=$HOME
    make
    make install

For a system-wide install on Fedora, ./configure --prefix=/usr would be
sufficient:

    ./configure --prefix=/usr
    make
    make install

If you wish to examine the files that will be installed, DESTDIR is a better
option than --prefix. DESTDIR will relocate files under a subtree without
affecting the paths used by Makefile variables. This target produces an
identical tree as what would be done without DESTDIR, but DESTDIR ensures that
the creation can take place at a safe location:

    # Same as a system-wide install
    ./configure --prefix=/usr
    make

    # ...but install to a temporary directory
    mkdir -p ~/tmp/luacxx
    make install DESTDIR=$HOME/tmp/luacxx

=head1 OPERATING SYSTEM SUPPORT

=head2 OSes that can build Luacxx without needing manually installed dependencies

Luacxx has been built using the following operating systems:

    Fedora 20 (Linux 3.14.8-200.fc20.x86_64 #1 SMP Mon Jun 16 21:57:53 UTC 2014 x86_64 x86_64 x86_64 GNU/Linux)

=head2 OSes that can build Luacxx with manually installed dependencies

None yet known.

=head2 OSes that can build Luacxx only with emulation

=head3 Microsoft Windows

Luacxx can be built using MinGW (and likely with Cygwin, though I haven't tried).

=head1 GETTING IN TOUCH

Send quick questions and comments to #luacxx on irc.freenode.net. For longer
questions or concerns, please email me at [email protected] I will answer
these as quickly as practical.

=head1 LICENSE

By default, this project uses the GNU General Public License, version 2, for
all code. Licensing exceptions are noted in each file where they occur

=head1 SEE ALSO

Lua 5.2 - http://www.lua.org/manual/5.2/manual.html

    Lua is an extension programming language designed to support general
    procedural programming with data description facilities.

Qt - http://qt-project.org/doc/qt-5/modules-cpp.html

    Qt is a cross-platform application and UI framework for developers.

=head1 ALTERNATIVES

LuaJIT - http://luajit.org/index.html

    LuaJIT is a Just-In-Time Compiler (JIT) for the Lua programming language.

tolua++ - http://www.codenix.com/~tolua/

    tolua++ is an extended version of tolua, a tool to integrate C/C++ code
    with Lua.

tolua - http://www.tecgraf.puc-rio.br/~celes/tolua/

    tolua is a tool that greatly simplifies the integration of C/C++ code with Lua.
    Based on a cleaned header file, tolua automatically generates the binding code
    to access C/C++ features from Lua.

Luabind - http://www.rasterbar.com/products/luabind.html

    Luabind is a library that helps you create bindings between C++ and Lua. It
    has the ability to expose functions and classes, written in C++, to Lua. It
    will also supply the functionality to define classes in lua and let them
    derive from other lua classes or C++ classes. Lua classes can override
    virtual functions from their C++ baseclasses.

lqt - https://github.com/mkottman/lqt

    lqt is a Lua binding to the Qt framework. It is an automated binding
    generated from the Qt headers, and covers almost all classes and methods
    from supported Qt modules.

QtLua - http://www.nongnu.org/libqtlua/

    The QtLua library aims to make Qt4/Qt5 applications scriptable using the
    Lua scripting language. It is an alternative to the QtScript module.

LGI - https://github.com/pavouk/lgi

    LGI is gobject-introspection based dynamic Lua binding to GObject based
    libraries. It allows using GObject-based libraries directly from Lua.

=head1 LICENSE

This project uses the MIT license unless otherwise noted. See LICENSE for exact
wording.
Issues
  • Can't build git HEAD

    Can't build git HEAD

    Hi, I'm receiving an error when building luacxx with gcc 4.9.1 or with clang 3.4.2 (with Qt 5.3.1). Both compilers fail on with the same error. The error message reported by clang is:

    Qt/QSurfaceFormat.cpp:26:21: error: no viable overloaded '=' mt["setOption"] = &QSurfaceFormat::setOption; ~~~~~~~~~~~~~~~ ^ ~~~~~~~~~~~~~~~~~~~~~~~~~~ Qt/../stack.hpp:375:7: note: candidate function (the implicit copy assignment operator) not viable: no overload of 'setOption' matching 'const lua::link<lua::index, const char *>' for 1st argument class link ^ Qt/../stack.hpp:413:17: note: candidate template ignored: couldn't infer template argument 'T' const link& operator=(T value) const; ^ Qt/QSurfaceFormat.cpp:38:22: error: no viable overloaded '=' mt["testOption"] = &QSurfaceFormat::testOption; ~~~~~~~~~~~~~~~~ ^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Qt/../stack.hpp:375:7: note: candidate function (the implicit copy assignment operator) not viable: no overload of 'testOption' matching 'const lua::link<lua::index, const char *>' for 1st argument class link ^ Qt/../stack.hpp:413:17: note: candidate template ignored: couldn't infer template argument 'T' const link& operator=(T value) const;

    Any clues?

    Thanks for the great project!

    opened by ghost 6
Owner
Aaron Faanes
Software engineer.
Aaron Faanes
A tool for generating cross-language type declarations and interface bindings.

Djinni Djinni is a tool for generating cross-language type declarations and interface bindings. It's designed to connect C++ with either Java or Objec

Dropbox 2.8k Jun 21, 2022
A lightweight, dependency-free library for binding Lua to C++

LuaBridge 2.6 LuaBridge is a lightweight and dependency-free library for mapping data, functions, and classes back and forth between C++ and Lua (a po

Vinnie Falco 1.3k Jun 21, 2022
ChakraCore is an open source Javascript engine with a C API.

ChakraCore ChakraCore is a Javascript engine with a C API you can use to add support for Javascript to any C or C compatible project. It can be compil

null 8.7k Jun 20, 2022
a one header library for creating Lua bindings to C++

Description A C++ library for generating Lua bindings. Supported features: functions, constructors, inheritance, member functions, properties, standar

null 76 Apr 3, 2022
lua-nuspell is a set of Lua 5.x bindings for Nuspell spellchecking C++ library.

lua-nuspell lua-nuspell is a set of Lua 5.x bindings for Nuspell spellchecking C++ library. About Nuspell Nuspell is a fast and safe spelling checker

AF 7 Mar 7, 2022
The Telegram Bot API provides an HTTP API for creating Telegram Bots.

The Telegram Bot API provides an HTTP API for creating Telegram Bots.

Telegram Library 1.6k Jun 25, 2022
Distributed (Deep) Machine Learning Community 677 Apr 14, 2022
SWIG bindings for raylib (to Lua, and hopefully other languages)

swigraylib SWIG binding for raylib This repo generates raylib bindings to other languages (eg. Lua), by providing a raylib.i SWIG interface file. SWIG

null 6 Oct 28, 2021
rlua -- High level bindings between Rust and Lua

rlua -- High level bindings between Rust and Lua

Amethyst Foundation 1.2k Jun 22, 2022
Rudimentary opinionated client-side lua libwayland bindings and scanner

wau This should work with Lua 5.3+. By default it builds with 5.3 instead of 5.4 because the examples depend on lgi. These aren't 1-to-1 bindings to l

null 4 Apr 18, 2022
๐Ÿ’‰ Source code for creating Lua executor

FiveM Lua Executor This is the ultimate great source code for building the best injectable Exec on FiveM. I'm not going to tell you how to create a pr

Achtzehn 33 Jun 26, 2022
LAppS - Lua Application Server for micro-services with default communication over WebSockets. The fastest and most vertically scalable WebSockets server implementation ever. Low latency C++ <-> Lua stack roundtrip.

LAppS - Lua Application Server This is an attempt to provide very easy to use Lua Application Server working over WebSockets protocol (RFC 6455). LApp

null 47 Apr 25, 2022
A dependency free, embeddable debugger for Lua in a single file (.lua or .c)

debugger.lua A simple, embedabble debugger for Lua 5.x, and LuaJIT 2.x. debugger.lua is a simple, single file, pure Lua debugger that is easy to integ

Scott Lembcke 571 Jun 28, 2022
The Lua development repository, as seen by the Lua team. Mirrored irregularly

The Lua development repository, as seen by the Lua team. Mirrored irregularly

Lua 5.7k Jun 23, 2022
Ziggified GLFW bindings with 100% API coverage, zero-fuss installation, cross compilation, and more.

mach/glfw - Ziggified GLFW bindings Ziggified GLFW bindings that Mach engine uses, with 100% API coverage, zero-fuss installation, cross compilation,

Hexops 155 Jun 25, 2022
Deno gl - WIP Low-level OpenGL (GLFW) bindings and WebGL API implementation for Deno.

deno_gl WIP Low-level OpenGL (GLFW) bindings and WebGL API implementation for Deno. Building Make dist directory if it doesn't exist. Build gl helper

DjDeveloper 14 Jun 11, 2022
Sol3 (sol2 v3.0) - a C++ <-> Lua API wrapper with advanced features and top notch performance - is here, and it's great! Documentation:

sol2 sol2 is a C++ library binding to Lua. It currently supports all Lua versions 5.1+ (LuaJIT 2.0+ and MoonJIT included). sol2 aims to be easy to use

The Phantom Derpstorm 3k Jun 23, 2022
Some C code I wrote while learning the Lua C API

Lua-C-API A personal repo where I push things while I'm learning the Lua C API! Feel free to contribute :) Building If you want to build this, you'll

Miqueas Martinez 6 May 13, 2022
log4cplus is a simple to use C++ logging API providing thread-safe, flexible, and arbitrarily granular control over log management and configuration. It is modelled after the Java log4j API.

% log4cplus README Short Description log4cplus is a simple to use C++17 logging API providing thread--safe, flexible, and arbitrarily granular control

null 1.3k Jun 17, 2022
The goal of arrowvctrs is to wrap the Arrow Data C API and Arrow Stream C API to provide lightweight Arrow support for R packages

The goal of arrowvctrs is to wrap the Arrow Data C API and Arrow Stream C API to provide lightweight Arrow support for R packages to consume and produce streams of data in Arrow format. Right now itโ€™s just a fun way for me to learn about Arrow!

Dewey Dunnington 28 Jun 15, 2022
Simple-MySQL-API is a free and easy API to manipulate MySQL with C99 and GCC compiler under GNU/Linux OS.

Simple-MySQL-API is a free and easy API to manipulate MySQL with C99 and GCC compiler under GNU/Linux OS.

Neptune 7 Apr 24, 2022
C++ (with python bindings) library for easily reading/writing/manipulating common animation particle formats such as PDB, BGEO, PTC. See the discussion group @ http://groups.google.com/group/partio-discuss

Partio - A library for particle IO and manipulation This is the initial source code release of partio a tool we used for particle reading/writing. It

Walt Disney Animation Studios 400 Jun 20, 2022
A tool for generating cross-language type declarations and interface bindings.

Djinni Djinni is a tool for generating cross-language type declarations and interface bindings. It's designed to connect C++ with either Java or Objec

Dropbox 2.8k Jun 21, 2022
๐ŸŽฎ C Bindings/Wrappers for Apple's METAL framework

Apple's Metal for C C Wrapper for Apple's METAL framework. This library is C bindings of Metal API (MetalGL). Since OpenGL is deprecated, this library

Recep Aslantas 103 Jun 13, 2022
๐ŸŽฎ C Bindings/Wrappers for Apple's METAL framework

Apple's Metal for C C Wrapper for Apple's METAL framework. This library is C bindings of Metal API (MetalGL). Since OpenGL is deprecated, this library

Recep Aslantas 103 Jun 22, 2022
RcppFastFloat: Rcpp Bindings for the fastfloat C++ Header-Only Library

Converting ascii text into (floating-point) numeric values is a very common problem. The fast_float header-only C++ library by Daniel Lemire does this very well, and very fast at up to or over to 1 gigabyte per second as described in more detail in a recent arXiv paper.

Dirk Eddelbuettel 18 May 2, 2022
ChakraCore bindings for aardio

ChakraCore-bindings-for-aardio ChakraCore is a Javascript engine with a C API you can use to add support for Javascript to any C or C compatible proje

null 9 Feb 18, 2022
HP-Socket bindings for aardio

HP-Socket-bindings-for-aardio HP-Socket is a high performance network framework. aardio is an extremely easy-to-use dynamic language, but it is also a

null 9 Jan 3, 2022
Godot bindings for the Rapier3D physics engine

Godot bindings for the Rapier3D physics library How to use There are two parts: A Godot module which must be compiled with the engine.

David Hoppenbrouwers 23 Jun 20, 2022