a Lua instance addon
Copyright (c) Dan Wilcox 2011-2012
BSD Simplified License.
For information on usage and redistribution, and for a DISCLAIMER OF ALL WARRANTIES, see the file, "LICENSE.txt," in this distribution.
See https://github.com/danomatika/ofxLua and the Openframeworks Forum post for documentation
ofxLua is an Open Frameworks addon for running a Lua embedded scripting interpreter within an OpenFrameworks application. Using the luabind library, C++ functions and classes can be bound to the lua api allowing them to be called within a lua script. This is useful in separating the upper level logic from the lower level application and is utilized in numerous video games and applications.
In addition, ofxLua provides bindings for the OpenFrameworks API.
Lua combines simple procedural syntax with powerful data description constructs based on associative arrays and extensible semantics. Lua is dynamically typed, runs by interpreting bytecode for a register-based virtual machine, and has automatic memory management with incremental garbage collection, making it ideal for configuration, scripting, and rapid prototyping.
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.
OpenFrameworks is a cross platform open source toolkit for creative coding in C++
To use ofxLua, first you need to download and install Open Frameworks. ofxPdExample-beta.xcodeproj is developed against the latest version of Open Frameworks on github (007). OF0062 support will be forth coming.
Currently, ofxLua is being developed on Mac OSX. You will need to install Xcode from the Mac Developer Tools.
For Linux, makefiles are included.
The code should work on Windows, but requires Visual Studio and/or Codeblocks project files to be built. Also, you'll need to install Boost and add paths for luabind to find it.
Place ofxLua within a folder in the apps folder of the OF dir tree:
openframeworks/addons/ofxLua
If you are using a stable version (0062, 007, ...) of OpenFrameworks then you want to use a git tag of ofxLua for that version. You can select the tag in the Github "Current Branch" menu or clone and check it out using git.
For example, the following commands will clone ofxLua and switch to the OF 0062 tagged version:
git clone git://github.com/danomatika/ofxLua.git cd ofxLua git checkout 0062
The master branch of ofxLua will work with the current stable version of OpenFrameworks and can be considered relatively stable.
ofxLua includes the lua and luabind library source files. Luabind requires the Boost C++ libraries. Install Boost and include the header and search paths in your project.
See the Homebrew or Macports package managers for easy install.
The install command for Homebrew is:
brew install boost
This takes a looong time.
A precompiled Boost framework is included in lib/boost as compiling for arm is non-trivial. See Building Boost for iOS for more info.
Install the boost development library with your distro's package manager.
For example, in Ubuntu you can use apt-get in the terminal:
sudo apt-get install libboost-dev
The example projects are in the example & exampleIOS folders.
Open the Xcode project, select the "example-Debug" scheme, and hit "Run".
Open the Code::Blocks .cbp and hit F9 to build. Optionally, you can build the example with the Makefile.
To build and run it on the terminal:
make make run
To develop your own project based on ofxLua, simply copy an example project and rename it. You probably want to put it in your apps folder, for example, after copying:
openFrameworks/addons/ofxLua/example/ => openFrameworks/apps/myApps/example/
It must be 3 levels down in the openframeworks folder structure.
Then after renaming:
openFrameworks/apps/myApps/myLuaProject/
On Mac, rename the project in Xcode (do not rename the .xcodeproj file in Finder!): Long click on the project name in the project tree.
If you want to add ofxLua to another project, you need to make sure you include the following src files:
openFrameworks/addons/ofxLua/src/ofxLua.h openFrameworks/addons/ofxLua/src/ofxLua.cpp openFrameworks/addons/ofxLua/src/ofxLuaFileWriter.h openFrameworks/addons/ofxLua/src/ofxLuaFileWriter.cpp
and optionally
openFrameworks/addons/ofxLua/src/ofxLuaWrapper.h
On older Mac OSXs (pre 10.8), a header file which is included with the OS contains some macros which conflict with several lua macros. They can be renamed by setting this CFLAG:
-D__ASSERT_MACROS_DEFINE_VERSIONS_WITHOUT_UNDERSCORES=0
This is already set in the static lib Xcode project. See more details here.
luabind requires the header search path to the luadbind sources:
../../addons/ofxLua/libs/lua ../../addons/ofxLua/libs/lua/lua ../../addons/ofxLua/libs/luabind
and the header and library search paths to the Boost C++ libraries. See the Project.xconfig of the example project.
Include these src files:
openFrameworks/addons/ofxLua/src/ofxLua.h openFrameworks/addons/ofxLua/src/ofxLua.cpp openFrameworks/addons/ofxLua/src/ofxLuaWrapper.h
You also need to include the static library Xcode project for the lua and luabind libraries:
# mac os openFrameworks/addons/ofxLua/lib/luabind.xcodeproj # or ios openFrameworks/addons/ofxLua/lib/luabind-ios.xcodeproj
Finally you need to include the header and library search paths required by luadbind. The provided static library xcode project includes the /usr/local/lib and /usr/local/lib search paths (as used by the Homebrew package manager) to the luabind static lib target. You'll need to change these if Boost is installed to a different dir.
For iOS, you can simply use the included boost.framework in lib/boost/osx. Drag and drop the file form the Finder onto your XCode project tree under addons/ofxLua.
Instructions:
- right click and create a new group "ofxLua"
- drag ofxLua/src into "ofxLua"
-
- create a subgroup in ofxLua called "libs"
- drag the
ofxLua/libs/luaandofxLua/libs/luabindfolders into the "ofxLua/libs" subgroup - drag the
ofxLua/libs/luabindorofxLua/libs/luabind-iosXcode project into the "ofxLua/libs" subgroup, make sure the checkbox is checked for your project target in the add dialog box - under Target->Build Phases, add the static lib project to Target Dependencies and both the lua and luabind libs to Link Binary with Libraries
- under Targets->YourApp->Build->Header Search Paths (make sure All Configurations and All Settings are selected) add:
../../../addons/ofxLua/libs/lua../../../addons/ofxLua/libs/lua/lua../../../addons/ofxLua/libs/luabind- the path to the Boost headers (for Homebrew, it's
/usr/local/include)
- under Targets->YourApp->Build->Library Search Paths (make sure All Configurations and All Settings are selected) add the path to the Boost headers
Compile the example by running "make".
To use ofxLua in a new project, simply add ofxLua to the project's addons.make file.
Luabind bindings for the OF API can be found in src/bindings. The implementation is split into separate .cpp files to help keep compilation down to a reasonable degree (as opposed to using all headers).
Currently, it covers most of the api and leaves out things involving pointers. More specific documentation may come at a future date, but for now check the example scripts on usage.
To invoke them with ofxLua, simply include ofxLuaBindings.h & call:
#include "ofxLuaBindings.h"
...
lua.bind<ofxLuaBindings>;
If you don't need the bindings in your project, just remove the src/bindings folder from your project files.
Create a bindings file with a static class which maps your classes & functions to Lua. Then you call this binding after initing an instance of ofxLua.
It could be as simple as the following:.
MyCode.h, your custom code:
float myFunction(float aNumber);
class MyCoolClass {
public:
MyCoolClass();
MyCoolClass(float aNumber);
// member function
void doSomething();
// getter/setter
void setInt(int newInt);
int getInt();
// member variable, read/write
string aString;
};
MyBindings.h, your custom bindings:
#pragma once
#include "ofMain.h"
#include "ofxLua.h"
// your custom code
#include "MyCode.h"
class MyBindings {
public:
// static function called when binding
static void bind(ofxLua& lua) {
// creates bindings within the "my" namespace,
// you can use whatever module name you want
// except for "of" as it's used by the ofxLuaBindings
//
luabind::module(lua, "my") [
// make sure there is a "," after every definition,
// but no comma after the last definition
// this is bound to lua as "my.function()",
// again you can rename this to whatever
// you want but it's best practice to
// keep the names similar to the C++ names
//
def("function", &myFunction),
// this is a class bound to Lua,
//
// it's Lua constructor is coolClass = my.CoolClass()
// see also the member functions & member variable bindings,
// also getInt & setInt are combined into a property in Lua
// as "anInt"
//
// note: no comma's between member functions & property
// definitions, you will need a comma at the end of the
// class if you have any further definitions below it
//
class_<MyCoolClass>("CoolClass")
.def(constructor<>())
.def(constructor<float>())
.def("doSomething", &MyCoolClass::doSomething)
.property("anInt", &MyCoolClass::getInt, &MyCoolClass::setInt)
.def_readwrite("aString", &MyCoolClass:aString)
];
}
};
Now call this in your project after initing an ofxLua instance:
#include "MyBindings.h"
...
lua.init();
lua.bind<MyBindings>;
Note: You need to calls this every time you init an ofxLua instance as the bindings are cleared when the Lua state is cleared.
If everything is working, you should be able to call your bindings in lua:
aNumber = my.function(3.45)
-- class
coolClass = my.CoolClass() -- constructor
coolClass = my.CoolClass(1.23) -- constructor with float
-- note: use ':' not '.' to call class instance member functions
coolClass:doSomething()
-- properties are access with a '.'
coolClass.anInt = 10
coolClass.aString = "hello world"
See the ofxLuaBindings and the Luabind documentation for more information.
Since binding OF involves many more functions and classes than the example above, the ofxLuaBindings are split up into *.cpp files which are called by the main ofxLuaBindings.h file in order to cut down on compile times. You would only need to do this if you plan to have alot of bindings to add (say more than 20 functions or 10 classes, etc).
Do not open issues or bug reports if the problem is in writing your own bindings as this is all handled by the Luabind library. Be sure to search online for similar errors with "Luabind" as part of your search. More likely than not, it's an issue with your bindings and not with ofxLua which merely utilizes Luabind and lightly wraps Lua objects.
You can help develop ofxLua on GitHub: https://github.com/danomatika/ofxLua
Create an account, clone or fork the repo, then request a push/merge.
If you find any bugs or suggestions please log them to GitHub as well.
There are a number scripts in the scripts folder which are used to update the various libraries (lua, luabind, and boost for iOS) used by ofxLua. Try editing the version setting in the script header and running the script to download new sources or, in the case of boostoniphone, build a new framework.
This usually occurs when the trying to bind a function that takes more then 10 arguments. You can change this upper limit using a define when building the luabind lib: LUABIND_MAX_ARITY.
Luabind has been updated to build with clang (aka LVMM) in Xcode, so this should not be an issue. See this Github issue for details.
With older versions of ofxLua:
If you get a reference to 'object' is ambiguous error at compile time in Xcode, you need to change the compiler from clang to gcc for the luabind static library project. See the Luabind user forum for more details.
This is set by default in the luabind static library project file.