Home
The place to start.

Development
Software development links, free utilities, source code, product reviews and more.

Products
Product information, downloads and purchasing information.

Contact/About
Who's behind this site and how to contact them.

What's New
All of the latest news and articles.

Community
An open forum to discuss Icy North products or site content.

Making a Lua 5.0 Extension DLL with lcc-win32

Brett Kapilik
Tuesday, August 30, 2005

Introduction

This tutorial will show you how to make a Lua 5.0 extension DLL (sometimes called a "module") using the free lcc-win32 compiler. Note that the lcc-win32 compiler is free only for non-commercial purposes. They also sell commercial licenses. Please see the lcc-win32 web site for licensing details.

Get lc-win32

Go to http://www.cs.virginia.edu/~lcc-win32 and download and install the lcc-win32 compiler system.

Start a New Project

Once installed, start the lcc-win32 editor (usually it is installed to "c:\lcc\bin\wedit.exe"). Then start a new project by selecting Project > Create... from the menu. This will open the "Definition of a new project" dialog. Fill in the following values:

Note: Make sure that the project's folder exists before clicking the Create button. For example, in the example above, "c:\projects" must first exist.

Once your values are in press the Create button. You will see a dialog:

Click "Yes" and then on the "Application characteristics" dialog, click "OK" to accept the defaults. Next you will see the "Compiler settings" dialog. Click "Next" to accept the defaults. On the "Linker settings" dialog click "Next" to accept the defaults. On the "Debugger settings" dialog click "Finish" to accept the defaults and complete the wizard.

You should now have a project with a file with the one file in your project open.

To confirm that your project is setup correctly, build the DLL by selecting Compiler > Make from the menu. It should quickly build and then say "myluadll.dll built successfully." in the build window at the bottom of the compiler environment. Congratulations - you now have a fully-functional DLL that does nothing! Your DLL will be located at: "C:\projects\MyLuaDLL\lcc\myluadll.dll".

Just Add Lua

The next step is to include the Lua 5.0 engine in your project. You can download and compile the Lua binaries yourself from http://www.lua.org if you wish. Beware that some of the Lua binaries available may not link properly with the lcc-win32 compiler. For your convenience, I have compiled the Lua files into a static library with lcc-win32:

Download lua50-lcc-win32.zip

The rest of this tutorial will assume that you have downloaded the above Lua distribution. If you are using the Lua DLL version then you will need to adjust accordingly. I prefer statically linked libraries in order to keep things self-contained.

Now unzip the contents of the lua50-lcc-win32.zip file to the project directory ("C:\projects\MyLuaDLL") so that you now have a directory structure that looks someting like this:

To add the files to the project select Project > Add/Delete Files... from the menu. This will open the "Source files for project myluadll" dialog. Click the "Add new file" button. On the file browse dialog choose "All" in the "Files of type" field. Now you should see the Lua files that you added to your folder. Select the files "lua.h", "lualib.h", "lauxlib.h" and "lua50lccwin32static.lib" and then click the "Open" button.

You should now see:

Click OK to close that screen. The lua files are now part of your project. If you compile now (Compiler > Make) you will notice that it says "cannot open lua50lccwin32static.lib". To fix this, select Project > Configuration to open the "Configuration of Wedit" dialog. Select the Linker tab and then change the "Additional files to be included in the link" from "lua50lccwin32static.lib" to the fully-qualified path: "C:\projects\MyLuaDLL\lua50lccwin32static.lib" and then click OK. If it asks you to "Rebuild the make file?" select Yes. You should now be able to re-build (Compiler > Make) and it should compile with no errors.

The next step is to include the lua header files in your myluadll.c file. To do this, put these lines of code after the line that says "#include <windows.h>":

#include "lua.h"
#include "lualib.h"
#include "lauxlib.h"

The last thing we need to do to get all setup is to change a linker setting so the linker will not decorate the exported function names. To do this, select Project > Configuration and then go to the Linker tab. Check the option "Do not include underscores in DLL exports" and then click OK.

Do Something, Already!

OK, now you are ready to add some functionality to your DLL. Add the following text to the end of the myluadll.c file:

static int MyLuaDLL_HelloWorld(lua_State* L)
{
	MessageBox(NULL,"Hello","World",MB_OK);
	return 0;
}

static const luaL_reg MyLuaDLLFunctions [] =
{
	{"HelloWorld",MyLuaDLL_HelloWorld},
	{NULL, NULL}
};

int __cdecl __declspec(dllexport) luaopen_MyLuaDLL(lua_State* L)
{
	luaL_openlib(L, "MyLuaDLL", MyLuaDLLFunctions, 0);

	return 1;
}

I am not going to go into detail about what the above code does. You can read more about that on the Lua web site, the Lua manual (especially the C API part) and in the great book Programming in Lua or on the Lua wiki. If you have any specific questions that are not answered there ask them in the Icy North forums.

You should now be able to compile the DLL with no errors. To test the DLL from a Lua project, use the following Lua code:

local testlib = loadlib("C:\\projects\\MyLuaDLL\\lcc\\myluadll.dll","luaopen_MyLuaDLL");
if(testlib)then
	testlib();
else
	-- Error
end

MyLuaDLL.HelloWorld();

Well, I hope that this helps to get you going making Lua extension DLLs in Windows of your own. Stop by the Icy North forums if you have any questions or comments about this article.