Sol v2.0 - a C++ <-> Lua API wrapper with advanced features and top notch performance - is here, and it's great! Documentation:
ThePhD Merge pull request #701 from isvogor-foi/develop
fmt rename to fmt_ to avoid naming conflict with the spdlog library
Latest commit 4f974a7 Sep 3, 2018
Permalink
Failed to load latest commit information.
.github add additional CMake presentation Feb 8, 2018
cmake Update sol2-config.cmake.in Jun 22, 2018
docs Fix a few typos in the threading doc. Jun 30, 2018
examples begin migrating benchmarks and preparing documentation for sol3 May 17, 2018
scripts begin migrating benchmarks and preparing documentation for sol3 May 17, 2018
single/sol fmt rename to fmt_ to avoid naming conflict with the spdlog library Sep 3, 2018
sol fmt rename to fmt_ to avoid naming conflict with the spdlog library Sep 3, 2018
subprojects Fix line endings Jun 6, 2018
tests fix utility stuff Jun 27, 2018
.clang-format fix #638 May 10, 2018
.dockerignore begin migrating benchmarks and preparing documentation for sol3 May 17, 2018
.gitignore Merge branch 'develop' into feature/meson Jun 15, 2018
.gitmodules Ditch the dependency on the optional submodule, nobody's ever gonna c… Nov 1, 2016
.style.yapf This update allows for many more definition macros and teh use of a c… Apr 17, 2018
.travis.yml Fix #626 Apr 12, 2018
CMakeLists.txt update CMake to have namespaced stuff Aug 11, 2018
CONTRIBUTING.md .clang-format the crap out of everything, I guess...! Sep 13, 2017
CONTRIBUTORS.md update documentation with additional information about resolve and ov… Jun 15, 2018
Dockerfile put things in place for 32-bit testing and builds on both appveyor an… Jan 20, 2018
LICENSE.txt begin migrating benchmarks and preparing documentation for sol3 May 17, 2018
README.md update documentation with additional information about resolve and ov… Jun 15, 2018
appveyor.yml Fix Visual Studio 2015 builds, fix error handling printouts / excepti… Apr 18, 2018
list-headers.py Add meson build configuration file Jun 4, 2018
meson.build Fix line endings Jun 6, 2018
meson_options.txt Fix line endings Jun 6, 2018
ninja_syntax.py Switched over to bootstrap.py script Jun 5, 2014
single.py Fix default args on single generation script Jul 23, 2018
sol.hpp update documentation with additional information about resolve and ov… Jun 15, 2018
sol2.natvis fix overpop from stack_check_get tracking Mar 4, 2018
sol2.pc.in Fix CMake install (#586) Feb 17, 2018

README.md

Sol 2.20

Join the chat in Discord: https://discord.gg/buxkYNT

Linux & Max OSX Build Status Windows Build status Documentation Status

Sol is a C++ library binding to Lua. It currently supports all Lua versions 5.1+ (LuaJIT 2.x included). Sol 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/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.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.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

You can donate to support Sol and the project, which is always appreciated! This is a time-consuming effort, so individuals who donate get to:

  • steer the direction and time spent on sol
  • get a role on the Discord server
  • get their name put up in the CONTRIBUTORS list
  • put something of their choice on sol2's README or the documentation's front page

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

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.

Features

  • Fastest in the land (see: sol bar in graph).
  • Supports retrieval and setting of multiple types including:
    • std::string, std::wstring, std::u16string and std::u32string support (and for views).
    • understands and works with containers such as std::map/unordered_map, c-style arrays, vectors, non-standard custom containers and more.
    • user-defined types, with or without registering that type
    • std::unique_ptr, std::shared_ptr, and optional support of other pointer types like boost::shared_ptr.
    • custom optional<T> that works with references.
    • C++17 support for variants and similar new types.
  • Lambda, function, and member function bindings are supported.
  • Intermediate type for checking if a variable exists.
  • Simple API that completely abstracts away the C stack API, including protected_function with the ability to use an error-handling function.
  • operator[]-style manipulation of tables
  • C++ type representations in lua userdata as usertypes with guaranteed cleanup.
  • Customization points to allow your C++ objects to be pushed and retrieved from Lua as multiple consecutive objects, or anything else you desire!
  • Overloaded function calls: my_function(1); my_function("Hello") in the same lua script route to different function calls based on parameters
  • Support for tables, nested tables, table iteration with table.for_each / begin() and end() iterators.
  • Zero overhead for usertype function call lookup when using SOL_USE_BOOST, safe for critical applications

Supported Compilers

Sol makes use of C++11 and C++14 features. GCC 5.x.x and Clang 3.6.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:

  • GCC 5.x.x+ (MinGW 5.x.x+)
  • Clang 3.6.x+
  • Visual Studio 2015 Community (Visual C++ 14.0)+

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

Older compilers (GCC 4.9.x, Clang 3.4.x seem to be the lowest) can work with versions as late as v2.17.5, with the flag -std=c++14 or -std=c++1y.

sol2 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.

Running the Tests

Testing on Travis-CI and Appveyor use CMake. You can generate the tests by running CMake and configuring TESTS, TESTS_SINGLE, TESTS_EXAMPLES, and EXAMPLES to be on. Make sure 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.

License

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