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.

OF github repository

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/lua and ofxLua/libs/luabind folders into the "ofxLua/libs" subgroup
• drag the ofxLua/libs/luabind or ofxLua/libs/luabind-ios Xcode 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.

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.