Creating a Lua Library in C: Doing Lua the Hard Way

Have you ever been writing some Lua, and thought to yourself “Gee, this is nice and all, but this isn’t nearly annoying enough! You know what this needs? Pointer arithmetic!” Don’t worry, it’s a common thought; we all go through this. There is good news though; I’m here to help. With my help you’ll be writing your Lua code in C like a champ!

But, first things first; you need to set up your environment. I’m going to assume that you’ve compiled and installed Lua on your dev workstation already. Now, fire up your favorite IDE. This post is written assuming NetBeans 7.3, but the concepts should be pretty universal.

IDE/Project Configuration

If you’re using Eclipse, or vi or whatever, you may want to read this to get an idea of what you need to do. However, these instructions are for NetBeans.

First things first, you should configure Code Assistance. From the menu bar, select Tools->Options. Click on C/C++, and select the Code Assistance tab. Click Add, and enter [path to lua installation]/include, and click Select. Click OK.

Now you’re ready to create your project. Click File->New Project… and select C/C++->C/C++ Dynamic Library and click Next >. Give your project a name and click Finish.

Next we need to configure our project to see the Lua headers. Right click your project and click Properties. Click on the C Compiler category, and click the ellipsis on the Include Directories line. Click Add, browse to the location of your Lua /include directory and click Select. Click OK to close the Include Directories window, then click OK to close the Project Properties window. You are ready to go.

Essential Elements of a Lua Library

First things first, you should #include the lua library headers: lua.h, lualib.h, and luaxlib.h

#include lua.h
#include lualib.h
#include luaxlib.h

Next, you need to create your luaL_Reg array. This array will contain all your functions that you want to expose to your library.

static const struct luaL_Reg libname [] = {
{"test_string", test_string},
{NULL, NULL}
};

For each entry in the array, the first part is the function name, as you’d like it to be called in your script, and the second part is a pointer to your function. The Last entry must be NULL, NULL.

Finally, you should create the int luaopen_libname(lua_State * L) function. This function is called when the library is required. This function could be declared like:

int luaopen_libname(lua_State * L)
{
luaL_newlib(L, libname);
lua_setglobal(L, "libname");
return 0;
}

Some things to note: the name of this function should reflect the name of your library. For instance, if your library is named cat_herding the function should be luaopen_cat_herding. For the function luaL_newlib(L, libname), the second argument is the name of the luaL_Reg array you created previously. The lua_setglobal(L, “libname”) function does exactly what it says; it sets a global variable for whatever the top entry in the lua stack is(I’ll discuss the stack in a future post).

Installing Your Library

After you’ve finished creating your library, compile it! After it’s built you should have a file called something like liblibname.so. You should copy this file to your Lua installation’s lib directory. This location varies per installation, but for me it’s at /usr/local/lib/lua/5.2/. After you’ve copied your library, rename it to remove the lib prefix.

mv liblibname.so libname.so

That’s it! You are now the proud owner of a completely useless Lua C library! Feel free to return to your C project and add some functionality to your library.

Further Reading

For further information on the use of the Lua C API, you should check out the Lua 5.2 Reference Manual. There, you can find documentation on all the functions available in the library. Lua-users.org is a great repository of tutorials on various things relating to Lua.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: