sol2

[brief]

`sol2` is a C++ library binding to Lua.

sol3 (sol2 v3.2.2)

Linux & Max OSX Build Status Windows Build status Documentation Status

Support via Github Sponsors Support via PayPal Support via Ko-fi Support via Patreon Support via Liberapay

sol2 is a C++ library binding to Lua. It currently supports all Lua versions 5.1+ (LuaJIT 2.x included). sol2 aims to be easy to use and easy to add to a project. The library is header-only for easy integration with projects.

Documentation

Find it here. A run-through kind of tutorial is here! The API documentation goes over most cases (particularly, the "api/usertype" and "api/table_proxy" and "api/function" sections) that should still get you off your feet and going, and there's an examples directory here as well.

Sneak Peek

#include <sol/sol.hpp>
#include <cassert>

int main() {
    sol::state lua;
    int x = 0;
    lua.set_function("beep", [&x]{ ++x; });
    lua.script("beep()");
    assert(x == 1);
}
#include <sol/sol.hpp>
#include <cassert>

struct vars {
    int boop = 0;
};

int main() {
    sol::state lua;
    lua.new_usertype<vars>("vars", "boop", &vars::boop);
    lua.script("beep = vars.new()\n"
               "beep.boop = 1");
    assert(lua.get<vars>("beep").boop == 1);
}

More examples are given in the examples directory here.

Supporting

Please use the buttons above and help this project grow.

You can also help out the library by submitting pull requests to fix anything or add anything you think would be helpful! This includes making small, useful examples of something you haven't seen, or fixing typos and bad code in the documentation.

Presentations

"A Sun For the Moon - A Zero-Overhead Lua Abstraction using C++"
ThePhD Lua Workshop 2016 - Mashape, San Francisco, CA
Deck

"Wrapping Lua C in C++ - Efficiently, Nicely, and with a Touch of Magic"
ThePhD Boston C++ Meetup November 2017 - CiC (Milk Street), Boston, MA
Deck

"Biting the CMake Bullet"
ThePhD Boston C++ Meetup February 2018 - CiC (Main Street), Cambridge, MA
Deck

"Compile Fast, Run Faster, Scale Forever: A look into the sol2 Library"
ThePhD C++Now 2018 - Hudson Commons, Aspen Physics Center, Aspen, Colorado
Deck

"Scripting at the Speed of Thought: Using Lua in C++ with sol3"
ThePhD CppCon 2018 - 404 Keystone, Meydenbauer Center, Aspen, Colorado
Deck

"The Plan for Tomorrow: Compile-Time Extension Points in C++" ThePhD C++Now 2019 - Flug Auditorium, Aspen Physics Center, Aspen, Colorado Deck

Features

Supported Compilers

sol2 makes use of C++17 features. GCC 7.x.x and Clang 3.9.x (with -std=c++1z and appropriate standard library) or higher should be able to compile without problems. However, the officially supported and CI-tested compilers are:

Please make sure you use the -std=c++2a, -std=c++1z, -std=c++17 or better standard flags (some of these flags are the defaults in later versions of GCC, such as 7+ and better).

If you would like support for an older compiler (at the cost of some features), use the latest tagged sol2 branch. If you would like support for an even older compiler, feel free to contact me for a Custom Solution.

sol3 is checked by-hand for other platforms as well, including Android-based builds with GCC and iOS-based builds out of XCode with Apple-clang. It should work on both of these platforms, so long as you have the proper standards flags.

Creating a single header

You can grab a single header (and the single forward header) out of the library here. For stable version, check the releases tab on GitHub for a provided single header file for maximum ease of use. A script called single.py is provided in the repository if there's some bleeding edge change that hasn't been published on the releases page. You can run this script to create a single file version of the library so you can only include that part of it. Check single.py --help for more info.

If you use CMake, you can also configure and generate a project that will generate the sol2_single_header for you. You can also include the project using CMake. Run CMake for more details. Thanks @Nava2, @alkino, @mrgreywater and others for help with making the CMake build a reality.

Running the Tests

Testing on Travis-CI and Appveyor use CMake. You can generate the tests by running CMake and configuring SOL2_TESTS, SOL2_TESTS_SINGLE, SOL2_TESTS_EXAMPLES, and SOL2_EXAMPLES to be on. Make sure SOL2_SINGLE is also on.

You will need any flavor of python3 and an available compiler. The testing suite will build its own version of Lua and LuaJIT, so you do not have to provide one (you may provide one with the LUA_LOCAL_DIR variable).

License

sol2 is distributed with an MIT License. You can see LICENSE.txt for more info.

If you need a custom solution, feel free to contact me.

license MIT
project sol2
url github.com/ThePhD/sol2
3 Versions
version 3.2.2
repository pkg:cppget.org/testing
depends 1; lua
version 3.2.1
repository pkg:cppget.org/stable
depends 1; lua
version 3.2.0+2
repository pkg:cppget.org/stable
depends 1; lua