LuaBinaries
Pre-compiled Lua libraries and executables.

Using LuaBinaries

LuaBinaries can be used in a variety of ways, depending on your needs. You can use the standalone interpreter to run Lua scripts and load external modules, you can use LuaBinaries to embed Lua in your application or to dynamically load Lua/C modules into your application.

Final User - Using the Standalone Interpreter

The executable packages available for download include the standalone Lua interpreter that can load modules using require or directly load dynamic libraries using the Lua function loadlib.

In Windows, the loaded modules and libraries must follow the LuaBinaries for Windows Compatibility documentation. Also there are two Lua executables, one that is console based (lua52.exe) and one that is a Windows application with no console output (wlua52.exe). To use wlua interactively you must load a GUI module to create and manage windows and dialogs.

The Lua for Windows distribution already includes many useful modules following this specification and includes the LuaBinaries executables and DLLs (also includes and stub libraries for developers).

The Lua Rocks system deploys modules that follow this specification in Windows and UNIX.

Application Developer - Embedding Lua in your Application

Usually you will follow the same parameters we use to build the standalone interpreter. See the Configuration documentation.

In Windows, you should use the dynamic libraries or you will not be able to dynamically load modules. And to ensure that standard modules can be successfully loaded, the applications must also follow the LuaBinaries for Windows Compatibility documentation.

In UNIX, you can use the dynamic or the static libraries. But when using the static libraries remember to include the parameter "-Wl,-E" in Linux to make the application exports the Lua functions, so the loaded modules are not dependent on the LuaBinaries dynamic libraries.

Module Developer - Using Lua as an External Module of an Existing Application

External modules or components are implemented using dynamic libraries. Considering that you are going to build modules compatible with the above applications then there are a few rules to follow.

In UNIX, you should not add a dependency link with the LuaBinaries dynamic libraries, leave that to the executable that will be exporting the Lua functions. The parameter -fPIC can be used or not. The compatibility of the module dynamic library binary depends on the version C run time library used, usually glibc.

In Windows, you must follow the LuaBinaries for Windows Compatibility documentation.

You should also consult the Building Modules page written by Mike Pall about how to build C extension modules for Lua.

LuaBinaries for Windows Compatibility

In Windows your library or application must be linked with a stub library. A stub library is a library with only the function declarations that will bind your DLL with the Lua DLL. The LuaBinaries DLL is called "lua52.dll".

The C Run Time Library

In Windows, as in UNIX, the modules depend on the C run time library. But in UNIX, for the same system version/release, the libc is usually the same and modules build for that system are compatible and do not have to worry about variations in the run time library. In other words, libc changes usually occur in different versions/releases of the system. That's why there are many different binaries for the same UNIX flavor in the LuaBinaries downloads.

In Windows, there are less variations of the system but each compiler has its own version of the C run time library, each one with different names. That's why also LuaBinaries downloads have many different binaries packages for Windows.

The LuaBinaries executables for Windows are distributed as a single package so they must use only one run time library.

Notice that this affects only the users who want to build compatible modules, or use compatible modules made by others. The DLLs for all the run time libraries we support will remain available for download and use.

For Lua 5.2 and Lua 5.3

We choose the MingW gcc 4 compiler to build the LuaBinaries executables.

So despite the known MSVCRT.DLL problems we decided to use it. On the other hand it is already installed on the system and MingW supports it, so maybe this could make things easier for our users and including Lua for Windows users.

The Visual C++ 8 MSVCR80.DLL was hard to be used because of two factors: its installation and the need of a manifest file to build the user modules.

For Lua 5.1

We choose the Visual C++ 8 compiler to build the LuaBinaries executables.

Up to Visual C++ version 6, the C run time library was called "msvcrt.dll" and this DLL is today included in all modern Windows systems (W2K, WinXP, Vista and 7). But for Visual C++ 8, Microsoft released a free version of the compiler called "Express". We consider that an important step for developers using LuaBinaries DLLs. Also It is know that "msvcrt.dll" has some problems and limitations, particularly with multi-threading. So we decided to move to Visual C++ 8 version for which the C run time library is called "msvcr80.dll".

If you want to use another compiler or another version of Visual C++ you may mix run time libraries, this is safe if you do not use structures across different run times, see the MSDN article "Potential Errors Passing CRT Objects Across DLL Boundaries".

So your module DLL or application EXE must link with the stub library made for Visual C++ 8 (Visual Studio 2005), that it is distributed in the LuaBinaries "dll8" package for 32 bits or in the "dll8_64" package for 64 bits.

The LuaBinaries DLL packages have a dll proxy called "lua51.dll". It can be used to replace other "lua51.dll" released by other distributions. It will simply forward calls to the "lua5.1.dll". There is no compiled source code involved in the forwarding.

Notice that MingW can generate DLLs with different MSVCR*.DLL dependencies. To generate an import library for MingW just run (you will need the LuaBinaries source code to obtain the "lua5.1.def" file):

dlltool -d lua5.1.def -D lua5.1.dll -l liblua5.1.a

The MSVCR80 Installation for Lua 5.1

One problem that rises when using the Visual C++ 8 C run time library is that it is not installed on the system. But you can redistribute it with your application. It can be in a folder called "Microsoft.VC80.CRT" on the same folder of the executable or it can be installed by the redistributable package provided at "Microsoft Visual C++ 2005 SP1 Redistributable Package (x86)" or "Microsoft Visual C++ 2005 Redistributable Package (x64)". To install the packages you will need administrative privileges. The Visual C++ 2005 used to compile LuaBinaries has the Service Pack 1 applied.

The LuaBinaries executables includes the folder "Microsoft.VC80.CRT" so you can use it in systems that do not have the redistributable package installed and it will not conflict with systems that have the package installed.

The Lua for Windows distribution already includes the redistributable package.

$Id: manual.html,v 1.3 2011/12/02 17:23:41 scuri Exp $ l