Embedding Lua in C: Using Lua from inside C

Embedding Lua in C: Using Lua from inside C.

Requirments:
1: The Lua Sources.
2: A C compiler - cc/gcc/g++ for Unix, and Visual C++ for Windows.

Other compilers should under Windows, basically any C compiler - I will cover compiling under Windows at the end of the toturial.
This tutorial will work under any OS which has a C compiler, and which Lua has compiled succesfully on. Though the process for compiling with different compilers on different platforms may be different - In this tutorial I will cover compiling on Unix systems and Windows systems.

For those who don't know, the Lua programming language was made to be a smimple and small scripting language which people could embed into larger applications, especially applications written in C. The advantage of embedding any scripting language (ie. Perl, Python, Ruby, etc) into a larger application was to give the user using your program a 'macro' language in which they could customize the program to suit them. Many developers even create their own 'macro' languages specifically for their applications. For a real world example of this in action - Take a look at the Microsoft Office software on the Windows platform. Microsoft Office applications like Excel and Word use a macro language called 'VBA' which enables the user to create... You guessed it, macros. Of course you could do what you wanted with it, like any other language. VBA ('Visual Basic for Applications') is basically a cut down version of Visual Basic.

Another real world example would be the famous text editor (On Unix platforms) Emacs, which uses Lisp as it's macro language.

So in this tutorial I will show you how to embed the Lua scripting language into your C applications.
To start with lets create a very basic Lua script and save it as "script.lua":

-- Start
-- Script: script.lua
print("I am using Lua from within C")
-- End

There, told you it was a very basic script!
When we embed Lua into C, we will ask Lua to open and run that file. For more examples, see the end of the tutorial. Now for the C code.
Create a new text file called and save it as "embed.c":

#include <stdlib.h>
#include <stdio.h>

/* Include the Lua API header files. */
#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>

int main(void)
{
	/* Declare the Lua libraries we wish to use. */
	/* Note: If you are opening and running a file containing Lua code */
	/* using 'lua_dofile(l, "myfile.lua") - you must delcare all the libraries */
	/* used in that file here also. */
	static const luaL_reg lualibs[] =
	{
        	{ "base",       luaopen_base },
        	{ NULL,         NULL }
	};

	/* A function to open up all the Lua libraries you declared above. */
	static void openlualibs(lua_State *l)
	{
        	const luaL_reg *lib;

      		for (lib = lualibs; lib->func != NULL; lib++)
		{
                	lib->func(l);
                	lua_settop(l, 0);
        	}
	}

	/* Declare a Lua State, open the Lua State and load the libraries (see above). */
	lua_State *l;
	l = lua_open();
	openlualibs(l);

	/* You can do what you want here. Note: Remember to update the libraries used (see above) */
	/* if you add to your program and use new Lua libraries. */
	/* In the lines below, I load and run the Lua code contained in the file */
	/* "script.lua". */
	/* Plus print some text directly from C. */
	printf("This line in directly from C\n\n");
	lua_dofile(l, "script.lua");
	printf("\nBack to C again\n\n");

	/* Remember to destroy the Lua State */
	lua_close(l);

	return 0;
}

To compile this, do the following (Unix):

cc -o embed embed.c \
		    -I/usr/local/include \
		    -L/usr/local/lib \
		    -llua -llualib

To compile under Windows (Visual C++ GUI) do the following:

1: Create a new project.
2: Add the embed.c file.
3: Add the 2 Lua libraries (*.lib) - Standard library and the Core library.
4: Add the locations of the Lua include files to the project options ("Directories tab").
5: You may also have to add the locations of the library files - the same way as above.
6: Compile and Build - that's it.

Now run the compiled file ("./embed" on Unix, "embed.exe" on Windows) and you should see the following output:

This line in directly from C

I am using Lua from within C

Back to C again

And there it is. Of course this is only an extremely basic example. One thing I actually do myself is embed a scripting language which is good at text processing (Python or Perl) and when I need to do text processing, use the embedded scripting language, instead of C - as it can take a lot more work in C.
You can also send values to and from between C and Lua when embedded, which makes the possibilities endless.
I have seen a good tutorial on this, and will link to it.
#NOTE_TO_MYSELF: Add link.

I might also write my own tutorial on this later on, as well as how to embed other scripting languages into C.
Remember to read the Official Lua API manual for loads more informtaion. Or even read through the Lua source code to see what happens under the hood and how the language is actually made, this will give you an even better understanding.

You don't even have to run the Lua code from a file. You can use the function "lua_dostring(l, 'code') instead of the "lua_dofile" function.

Note on distrobuting programs:

If you embed Lua (Or any other scripting language) into a larger application, you still need to ship with it the scripting languages library files (standard library and core library in Lua's case).
In Lua's case, it is not really a downside if your application is big in the first place, because Lua is so small - the library files should not take up anymore than 1mb. This is why I recommend using Lua, I think it is a great embeddable, extensible, stand-alone scripting language.

I hope you have enjoyed reading this tutorial, and have got lots of exciting ideas!
Remember to thank the team behind Lua for creating a wonderful language.

Feel free to email any comments to comments@heavycoder.com

Recommended reading: Programming in Lua (Amazon)