wxLua 2.8.10 - Installation Guide

This document describes how to build wxLua for use as an interpreter of Lua scripts and for embedding wxLua in a C++ project. You can build wxLua on many platforms with a variety of compilers. All the build settings and platforms that are supported by wxWidgets are supported by wxLua.

  1. Required libraries

    1. List of wxLua applications

    2. List of wxLua modules

  2. Building on Windows using makefiles

  3. Building on Windows using MSVC IDE

  4. Building on Linux/Unix

  5. Advanced building options

    1. Building a minimal set of wxWidgets wrappers

    2. wxLua libraries and linking order


1. Required libraries

wxLua is organized in three main blocks: applications (wxLua/apps), modules (wxLua/modules) and utilities (wxLua/utils). If you want to use wxLuaApp to write your applications in Lua using wxWidgets library then you are mainly interested in the applications (basically code editors with integrated Lua interpreter). If you want to integrate wxLua in your C++ project, then you are mainly interested in the modules, which are compiled as libraries which must be linked by your project:

1.a List of wxLua applications

1.b List of wxLua modules

In any case, the instructions below show how to compile all the three blocks (applications, modules, utilities) at once.

wxLua requirements are simple: wxWidgets (version 2.8.4 or higher), wxSTC if you want to use the wxbindstc module or you want to compile the wxlua application, wxStEdit (version 1.2.4 or higher) if you want to compile the wxluaedit application.

VERY IMPORTANT:

wxSTC is the wxWidgets wrapper around the Scintilla text control and can be built from the wxWidgets source tree...

If you want to disable wxSTC dependency you have to use the USE_WXBINDSTC=0 option (on Windows makefiles) or --disable-wxbindstc option (with Unix configure script).

wxStEdit is part of the wxCode project and can be downloaded from wxcode.sourceforget.net. Refer to its README for instructions on how to build it. If you want to disable wxStEdit dependency you have to use the USE_WXLUAEDITAPP=0 option (on Windows makefiles) or --disable-wxluaedit-app (with Unix configure script).


2. Building on Windows using makefiles

Enter the wxLua/build/msw directory with an MSDOS prompt and type:

to build all modules, applications and utilities of wxLua.

For more options, you can just see the top of the makefile you're using for your compiler. For example, if you're using nmake (MS Visual C nmake program) look at makefile.vc.

At the top you'll see something like this:

# -------------------------------------------------------------------------
# These are configurable options:
# -------------------------------------------------------------------------

# C compiler
CC = cl

# C++ compiler
CXX = cl

# Standard flags for CC
CFLAGS =

# Standard flags for C++
CXXFLAGS =

# Standard preprocessor flags (common for CC and CXX)
CPPFLAGS =

# Standard linker flags
LDFLAGS =

# Builds in debug mode [debug,release]
BUILD = debug

# Builds in Unicode mode [0,1]
# 1 - Unicode
UNICODE = 0

# Builds in shared mode [0,1]
# 1 - DLL
SHARED = 0

# Use DLL build of wx library? [0,1]
# 0 - Static
# 1 - DLL
WX_SHARED = 0

# Version of the wx library to build against.
WX_VERSION = 28

# Use monolithic build of wxWidgets? [0,1]
# 0 - Multilib
# 1 - Monolithic
WX_MONOLITHIC = 0

# The directory where wxWidgets library is installed
WX_DIR = $(WXWIN)

# Should the wxLua applications be compiled ? [0,1]
USE_APPS = 1

# Should wxLua use the system-wide Lua library ? [0,1]
USE_SYSTEM_LUA = 0

# The path to the Lua library
LUA_DIR = ..\..\..\modules\lua

# This is an advanced option. Handle with care.
# Version of C runtime library to use. You can change this to
# static if SHARED=0, but it is highly recommended to not do
# it if SHARED=1 unless you know what you are doing. [dynamic,static]
RUNTIME_LIBS = dynamic

# Do the wxLua bindings for the wxAdv lib need to be compiled ? [0,1]
USE_WXBINDADV = 1

# Do the wxLua bindings for the wxAUI lib need to be compiled ? [0,1]
USE_WXBINDAUI = 1

# Do the wxLua bindings for the wxBase lib need to be compiled ? [0,1]
USE_WXBINDBASE = 1

# Do the wxLua bindings for the wxCore lib need to be compiled ? [0,1]
USE_WXBINDCORE = 1

# Do the wxLua bindings for the wxGL lib need to be compiled ? [0,1]
USE_WXBINDGL = 1

# Do the wxLua bindings for the wxHTML lib need to be compiled ? [0,1]
USE_WXBINDHTML = 1

# Do the wxLua bindings for the wxMedia lib need to be compiled ? [0,1]
USE_WXBINDMEDIA = 1

# Do the wxLua bindings for the wxNet lib need to be compiled ? [0,1]
USE_WXBINDNET = 1

# Do the wxLua bindings for the wxRichText lib need to be compiled ? [0,1]
USE_WXBINDRICHTEXT = 0

# Do the wxLua bindings for wxSTC need to be compiled ? [0,1]
USE_WXBINDSTC = 1

# Do the wxLua bindings for wxXML need to be compiled ? [0,1]
USE_WXBINDXML = 1

# Do the wxLua bindings for wxXRC need to be compiled ? [0,1]
USE_WXBINDXRC = 1

# Does the wxLua debug support need to be compiled ? [0,1]
USE_WXLUADEBUG = 1

# Does the wxLua debug socket support need to be compiled ? [0,1]
USE_WXLUASOCKET = 1

# Compile the lua module ? [0,1]
USE_LUAMODULE = 1

# Compile the wxLua app ? [0,1]
USE_WXLUAAPP = 1

# Compile the wxLuaCan app ? [0,1]
USE_WXLUACANAPP = 1

# The path to the wxStEdit component (meaningful only when USE_WXLUAEDITAPP==1)
WXSTEDIT_DIR = $(WXSTEDIT)

# Compile the wxLuaEditor app ? [0,1]
USE_WXLUAEDITAPP = 0

# Compile the wxLuaFreeze app ? [0,1]
USE_WXLUAFREEZEAPP = 1


To specify one or more options, just append them to the end of your make command:

nmake -f makefile.vc BUILD=debug UNICODE=1 WX_MONOLITHIC=1

in case you get an error complaining about wx/setup.h or wx/wx.h which cannot be found, this is because the options default or the option values you gave did not match any of your available wxWidgets builds. In this case use one of BUILD, UNICODE, SHARED, WX_DIR, WX_SHARED, WX_VERSION, WX_MONOLITHIC options to select the build you want.
You can set these environment variables in MS Windows either at the DOS prompt using "set WXWIN=\path\to\wxWidgets" or by right clicking on "My Computer" -> "System" -> "Environment Variables" and add it for yourself or for everyone.

Note that the USE_WXLUAEDITAPP option is disabled by default so that if you want to enable wxStEdit dependency you have to explicitely use the USE_WXLUAEDITAPP=1 option.

Some useful targets you can specify are:


3. Building on Windows using MSVC IDE

Open the wxLua/build/msw/wxLua.dsw project file and select the same configuration you used to build wxWidgets from the "Build->Set Active Project" menu.

Now build the wxLua application right-clicking on the app_wxlua target and choosing Build (or Generate). Then just repeat this build command for the app_wxluacan and app_wxluaedit targets. the mod_XXX targets will be automatically built since they are dependency of the app_XXX targets. You may also use "Batch Build" to build multiple libraries and programs at once.

In order to compile the wxLuaEdit application you must compile the wxStEdit library by using its project file with the same settings that you will use for wxLua. Then set the environment variable WXSTEDIT=/path/to/wxstedit by right clicking on "My Computer" -> "System" -> "Environment Variables" and add it for yourself or for everyone. You will have to close and reopen MS Visual Studio in order for the new variable to be used.


4. Building on Linux/Unix

Quickstart: Move to the root directory of the wxLua project and type:

./configure && make

to build using the wxWidgets default build settings and then execute, with root permissions (you can use su or sudo commands...):

make install

If you want more control over configure you can type ./configure --help to get a list of available options.
Note that --enable-XXX or --enable-XXX=yes enables the option and --disable-XXX or --enable-XXX=no disables it.

wxLua's configure tries to determine the wxWidgets build settings automatically using the wx-config script, but if you have multiple wxWidgets builds (you can list them using wx-config --list) you can select the build you want using the --enable-unicode, --enable-debug and --with-wxshared, --with-gtk|msw|mgl|x11|motif options. Note that you would use the --enable-unicode, --enable-debug options only if you had built wxWidgets with them. The build settings for wxLua must be identical to the ones used by wxWidgets, i.e. you cannot build wxLua in ANSI mode and try to link to a Unicode build of wxWidgets! For example, if you have a unicode, release, shared library (as opposed to static) build of wxWidgets and want to build wxLua in unicode, release, static mode, then you can do:

./configure --enable-unicode --disable-debug --disable-shared --with-wxshared

The options --enable-wxlua-app, --enable-wxluacan-app, --enable-wxluaedit-app let you to enable or disable compiling the applications which are part of wxLua.

The options --enable-wxbindstc, --enable-wxluadebug, --enable-wxluasocket let you to enable or disable compiling the wxLua modules.

You can compile multiple coexisting wxLua builds by running wxLua's configure script in different folders; e.g.

mkdir mybuild && cd mybuild && ../configure && make

which puts all objects and intermediate stuff in the mybuild folder (exactly as you can do with wxWidgets). This is typically a good idea even if you only have a single build so you don't pollute the main wxLua directory with the build files.

If you do not want to install wxLua to the system directory /usr/ you can specify --prefix=/path/to/install/to and when you run make install the headers, apps, and libs will be placed there. For development purposes it is often not necessary to install wxLua, but you may need to specify the shell environment variable LD_LIBRARY_PATH to allow the executables to find the shared libraries, e.g. export LD_LIBRARY_PATH=/path/to/wxLua/lib, be careful not to override the variables existing value so you may want to instead do export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/wxLua/lib.

The wxLuaEdit application depends on the wxStEdit library that you should have compiled before trying to compile wxLua. There are two ways to let wxLua's configure find the wxStEdit library: 1) Set the shell environment variable before running configure export WXSTEDIT=/path/to/wxstedit or 2) Use the --with-wxstedit-prefix=/path/to/wxstedit configure directive. As a last resort you can help wxLua's configure find wxStEdit or its libraries by exporting these environment variables:

export CPPFLAGS="-I/path/to/wxstedit/include"
export LDFLAGS="-L/path/to/wxstedit/lib"

Other useful targets which you can use are:

5. Advanced building options

These instructions are for C++ developers who want to use wxLua as a script interpreter in their own project. This means that you can write scripts to make your code simpler, load and run files on the fly, and allow users to more easily customize your program with their own Lua scripts.

5.a Building a minimal set of wxWidgets wrappers

In order to embed wxLua in your project, you will probably need the library from wxLua/modules/lua and wxLua/modules/wxlua at a minimum. With these two libraries you have the ability to start an interpreter and run straight Lua code in it using the wxLuaState class.

To get the ability to create wxWidgets objects and use the functionality of wxWidgets in Lua you will also need to build and link to the libraries in modules/wxbind. The bindings in modules/wxbind contain nearly all of the classes and functions in wxWidgets. They also contain the appropriate #if wxUSE_XXX statements and platform dependent __WXMSW/GTK/MAC__ checks that wxWidgets uses in its headers to ensure that no matter what platform or what type of build you use, the bindings will compile without errors (if they don't compile for your settings, please be sure to tell us on the wxlua-users mailing list).

NOTE: if you want all wxWidgets API wrapped and you don't care about size of the wxLua libraries, then you can just skip this section ! You will just need to link your program against the wxLua libraries which you built in step 2, step 3 or step 4. Just look at section 5.b for some tips about linking order.

In order to make wxLua libraries smaller, you just need to add to your project a file named wxluasetup.h (the name must be exactly that, all lowercase!) which should start as a copy of modules/wxbind/setup/wxluasetup.h. Once you have your custom wxluasetup.h you can edit it to your liking. The header file contains a number of wxLUA_USE_XXX #defines that are fairly self explanitory. By setting some of them to 0 you can block out large chunks of the bindings making them smaller.

NOTE: The functionalities of wxLua bindings will obviously be limited by your current wxWidgets build settings; i.e. if you did not built OpenGL support in wxWidgets you won't have it in wxLua!

Once you have created and edited wxluasetup.h you can build your wxBind custom library: on Windows, just open an MSDOS prompt and move in the wxLua/modules/wxbind/build directory and then launch a MAKE command using the WXLUASETUP_DIR option to tell the makefile the path to your custom wxluasetup.h and the WXLUABINDLIB_DIR option to tell the makefile where the custom wxBind library should be created:
On Unix/Linux, unless you used the --enable-customwxbind-install=no option, then the wxBind sources will be installed to PREFIX/src/wxbind as soon as you give the make install command.
Once you have them installed, just go in the PREFIX/src/wxbind/build folder and type:

make -f makefile.gnu WXLUASETUP_DIR=~/myproj/include WXLUABINDLIB_DIR=~/myproj/lib

and you will get your wxBind custom library compiled.

Last step: you just need to add to your project dependencies the custom wxBind library you've just created.
Next section helps you with linking order which can be a bit troubling with some compilers.

5.b wxLua libraries and linking order

The order in which you link to the wxLua libraries is important since some variable are initialized using variables from other libraries. You must always link to any binding library after (in terms of initialization) linking with the wxLua libraries.

NOTE: Many linkers actually link libraries in the opposite order in which they appear on the command line.

Thus the library order to give to the gcc linker is (last means initialized first):

wxbind... , wxbindcore ,wxbindbase, wxluasocket, wxluadebug, wxlua, lua, wxWidgets libs

Obviously you should remove the libraries you don't use (e.g. wxluasocket, wxluadebug) and use the decorated names for the others. The wxLua makefiles/IDE outputs the libraries following the same wxWidgets naming rule:

wxlua_$(WX_PORT_WITHVERSION)$(WXLIBPOSTFIX)_wxlua-$(WX_VERSION_MAJOR).$(WX_VERSION_MINOR)

where WX_PORT_WITHVERSION can be gtk2, msw, x11, etc; WXLIBPOSTFIX can be u, d, ud.


$Id: install.html,v 1.15 2009/05/24 05:34:14 jrl1 Exp $