This document describes how to build the wxLua libraries, editors, and interpreters. wxLua is written in C and C++ and can be built on MS Windows, Linux, and OSX with the Visual Studio, Borland, Watcom, MingW, and GCC compilers. Most of the build settings and platforms that are supported by wxWidgets are supported by wxLua.
Please see Building wxWidgets for information about building wxWidgets on a variety of platforms.
The wxStyledTextCtrl (wxSTC) library is a wrapper around the Scintilla text editor control and is required to build the wxlua and wxluaedit applications and the wxbindstc binding library.
wxWidgets < 2.9 Windows users can build the wxSTC library using the makefiles or the MSVC build files in contrib/stc/stc.
wxWidgets < 2.9 Unix/OSX users can use the Makefile in created in contrib/src/stc after you have run configure and have successfully built the main wxWidgets libraries.
wxWidgets >= 2.9 has wxSTC built in and there is no longer a wxWidgets/contrib directory.
Before attempting to compile wxLua you should be able to compile and successfully run at least one of the wxWidgets samples.
An external Lua development library may be used to build wxLua against your own Lua library as described below.
2 - Building wxWidgets
wxWidgets is fairly easy to build from its source code. You should build it yourself in MS Windows and in OSX using the instructions below, refering to the wxWidgets documentation as needed. In Linux, you can use the precompiled development distribution packages, if available, or build it yourself.
Do not checkout into a directory name with spaces to make your life easier.
2.2 - Build using Microsoft Visual Studio GUI
If you want to modify the default configuration, copy wxWidgets\include\wx\msw\setup0.h to wxWidgets\include\wx\msw\setup.h and adjust as desired.
The file should be automatically copied over, but in case you get a compiler error about not finding "wx/msw/setup.h" copy it by hand.
There are comments above each #define describing the setting.
However, you might want to compile wxWidgets and wxLua with the default settings at least once before trying more advanced settings.
For wxWidgets < 2.9 open wxWidgets\build\msw\wx.dsw (written for for MSVC 6) and allow MSVC to convert it for a newer version of MSVC if asked.
For wxWidgets >= 2.9 open the appropriate solution file wxWidgets\build\msw\wx_vc9.sln (for MSVC 2008 for example) or the one closest to the version of MSVC you use.
64-bit builds (MSVC > 6 only, the steps below are for MSVC 2008 and note that a default MSVC install does not install the 64-bit compiler, you must do a custom MSVC install)
Right-click on the main "Solution" to bring up the menu.
Select "Properties..." to get the properties dialog.
Select "Configuration Properties" on the left.
Then the "Configuration Manager..." button in the top-right to get another dialog.
Drop down the "Active Solution Platform" choice and select "x64" and copy settings from "Win32" and check "Create new project platforms."
The recommended build configurations are "Debug" and "Release" which build static libraries.
If you really want DLLs choose "Debug DLL" or "Release DLL". Remember to copy the wxWidgets DLLs into the wxLua bin dir or set the %PATH% environment variable to their directory.
The "Universal" configurations build wxWidgets with a "Universal" widget toolkit as opposed to native MS Windows widgets.
Note that this configuration has not been tested with wxLua extensively.
Either choose the desired "Solution Config" and "Solution Platform" from the toolbar and press the build button or right-click on the main solution and choose "Build Solution".
Or select the menu item "Build"->"Batch Build..." and check the projects you want built (note that you can sort the columns in MSVC >= 2008).
It is best to simply build ALL the wxWidgets libraries per configuration since you can choose to not link wxLua to them if you don't want them. This will guarantee that they're all built the same way as opposed to building a few now and deciding you want more later, but forgetting you changed setup.h in between... You'll end up with mismatched libs leading to very strange and hard to debug crashes.
For wxWidgets 2.8.x you will also need to open wxWidgets\contrib\build\stc\stc.dsw and build the Scintilla and wxStyledTextCtrl library for each configuration too.
Hopefully it will all build... You shouldn't have any problems if you don't modify the wx/msw/setup.h file too much.
2.3 - Build using MSVC NMake
Open a cmd.exe (DOS) prompt and cd wxWidgets\build\msw\
You need to setup the environment before running nmake.exe
For 32-bit Visual Studio 2008 run this
c:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars32.bat
For 64-bit Visual Studio 2008 run this
c:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\amd64\vcvarsamd64.bat
Where typically UNICODE=1 and BUILD=release would be appropriate.
Note that monolithic means that only a single DLL will be created which usually easier to work with, but wxLua can work with the non-monolithic libraries too.
You can run any and all of the commands above to build multiple configurations since the generated libs will not conflict with each other in the wxWidgets/lib directory.
For wxWidgets 2.8.x you will also need to cd wxWidgets\contrib\build\stc\ and run the exact same nmake.exe ... command to build the wxStyledTextCtrl lib.
2.4 - Build using MinGW
Download mingw-get-inst-20120426.exe or an appropriate newer version to automatically download and install a fully working system.
Run the installer and select "C Compiler," "C++ Compiler," "MSYS Basic System," and the "MinGW Developer Toolkit" at minimum.
It is probably best to install to a directory without a space in the name, typically c:\MinGW.
Open a cmd.exe (DOS) prompt and cd wxWidgets\build\msw\
Run set PATH=C:\MinGW\bin;%PATH% so that the compiler can be found.
Or optionally add to a system wide PATH environment variable to point to the C:\MinGW\bin directory.
Or use the MinGW shell and cd /c/path/to/wxWidgets/build/msw.
The MinGW shell has MinGW/bin PATH already set, but note that this shell is a Linux (Cygwin) shell rather than a DOS shell so it works a little differently.
If you are unfamiliar with Unix or Linux you should probably use the cmd.exe (DOS) prompt.
Briefly; use / forward-slashes instead of \ back-slashes for path separators.
Drives are accessed using /c/... or /d/... instead of c: or d:.
The build is configured by config.gcc, but don't edit it, rather override the default values of the variables on the make command line.
You can speed up compilation using multiple processors by adding the flag -jN, e.g. -j4 to use four processors.
Note that you may have to run make multiple times since you may initially get errors since the compilers are not synced.
For wxWidgets 2.8.x you will also need to cd wxWidgets\contrib\build\stc\ and run the exact same mingw32-make.exe ... command to build the wxStyledTextCtrl lib.
2.5 - Build using GCC in Linux
Install the wxwidgets and wxwidgets-devel prebuilt packages for your Linux distribution and you're done...
They may be called wxBase, wxGTK and wxBase-devel, wxGTK-devel.
Or install the required development packages needed to build wxWidgets yourself.
Below is a list for Fedora 15, but they should be named similarly on other distributions.
There are others, but hopefully they'llbe dependent on the packages below so you won't need to explicitly install them.
This enables most everything and you can adjust it as required.
Note that the configure script in the root wxWidgets source directory will generate the build files in the directory it is run from so do not run it in the root wxWidgets dir.
Review the output file, configure-gtk2ud.log, to find any problems.
On success, you can then run make -j4 (set 4 to the number of processors you have) to build wxWidgets.
The build settings are created in the shell script wx-config.
Run ./wx-config --prefix and ./wx-config --cxxflags and ./wx-config --libs to print the wxWidgets build settings.
You DO NOT NEED to run make install and in fact by setting --prefix=$PWD it would only be installed to the build directory where it already is.
If you must install it, adjust the --prefix directory as desired.
For wxWidgets 2.8.x you will also need to cd wxWidgets/build_gtk2ud/contrib/src/stc/ and run make to build the wxStyledTextCtrl lib.
Build a wxWidgets sample program as a sanity check, samples/widgets for example, cd build_gtk2ud/samples/widgets, run make, then ./widgets to execute it.
2.6 - Build using GCC in OSX
Install XCode which should install the command line GCC tools, the "app store" should have it.
You should use wxWidgets >= 2.9 on OSX, there is no good reason to use 2.8.x.
In the example below an OSX, Unicode, Debug build will be created, osx2ud.
Create a sub-directory in the wxWidgets directory for the build files.
You can create this directory anywhere, but it is convenient to keep it contained within the wxWidgets directory.
E.G. wxWidgets/build_osxud for a OSX, Unicode, Debug build.
Create a script in the build directory named configure-osxud.sh (or named appropriately) with this as its content :
This enables most everything and you can adjust it as required.
Note that the configure script in the root wxWidgets source directory will generate the build files in the directory it is run from so do not run it in the root wxWidgets dir.
Review the output file, configure-osxud.log, to find any problems.
On success, you can then run make -j4 (set 4 to the number of processors you have) to build wxWidgets.
The build settings are created in the shell script wx-config.
Run ./wx-config --prefix and ./wx-config --cxxflags and ./wx-config --libs to print the wxWidgets build settings.
You DO NOT NEED to run make install and in fact by setting --prefix=$PWD it would only be installed to the build directory where it already is.
If you must install it, adjust the --prefix directory as desired.
For wxWidgets 2.8.x you will also need to cd wxWidgets/build_osxud/contrib/src/stc/ and run make build the wxStyledTextCtrl lib.
Build a wxWidgets sample program as a sanity check, samples/widgets for example, cd build_osxud/samples/widgets, run make, then ./widgets to execute it.
3 - wxLua Components
wxLua has three components: applications (wxLua/apps), modules (wxLua/modules), and utilities (wxLua/utils). You should simply build them all.
3.1 - wxLua applications
wxLua/apps/wxlua
A wxLua code editor, interpreter, and debugger; runs an embedded copy of the Lua program samples/editor.wx.lua.
wxLua/apps/wxluaedit
Another wxLua code editor and interpreter, based on wxStEdit.
wxLua/apps/wxluafreeze
A simple program to execute Lua or wxLua programs that can be used as a replacement for the Lua executable that is capable of running wxLua apps.
wxLua/apps/wxluacan
An example of how to create a C++ application with an embedded wxLua interpreter.
3.2 - wxLua libraries
wxLua/modules/lua-5.1
Lua 5.1.x sources with patches applied.
wxLua/modules/lua-5.2
Lua 5.2.x sources with patches applied.
wxLua/modules/luamodule
A shared library (wx.so or wx.dll) for Lua code to call require("wx") to load the wxLua bindings.
wxLua/modules/luaproxydll
MS Windows only libraries that allow a staticly built lua.exe to look and act like the lua.dll shared library.
Briefly, a staticly built lua.exe contains all of the compiled Lua code and is a stand-alone application. A shared lua.exe would be linked to a lua.dll which would contain the code and so the lua.exe and lua.dll must be kept together or the lua.dll must at least be in the %PATH%.
The luaproxydll directory contains prebuilt shared libraries lua5.1.dll, lua51.dll, lua5.2.dll, and lua52.dll that when loaded by an application (lua.exe) simply points the load request back to the caller application itself to find the functions and symbols.
This allows the same static lua.exe to be used to as a convenient stand-alone application, but also as the lua.dll when calling require("wx") from Lua code.
Additionally, it simplifies the usage of prebuilt 3rd-party libraries which may be linked against Lua dlls with nearly any name. Simply make a copy of one of the appropriate luaproxydll file, lua51.dll or lua52.dll, and give it the name the 3rd-party library was originaly linked to.
Note that this does NOT give you license to mix and match libraries of different versions or that were compiled with different settings.
If the Lua library used to build wxLua is too different from the Lua library used to build the 3rd-party library you should expect your application to crash.
Ideally, you should compile wxLua and ALL 3rd-party libraries with the same compiler settings and against the EXACT SAME Lua library and its headers.
Use these proxy-dlls with 3rd-party libraries at your own risk and NO guarantee is made that they are suitable for any purpose...
They will, however, work perfectly with the wxLua compiled lua.exe and wx.dll.
wxLua/modules/wxlua
The base wxLua library, contains the wxLuaState class that wraps a lua_State and loads the bindings.
wxLua/modules/wxbind
The wxLua bindings for wxWidgets broken up by the wxWidgets libraries: adv, aui, base, core, gl, html, media, net, richtext, stc, xml, xrc.
To determine what classes are part of what libs you can use the wxluaref.html document and search for the class.
For example, class wxGrid is in the file wxadv_grid.i so it is part of the adv library.
wxLua/modules/wxluadebug
Classes for debugging Lua in C++; wxLuaCheckStack and wxLuaStackDialog.
wxLua/modules/wxluadebugger
Debugger socket classes to run a wxLua program in a separate process and communicate with the parent debugger.
3.3 - wxLua Utilities
wxLua/utilities/bin2c.lua
Lua script to convert any text file to a 'C' const char* string.
4 - Building wxLua
wxLua uses uses CMake as its build system. The CMakeLists.txt files describe how wxLua is to be built so that when CMake is run it can generate the appropriate build files for the compiler of your choice.
There is also a Makefile.wx-config in the root directory of the wxLua that can be used to build wxLua using GCC in Linux. It simply requires that the wxWidgets wx-config script is in the path to work. These files are kept as a backup, they work, but the CMake build is preferred since it is far more flexible.
In Linux you can typically install the CMake package that your Linux distribution provides.
Run the cmake-gui program.
Choose the compiler you wish to use, it should match the compiler wxWidgets was compiled with.
Select "Use default native compilers" unless you have some reason not to.
Select the root of the wxLua directory as the "Where is the source code" directory, it has the root CMakeLists.txt file in it and subdirectories of apps, art, bindings, modules, ....
Select a directory, perhaps named wxLua-build, at the same level as the wxLua/ directory for "Where to build the binaries."
The build directory can be anywhere, but ideally not the same as the wxLua source code directory since you may want to completely delete it.
If anything goes very wrong, consider deleting the build directory you created so you can start fresh.
If you drasticly change the CMake build settings after having compiled wxLua you should simply start with a new build directory. Everything will have to be rebuilt anyway and once the new settings are applied you can no longer clean the old files that have different names.
Choose the type of library you want, static or shared libs (DLLs), by setting the BUILD_SHARED_LIBS variable.
Typically this will match what your wxWidgets build is.
By default, a shared version of wxWidgets will be used if BUILD_SHARED_LIBS is TRUE, if available. See the build settings for particular compilers to choose the wxWidgets build you actually want.
Press the "Configure" button a few times.
Each time configure is run more variables are found and these appear in red, reconfigure until no more items are red.
There will probably be an error configuring the first time through, this is normal since it takes a few passes to figure things out.
If the error persists after a few configures adjust the settings to fix the problem.
Adjust the CMake variable wxWidgets_COMPONENTS to match what wxWidgets libraries you have and want to use.
Adjust the CMake variable wxLuaBind_COMPONENTS to match or have fewer libraries than the wxWidgets_COMPONENTS list.
Review the available settings in section 4.3 before continuing.
Skip to the section below that is appropriate for your compiler to complete the build process.
ALWAYS CONFIGURE CMAKE MORE THAN ONCE to ensure that wxWidgets is properly found and the wxLua settings are synced to it. This also applies to the command-line cmake configuration too. Double check the cmake output to ensure that wxLua will be built to your specifications.
4.3 - CMake Configuration Variables
Below are the CMake variables that you can and in some cases must adjust to build wxLua. If you want to run CMake from the command line you would specify these variables as : cmake -DBUILD_SHARED_LIBS=TRUE ...
Set the build for Debug, Release, Release with Debug Info, and Minimum Size Release (stripped).
This variable will not be shown in the CMake Gui when building with Visual Studio since you choose the build type in the MSVC IDE and you can build them all using the same CMake configuration.
For other compilers, you can only build one at a time so you will have to create a separate build directory for each different build type.
Do not try to change the build type in CMake and reuse the same build directory. It may work, but can cause problems, simply delete the current build dir or create a new one for the new build type.
The "wx/stedit/setup0.h" contains user defined setup information and needs to be copied to "wx/stedit/setup.h" where it can be modifed before compiling.
CMake takes care of the copying if wxStEdit_COPY_SETUP0_TO_SETUP_H is true and then this variable points to where it was copied to.
Only change this variable to point to your own copy if you need to modify the setup.h file, typically no changes are required.
wxWidgets_COMPONENTS=[semicolon separated list of wxWidgets library names]
wxWidgets has a number of components that are either built into separate libs (default build) or into a monolithic lib.
Therefore you either specify the desired separate libs or the monolithic lib. The GL and scintilla libs are always built separately.
The wxWidgets directory with the compiled libraries.
wxWidgets_ROOT_DIR="/path/to/wxWidgets"
The root dir of wxWidgets that has include/wx as a subdirectory.
wxWidgets_USE_REL_AND_DBG=[TRUE,FALSE]
Use both release and debug configurations.
You probably always want this checked if you have built both and you will not be able to check this if you do not have both a release and debug configuration in the wxWidgets lib dir.
wxWidgets_VERSION=[2.8.x,2.9.x]
In order to help find all the libs you may have to set this variable to the correct wxWidgets version as a hint to CMake.
This is because different wxWidgets versions have different libs and it is hard to tell if a lib is missing or if a different version is being used.
Linux and OSX configuration options
wxWidgets_CONFIG_EXECUTABLE=/path/to/wx-config
Set the path to the wx-config script that CMake can use to get everything it needs to know about the wxWidgets library.
4.4 - CMake with MSVC
To find wxWidgets you must set the CMake variable
wxWidgets_ROOT_DIR=/path/to/wxWidgets
Press "Configure," but it probably won't work just yet.
To find the libraries for wxWidgets (you may have compiled a variety of them) you must also set the variable
wxWidgets_LIB_DIR=/path/to/wxWidgets/lib/vc_lib
Where you must set vc_lib appropriately; vc_amd64 for 64-bit, vc_dll for DLLs, and vc_amd64_dll for 64-bit DLLs
Press "Configure" again, if it doesn't work set
wxWidgets_CONFIGURATION=[msw, mswu]
Press "Configure" again, if it doesn't work set
wxWidgets_VERSION=[2.8.x,2.9.x]
Where you will use the actual number, 2.8.12 or 2.9.4 for example.
If "Configure" still doesn't work, then something is wrong with your wxWidgets build... go back and fix it.
If "Configure" succeeds, the output window should say "Configuring done" and the log should have a complete description of your wxWidgets build.
Press "Generate" to have CMake write out the build files.
Open wxLua.sln in the build directory...
Choose the "Solution Configuration" (Debug, Release, MinSizeRel, RelWithDebInfo) that matches your wxWidgets build and build everything.
Note that you MUST have built wxWidgets in debug for a wxLua Debug build, but a wxWidgets release build works with a wxLua Release, MinSizeRel, RelWithDebInfo build.
All the apps are put into build\bin\Debug or Release, MinSizeRel, RelWithDebInfo as appropriate.
Right-click on "wxLua_app" and select as "Startup project" and press the "Start Debugging" program to run it in the GUI... etc.
If you built as a DLL using the wxWidgets DLLs you will have to either have the wxWidgets DLLs in you PATH environment variable or copy them into the same directory as the wxLua executables.
If you run a program and it silently closes with no error you can open a cmd.exe (DOS) prompt and run it there and, if you're lucky, an error message about a missing DLL will be printed to the console.
4.5 - CMake with MinGW
See the section above titled Build using MinGW for more information about getting and using MinGW.
Choose the CMAKE_BUILD_TYPE that you want.
Note that you MUST have built wxWidgets in debug for a wxLua Debug build, but a wxWidgets release build works with a wxLua Release, MinSizeRel, RelWithDebInfo build.
To find wxWidgets you must set the variable
wxWidgets_ROOT_DIR=/path/to/wxWidgets
Press "Configure," but it probably won't work just yet.
To find the libraries for wxWidgets (you may have compilied a variety of them) you must also set the variable
wxWidgets_LIB_DIR=/path/to/wxWidgets/lib/gcc_lib
Where you must set gcc_lib appropriately; gcc_dll for DLLs.
Press "Configure" again, if it doesn't work set
wxWidgets_CONFIGURATION=[msw, mswu]
Press "Configure" again, if it doesn't work set
wxWidgets_VERSION=[2.8.x,2.9.x]
If "Configure" still doesn't work, then something is wrong with your wxWidgets build... go back and fix it.
If "Configure" succeeds, the output window should say "Configuring done" and the log should have a complete description of your wxWidgets build.
Press "Generate" to have CMake write out the build files.
Open a cmd.exe prompt to run mingw32-make.exe help to display all the available targets.
If you run mingw32-make.exe with no parameters you will build everything, which is probably best.
All the apps are put into build\bin\Debug or Release, MinSizeRel, RelWithDebInfo as appropriate.
4.6 - CMake with GCC in Linux or OSX
Choose the CMAKE_BUILD_TYPE that you want.
Note that in Linux you can mix and match Release and Debug versions.
To find wxWidgets you must set the variable
wxWidgets_CONFIG_EXECUTABLE=/path/to/wx-config
See above about building wxWidgets for Linux for a description of it.
Press "Configure" and the output window should say "Configuring done" and the log should have a complete description of your wxWidgets build.
Press "Generate" to have CMake write out the build files.
Open a terminal, change into your wxLua build dir and run make help to display all the available targets.
If you run make with no parameters you will build everything, which is probably best.
All the apps are put into build\bin\Debug or Release, MinSizeRel, RelWithDebInfo as appropriate.
You can run all the apps without installing them.
5 - Advanced Building
These instructions are for developers who wish to customize wxLua's wxWidgets bindings or for those who want to use wxLua as a script interpreter in their own C++ project.
5.1 - Building a minimal set of wxWidgets wrappers
The functionality of wxLua's wxWidgets bindings are limited by your wxWidgets build settings; i.e. if you built wxWidgets with wxUSE_TIMER=0 then you will not be able to use the wxTimer class in wxLua.
If you want all of the wxWidgets API that's available in your wxWidgets build wrapped by wxLua, simply build wxLua using the directions above, no modifications required.
On the other hand, if you wish to make the wxLua bindings smaller, you will need to set the CMake variable wxLuaBind_WXLUASETUP_DIR to point to the directory of a customized wxluasetup.h header which should start as a copy of modules/wxbind/setup/wxluasetup.h. It is best to copy it to a new directory instead of modifying the original one. This way you will have the original as a backup to compare your changes to.
The wxluasetup.h 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 wxWidgets bindings making the library smaller.
Be careful about which parts you remove since you can badly cripple your ability to create and use higher-level objects if you disable the lower-level parts they rely on. Though, this may be your goal, some experimentation may be required.
Once you have created and edited your wxluasetup.h you can build your custom wxLuaBind library following the directions above.
5.2 - Embedding wxLua into a C++ Application
In order to embed wxLua in your project, you will need the wxLua/modules/lua and wxLua/modules/wxlua libraries 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 enable creation and use of wxWidgets objects in Lua you will also need to build and link to the libraries in modules/wxbind. The wxWidgets bindings contain the appropriate #if wxUSE_XXX statements and platform dependent #ifdef __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 ).
5.3 - wxLua libraries and linking order
The order in which you link to the wxLua libraries is important. 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. This means that the libraries that are first in the linker list are initialized last.