getting started¶

Let’s get you going with sol! To start, you’ll need to use a lua distribution of some sort. sol doesn’t provide that: it only wraps the API that comes with it, so you can pick whatever distribution you like for your application. There are lots, but the two popular ones are vanilla Lua and speedy LuaJIT . We recommend vanilla Lua if you’re getting started, LuaJIT if you need speed and can handle some caveats: the interface for sol doesn’t change no matter what Lua version you’re using.

If you need help getting or building Lua, check out the Lua page on getting started. Note that for Visual Studio, one can simply download the sources, include all the Lua library files in that project, and then build for debug/release, x86/x64/ARM rather easily and with minimal interference. Just make sure to adjust the Project Property page to build as a static library (or a DLL with the proper define set in the Preprocessor page, eg. LUA_BUILD_AS_DLL=1).

After that, make sure you grab either the single header file release, or just perform a clone of the github repository here and set your include paths up so that you can get at sol.hpp somehow. Note that we also have the latest version of the single header file with all dependencies included kept in the repository as well. We recommend the single-header-file release, since it’s easier to move around, manage and update if you commit it with some form of version control. You can also clone/submodule the repository and then point at the single/sol/sol.hpp on your include files path. Clone with:

>>> git clone https://github.com/ThePhD/sol2.git

When you’re ready, try compiling this short snippet:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp> // or #include "sol.hpp", whichever suits your needs

int main(int argc, char* argv[]) {

	sol::state lua;
	lua.open_libraries(sol::lib::base);

	lua.script("print('bark bark bark!')");

	return 0;
}

Using this simple command line:

>>> g++ -std=c++17 test.cpp -I"path/to/sol/include" -I"path/to/lua/include" -L"path/to/lua/lib" -llua

Or using your favorite IDE / tool after setting up your include paths and library paths to Lua according to the documentation of the Lua distribution you got. Remember your linked lua library (-llua) and include / library paths will depend on your OS, file system, Lua distribution and your installation / compilation method of your Lua distribution.

If this works, you’re ready to start! The first line creates the lua_State and will hold onto it for the duration of the scope its declared in (e.g., from the opening { to the closing }). It will automatically close / cleanup that lua state when it gets destructed.

The second line opens a single lua-provided library, “base”. There are several other libraries that come with lua that you can open by default, and those are included in the sol::lib enumeration. You can open multiple base libraries by specifying multiple sol::lib arguments:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

int main(int argc, char* argv[]) {
	sol::state lua;
	lua.open_libraries(sol::lib::base, sol::lib::coroutine, sol::lib::string, sol::lib::io);

	lua.script("print('bark bark bark!')");

	return 0;
}

If you’re interested in integrating sol with a project that already uses some other library or Lua in the codebase, check out the existing example to see how to work with sol when you add it to a project (the existing example covers require as well)!

Some more ways of loading scripts and handling errors is shown in this example! There is also a full, cross-platform example of loading a DLL.

Next, let’s start reading/writing some variables from Lua into C++, and vice-versa!