Saturday, April 6, 2013

Including Lua 5.x in Visual Studio 2012 for Embedding in C++

Lua is an incredibly powerful dynamically-typed scripting language. Seriously. Anyone that thinks Perl is the king of scripting has clearly not spent some intimate time with Lua. It can process literally millions of large rows in less than a second. It is this speed and power that makes it a very desirable tool to embed in high-stress systems. Many get their first taste of Lua from video games, a great example being Blizzard Entertainment's epic MMORPG World of Warcraft. Recently, even the powerful online information giant Wikipedia made the leap to implement Lua (kudos to them, I might add!).

It's really a quite sad story how Javascript became the scripting language of choice for the web, rather than Lua. A clever play on the name of a completely unrelated technology at it's emergence (Java) left Lua out in the cold. A sad loss for the web really, but that's a whole other story.

The point is, you don't have to let your applications miss out! Embedding Lua in C++ is a great choice for many things. Sadly, finding a straight-forward answer on how to do so can be a rather discouraging task. Especially if you are working with Visual c++ in Visual Studio. The great news is, it's actually quite easy to do and I'm here to show you exactly how to do it!

The first thing you will need is a suitable Lua build. The current version is 5.2.x. The following approach I'm going to show you is interchangeable with both Lua 5.1 and Lua 5.2. While I will be demonstrating how to do this in Visual Studio 2012, this will also work in Visual Studio 2010.

There are 2 routes you can go about this. You can download the source from Lua.Org directly, or you can get a windows-centric distribution from Lua for Windows, which installs via a simple msi installer and includes a whole plethora of helpful extension libraries for almost anything you could think of doing with Lua. The catch with LuaForWindows is, it's Lua 5.1 and will not be carried on to future versions of Lua. If you get the source from Lua.Org you will have run a build on it yourself (I may be including an article on doing this soon, as it's very easy to do).

Once you have your build of Lua, you are ready to embed it in your c++ project. To do this, you need to tell Visual Studio's compiler and linker where to look for it and what libraries to include.

Let's start with telling it where to look.

I'm going to assume you have installed Lua to the default "c:\Program Files (x86)" directory on your machine. If you have not, don't worry, we'll cover that too.

With your project in visual studio, open the project's "Properties" window. Go to the "VC++ Directories" tab. In here, you will need to edit "Include Directories", "Reference Directories" and "Library Directories". To edit these values, you click on the value, then click on the arrow box that will appear in the top-right side of the value box, and select edit. The window that pops up will allow you to edit the values for the particular line.

First set the "Include Directories" value. If you have installed Lua to the ProgramFiles (x86) directory as suggested above, you can use the following simple macro to point to the directory:


If your directory looks a bit different, just adjust the above text accordingly (example: \Lua\lua-5.1\include).

If you have Lua installed to another location, you can simply use the file navigation tool that appears in the editor window to navigate to the location and point to it. The important part is, you want it pointing to the "/include" folder within the Lua directory.

The process for the remaining settings are the same procedure. Below is a list of each setting and the value to set it to. Remember to adjust the file path if needed.

Include Directories: $(ProgramFiles)\Lua\5.1\include as demonstrated above.
Reference Directories: $(ProgramFiles)\Lua\5.1\lib points to the "lib" folder
Library Directories: $(ProgramFiles)\Lua\5.1\lib points to the "lib" folder

Now visual studio knows what directories to look in when searching for file dependencies. The last part to do is to tell it what lib(s) specifically to include.

In the properties window, go to the "Linker" tab, select the "Input" tab within that, and we will be editing the "Additional Dependencies" value.

As before, click the line, then click the arrow box and select edit. This time we simply need to tell it what lib to use. The only important thing to note is that any libs we specify in here need to be on separate lines.

Enter the following value:


If it is a different version you are using, just adjust the value to the appropriate version.

That's it! Lua is now successfully referenced in our application and ready to be implemented. To see for yourself, try including the c++-specific Lua header file in code:

#include <lua.hpp>

You will notice at the bottom of the visual studio window it is loading the dependencies. If it is giving you error messages that things can not be found, you will need to double check that you have referenced the correct directory locations.

Congratulations! You are ready to use Lua in your application! I will be doing an article about setting up the Lua instance within your app but if you MUST get some info on how to do it, Check out the online version of the book Programming in Lua here. It is written by one of the founders of Lua and includes everything you need to get started.

No comments :

Post a Comment