README.md
1Luabind
2=======
3
4[](https://travis-ci.org/Oberon00/luabind)
5
6Luabind is a library that helps you create bindings between C++ and Lua. It
7has the ability to expose functions and classes, written in C++, to Lua. It
8will also supply the functionality to define classes in lua and let them
9derive from other lua classes or C++ classes. Lua classes can override virtual
10functions from their C++ baseclasses. It is written towards Lua 5.x, and does
11not work with Lua 4.
12
13It is implemented utilizing template meta programming. That means that you
14don't need an extra preprocess pass to compile your project (it is done by the
15compiler). It also means you don't (usually) have to know the exact signature
16of each function you register, since the library will generate code depending
17on the compile-time type of the function (which includes the signature). The
18main drawback of this approach is that the compilation time will increase for
19the file that does the registration, it is therefore recommended that you
20register everything in the same cpp-file.
21
22Luabind is released under the terms of the [MIT license][1].
23
24> Copyright Daniel Wallin, Arvid Norberg 2003.
25> Extracted from <http://www.rasterbar.com/products/luabind/docs.html>
26
27[1]: http://www.opensource.org/licenses/mit-license.php
28
29
30This fork
31---------
32
33I forked the project since it seems abandoned (latest commit from January 2012
34on the 0.9 branch) and I ran into certain bugs which needed fixing (see
35commits).
36
37This should actually have been forked from [rpavlik/luabind][rpavlik]: I
38cherry-picked most commits from there. Additionally, many commits from
39[fhoefler/luaponte][fhoefling] are incorporated (as the are in rpavlik's
40fork). Thus, feel free to do the same with my fork.
41
42[rpavlik]: http://github.com/rpavlik/luabind/
43[fhoefling]: http://github.com/fhoefling/luaponte
44
45In the following two sections, the improvements over the latest official
46luabind release (0.9) are described.
47
48### Fixed bugs ###
49
50* Destroyed objects now have their metatable unset. Previously, one could
51 easily cause segmentation faults and other undefined behavior by accessing
52 destroyed objects from luabinds `__finalize` or Lua 5.2's `__gc`. Now you
53 can simply check with `getmetatable(obj)`, and if you forget, you get an
54 ordinary, well defined Lua error instead. Commit [a83aa][c-destroy].
55* The Lua part of a `wrap_base` derived class randomly got lost after a few
56 garbage collection cycles due to errors in the implementation of the
57 internal `weak_ref` class. Credits for the fix go to Max McGuire who
58 [posted][mmg-fix] a fix on luabind-user in 2010. Commit [a3a400][c-weakref].
59* The error message displayed when a function could not be called from Lua
60 with the provided arguments sometimes only contained the function signatures
61 but not the actual error message. mrwonko's commit [9d15e0][c-errmsg] (and
62 previous).
63* Luabind did not work over shared library (DLL) boundaries on some
64 platforms. fhoefling's commit [a83af3][c-dll] and my minor improvement
65 [a8349d][c-dll2].
66* Calling `call_function` with a return type but not using it resulted in a
67 call to `std::terminate` if the called function produced an error and a
68 C++11 compliant compiler is used. Commit [81bdcb][c-noexpect].
69* Luabind failed to recognize Lua numbers correctly on MSVC x64. Commit
70 [c9582c][c-longlong].
71
72* Luabind failed to compile on g++ with Boost 1.49
73 (`BOOST_PP_ITERATION_FLAGS` problem). The first one I know to have fixed
74 this is [fhoefling][c-fh-gcc-ftbfs]. Commit [1aa80b][c-gcc-ftbsfs].
75* Luabind failed to compile on Clang. Commit [4555b2][c-clang-ftbfs].
76
77[c-destroy]: http://github.com/Oberon00/luabind/commit/a83aae710ccb5d4fad2d625e3c87008d450949cb
78[mmg-fix]: http://lua.2524044.n2.nabble.com/weak-ref-issue-patch-td7581558.html
79[c-weakref]: http://github.com/Oberon00/luabind/commit/a3a400e5fc5f31b5733ad0e595e7f5b474883174
80[c-fh-gcc-ftbfs]: http://github.com/fhoefling/luaponte/commit/085f2e06204d6b2710db127806cfa855fca17d79
81[c-gcc-ftbsfs]: http://github.com/Oberon00/luabind/commit/1aa80be0bb944e960919542b16c6a3a117a4cdb8
82[c-errmsg]: http://github.com/Oberon00/luabind/commit/9d15e0288261ef83b227a3151d8f2ac238ef3759
83[c-dll]: http://github.com/Oberon00/luabind/commit/a83af3c69a3cd6da5ba21ea5062205fa664e59d2
84[c-dll2]: http://github.com/Oberon00/luabind/commit/a8349dfd94bcc456af5dc4b1bf4f175875d8ae54
85[c-longlong]: http://github.com/Oberon00/luabind/commit/c9582cea44fd67301ee5940cf08ccf5ae8c90094
86[c-noexpect]: http://github.com/Oberon00/luabind/commit/81bdcb72aa6ef7b321e59416b77be65c3944d6a9
87[c-clang-ftbfs]: http://github.com/Oberon00/luabind/commit/4555b20f0553f073d9d9085a43174aea5f7abaa6
88
89### Added features ###
90
91* CMake replaces the broken Jamfile as build system (including installation
92 and test support).
93 A [`FindLuabind.cmake`][findluabind] file is also provided, as well as
94 [`FindLua52.cmake`][findlua52].
95* A bit of C++11 support:
96 + `std::shared_ptr` is supported as smart pointer through
97 [`luabind/std_shared_ptr_converter.hpp`][stdptr].
98 Commit [118f80][c-11-ptr].
99 + Scoped enums can be used with `enum_`.
100 + Basic rvalue reference support. fhoefling's commit [a83af3][c-11-rval].
101 + Support for `long long`. Commit [c9582c][c-longlong] (also for
102 pre-C++11 compilers supporting it).
103* A new (C++) function `set_package_preload` can be used to register a
104 (loader) function to be called only if it is `require`d from Lua. rpavlik's
105 commit [3502e9][c-preload].
106* Modules can now register everything to arbitrary tables
107 (`luabind::object`s). fhoefling's commit [dd4a16][c-table]. This plays
108 together very nicely with `set_package_preload`.
109* The modulo operator `%` can now be exported to Lua. rpavlik's commit
110 [855b4a][c-modulo] and the following.
111* `class_info` can now handle actual classes as arguments. Previously it could
112 handle only *objects* of luabind classes. rpavlik's commit
113 [c2ee1f][c-classinfo].
114
115[findluabind]: cmake/Modules/FindLuabind.cmake
116[findlua52]: cmake/Modules/FindLua52.cmake
117[stdptr]: luabind/std_shared_ptr_converter.hpp
118[c-11-ptr]: http://github.com/Oberon00/luabind/commit/118f808b068e93e78fc717749f757a2358b9a4af
119[c-11-rval]: http://github.com/Oberon00/luabind/commit/a83af3c69a3cd6da5ba21ea5062205fa664e59d2
120[c-classinfo]: http://github.com/Oberon00/luabind/commit/c2ee1f82598eb3ded6922e05decdcc7bb69a8d2a
121[c-preload]: http://github.com/Oberon00/luabind/commit/3502e9c7234daf1b12f6dc7f545d361d5cee105d
122[c-table]: http://github.com/Oberon00/luabind/commit/dd4a1695dcbabbe1541f229ff245178b0621cf0d
123[c-modulo]: http://github.com/Oberon00/luabind/commit/855b4afba0204d0ae6e8fbd251dfc71f4d84353e
124
125Additionally, the removal of many lines of death code, also unused (parts of)
126member variables and other minor improvements make luabind generally
127(a little bit) faster and less memory hungry.
128
129Many compiler warnings have also been fixed. The remaining (irrelevant) ones
130are silenced, so the build should be completely warning- (and of course
131error-)free on Clang, g++ and MSVC.
132
133This fork is fully source (API) compatible to the original luabind library,
134but not binary compatible.
135
136### A word on the branch names ###
137
138First I worked against the 0.9 branch but then decided to rename it to master,
139since it actually has become the master branch of development in this fork.
140The original master branch is now named old-master.
141
){kind=link}