-
Notifications
You must be signed in to change notification settings - Fork 23
C++11 API for creating Lua bindings
License
dafrito/luacxx
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
=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 dafrito@gmail.com. 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.
About
C++11 API for creating Lua bindings
Topics
Resources
License
Stars
Watchers
Forks
Releases
No releases published
Packages 0
No packages published