Sol3 (sol2 v3.0) - a C++ <-> Lua API wrapper with advanced features and top notch performance - is here, and it's great! Documentation:



Documentation Status

sol2 is a C++ library binding to Lua. It currently supports all Lua versions 5.1+ (LuaJIT 2.0+ and MoonJIT 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, and a single header can be used for drag-and-drop start up.

Sneak Peek

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

int main() {
    sol::state lua;
    int x = 0;
    lua.set_function("beep", [&x]{ ++x; });
    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 =\n"
               "beep.boop = 1");
    assert(lua.get<vars>("beep").boop == 1);

More examples are given in the examples directory here.


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.

"I need X Feature or Fix, Right Now™"

Find the support option that's right for you, here! If you're happy to wait, you can just file a boring issue and we'll get to it Whenever There Is Time™.

I want to donate to help!

You can find donation and sponorship options here and from the little heart button near the top of this repository that will take you to a bevy of links in which you can donate and show support for this project and others!


  • Fastest in the land (see: sol3 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, and support for the inferior std::optional.
    • 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 string overhead for usertype function lookup.

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:

  • GCC 7.x.x+ (MinGW 7.x.x+)
  • Clang 3.9.x+
  • Visual Studio 2017 Community (Visual C++ 15.0)+

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. If something doesn't work or you need special options, you may need to look into the different ways to support the project to have it done for you!

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


Testing turns on certain CI-only variables in the CMake to test a myriad of configuration options. 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).


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

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

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

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

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

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


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

If you need a custom solution, feel free to reach out.

  • Alignment error with member callback

    Alignment error with member callback

    The following example, where we try to execute a std::function member object, creates alignment errors on clang 6.0.0 according to the UndefinedBehaviorSanitizer.

    #include <sol.hpp>
    #include <functional>
    #include <iostream>
    struct Test{
      std::function<void()> callback = [](){ std::cout << "Hello world!" << std::endl; };
    int main() {
      sol::state lua;
      Test test;
      lua["test"] = &test;
      return 0;

    when compiled using clang++ --std=c++14 -fsanitize=undefined ... a cascade of 'misaligned address' runtime errors is generated, beginning with

    (a.out:x86_64+0x1000d8c48): runtime error: constructor call on misaligned address 0x7fc01c405518 for type 'sol::function_detail::functor_function<std::__1::function<void ()> >', which requires 16 byte alignment
    0x7fc01c405518: note: pointer points here
     00 00 00 00  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  00 00 00 00

    Otherwise the program executes as expected.

    Ahhh.Real Monsters Baited.Undefined Behavior 
    opened by TheLartians 42
  • sol::variadic_args use in usertype constructor

    sol::variadic_args use in usertype constructor

    struct foo 
    	foo(sol::variadic_args args)
    		std::cout << args.size() << std::endl;
    int main(int argc, char ** argv)
    	sol::state lua;
    	lua.new_usertype<foo>("foo", sol::constructors<foo(sol::variadic_args)>());
    	lua.script(R"(, 1), 1, 2), 1, 2, 3)

    This will be print


    why? my compiler is vc2019.

    opened by 11nk 33
  • Long compilation times when registering usertype with lots (>50) of member functions.

    Long compilation times when registering usertype with lots (>50) of member functions.

    I have a class which has a lot of member functions. I pass them all in usertype constructor but that probably generates huge template intantiations of some functions. This causes CPP file in VS2015 to compile for 3-4 minutes while consuming 1.5 gigabytes of RAM.

    What I need is ability to register functions one by one, not all at once. I realize that this may not be the most efficient way to do this, but compilation times are very important for me, more that runtime performance when registering this stuff.

    I propose something like:

    usertype<SomeClass> ut("SomeClass");
    ut.add_function("someFunc", &SomeClass::someFunc);
    Refactoring.Usability Feature.Can Do Feature.Shiny 
    opened by eliasdaler 29
  • Calling Unknown function on global variable crashes on cleanup

    Calling Unknown function on global variable crashes on cleanup

    Hey there,

    I just grabbed latest to benefit from the "attempt to index a nil value" fix, but ran into an issue on app exit. When having called an unknown function on a global lua var it will crash on exit with iterator debug level 2, orphaned pointer, read access violation.


    class A
        A() : a(0){}
    solState.new_usertype<A>("A", "a", &A::a);

    runs and exits fine:

    local test =

    runs fine but will cause app crash on exit:

    test = -- notice global variable
    test:Unknown() -- having called it will cause app to crash on exit

    Looking into it more the crash happens during GC for the fail_on_error functor.

    opened by schnitzelK1ng 27
  • AppVeyor for VS 2017/2015 | Travis for g++ 7/6/5 , clang++ 3.7/3.8/3.9/4.0

    AppVeyor for VS 2017/2015 | Travis for g++ 7/6/5 , clang++ 3.7/3.8/3.9/4.0

    All of the old test harnesses should be placed into "Allowed Failures" buckets, including VS 2015. This will let us know what commit exactly breaks a certain compiler level, albeit it would mean tests would take an additional hour to complete in the cloud (mostly because of additional XCode imaging setup).

    • [x] Travis CI:

      • [x] g++ 5.3
      • [x] g++ 5.4
      • [x] g++ 6.3
      • [x] g++ 7.1
      • [x] clang++ 3.6
      • [x] clang++ 3.7
      • [x] clang++ 3.8
      • [x] clang++ 3.9
      • [x] clang++ 4.0
    • [x] AppVeyor:

      • [x] Visual Studio 2015, Latest (allowed failure)
      • [x] Visual Studio 2017, Latest

    All older tests should be bundled up as "allowed failures"

    opened by ThePhD 25
  • Write a tutorial

    Write a tutorial

    The current README is pretty terse, and reading API reference is a not pleasant way to learn any library. I propose to kidnap manual from any competing library (kagaya, selene, lua-intf to name a few), made a few edits to identifiers (and list of supported compilers) and put it into README. You may even combine parts kidnapeed here and there. Later Sol-specific features may be added, but it will be a good start.

    I believe that now, when you are released a major stable version, lack of step-by-step tutorial is main barrier to wider Sol2 acceptance.

    opened by Bulat-Ziganshin 25
  • LuaJIT 5.1: Exceptions are not rethrown through sol::error

    LuaJIT 5.1: Exceptions are not rethrown through sol::error

    In my code, I'm trying to force some sandboxing, one part of this is setting the require function to nil.

    To test this, I create an "library script":

    local M = {}
        return "foo"
    return M

    I store this into a file in the test dir, m.lua, and then load it via:

    local M= require('m')
    assert( == "foo");

    On Lua 5.2, this throws a sol::error claiming the require function is nil. This is the expected behaviour, however, luajit exceptions are never caught and it throws an error unrecognized.

    opened by Nava2 25
  • Usertypes with many members become too complex for the compiler

    Usertypes with many members become too complex for the compiler

    I'm experiencing this issue under MSVC140 (Update 3) on the 64-bit toolchain.

    I have a usertype which has 147 property members (sol::property), a call constructor, and two base classes, and during compilation I'm getting the following errors:

    2>I:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\include\type_traits(1016): fatal error C1202: recursive type or function dependency context too complex (compiling source file CustomUsertypeClass.cpp)
    2>  I:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\include\type_traits(1035): note: see reference to class template instantiation 'std::_Choose_conjunction<true,_Lhs,std::is_constructible<const char (&)[27],const char (&)[27]>,std::is_constructible<sol::property_wrapper<bool (__cdecl CustomUsertypeClass::* )(void) const,void (__cdecl CustomUsertypeClass::* )(bool)>,_Ty>,std::is_constructible<const char (&)[27],const char (&)[27]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[30],const char (&)[30]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[26],const char (&)[26]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[16],const char (&)[16]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[15],const char (&)[15]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[20],const char (&)[20]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[25],const char (&)[25]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[34],const char (&)[34]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[28],const char (&)[28]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[32],const char (&)[32]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[21],const char (&)[21]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[18],const char (&)[18]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[23],const char (&)[23]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[21],const char (&)[21]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[24],const char (&)[24]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[26],const char (&)[26]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[25],const char (&)[25]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (...

    This could be associated to #202 but since it's an actual issue I'm posted it here for reference.

    opened by OrfeasZ 23
  • Issue compiling sol on OSX (xcode 8.2.1, LLVM 8.0).

    Issue compiling sol on OSX (xcode 8.2.1, LLVM 8.0).

    I wonder if someone could help me. This is likely something on my end.

    Im trying to use sol2 with luajit. Previously using lua worked fine. I add the header like this:

    ` #define SOL_USING_CXX_LUA


    #include <sol2/sol.hpp> `

    I get an error in compilation: .../include/sol2/sol.hpp:2082:10: Cannot initialize return object of type 'char *' with an rvalue of type 'int'

    It seems strerror_r returns an int, not as expected a char *. Should i be using those 2 defines when trying to use luajit?


    Bug.Well Shit 
    opened by pjohalloran 22
  • Container Usertypes are not iterable

    Container Usertypes are not iterable

    Using the latest release of sol2, Visual Studio 2017 and compiled as C++17 through the appropriate compiler flags

    I have a class, X, which satisfies the requirements of Container and holds a different class, Y.

    Class X has methods and functions that help manipulate Y's, and i want this class to be exposed to Lua. As such, i've attempted to register it as a usertype, which works, but I can't for the life of me figure out how to get the actual Container part to work. No matter what i try i can't iterate over it from Lua.

    I have tried specializing the is_container template to be true, but that does not visibly change anything.

    Is this not possible in sol2? Am i missing something?

    Documentation Docs.Are Bad 
    opened by DianaNites 22
  • Large integer support

    Large integer support

    This PR adds large integer support for x86 and integer misrepresentation detection for x86/x64. sol2 will still try to use lua_Integer wherever it is safe to do so, only when the value can't possibly fit in lua_Integer, it uses lua_Number as fallback with optional runtime checks to make sure the floating point value still represents the integer accurately.

    Would appreciate any feedback or concerns, if there are any.

    See #470

    • [x] large integer changes
    • [x] tests
    • [x] working linux:i386 build
    • [x] passes travis-ci (as good as develop)
    • [x] reviewed

    unrelated to this PR:

    • The build for the original develop branch is currently broken, I'll update my fork from upstream as soon as it's fixed.
    • currently both linux:i386 and windows:x86 are failing some tests on upstream/develop (at least with the latest luajit) maybe we could have some i386 builds on travis?
    • you manually need to set SOL_EXCEPTIONS_SAFE_PROPAGATION under windows x86/luajit2.1b3 (the new versions have proper exception handling under windows x86 with \EHsc)
    • is failing with python2.7 and only works with python3
    • it would be nice to have a build config that runs with msvc that you don't need to create yourself
    Feature.Shiny Tests.CI 
    opened by mrgreywater 22
  • Unwanted function argument copying starting from v3.3.0

    Unwanted function argument copying starting from v3.3.0

    In push_reference, where the use_reference_tag is calculated, there is a change made in v3.3.0: meta::neg<std::is_const<T>> -> meta::neg<std::is_const<std::remove_reference_t<T>>>

    Due to this change, const T& args meet the reference condition no more, and now they are copied for the call. The first issue here is that some big and heavy objects are copied although we explicitly pass them as const references and don't either want or expect copying to happen. The second issue is inability to pass refcounted objects without making a new reference, which is desired sometimes and was possible before the change.

    opened by niello 0
  • is_value_semantic_for_function doesn't work as expected

    is_value_semantic_for_function doesn't work as expected

    As follows from code, passing by reference or by value is determined as:

    	using use_reference_tag =

    But when we pass some argument to sol::function by value (say type is MyType), in push_reference the T is already MyType&. And if we define MyType as passed by value, we actually get nothing, because for MyType& it is not defined. This causes me to define all these just in case:

    template <> struct is_value_semantic_for_function<MyType> : std::true_type {};
    template <> struct is_value_semantic_for_function<const MyType> : std::true_type {};
    template <> struct is_value_semantic_for_function<MyType&> : std::true_type {};
    template <> struct is_value_semantic_for_function<const MyType&> : std::true_type {};

    And there is the second issue. While we may want to pass [const] MyType and const MyType& by value, we may at the same time want explicit MyType& to be passed by reference. It is typical pattern for C++ signatures. But we can't define that because MyType& specialization is used for MyType args.

    The perfect behaviour would be to define specialization for MyType only and to have MyType& as an automatic exception from the rule, bound always by reference. And if someone wants a reference to be passed by value, let them explicitly use const MyType& on C++ side.

    opened by niello 0
  • LuaJIT 2.1.0-beta3 and 64-bit bitwise operations

    LuaJIT 2.1.0-beta3 and 64-bit bitwise operations


    My apologies in advance if this is not a SOL issue but I thought it'd be worth asking. I have encountered the following issue: I am trying to use luaJIT's built-in bit library which, reportedly, handles 64-bit integers. The issue is: When I try to use local bit = require("bit") and do my thing, I get this error:

    ERROR! XElua_state.cpp : 352 : CheckAndRunFunction : Assets/script/__init.lua:1: module 'bit' not found:
            no field package.preload['bit']
            no file '.\bit.lua'
            no file 'C:\Users\User\source\repos\engine\x64\Debug\lua\bit.lua'
            no file 'C:\Users\User\source\repos\engine\x64\Debug\lua\bit\init.lua'
            no file '.\bit.dll'
            no file 'C:\Users\User\source\repos\engine\x64\Debug\bit.dll'
            no file 'C:\Users\User\source\repos\engine\x64\Debug\loadall.dll'

    Opening sol::lib::bit32 makes bit functions work but only for 32-bit numbers. there any way to make the "correct" luaJIT library visible?

    opened by vdweller84 0
  • Memory leak when returning usertype A from a usertype B member function when usertype B does not have a registered member variable.

    Memory leak when returning usertype A from a usertype B member function when usertype B does not have a registered member variable.

    I am currently using C++ in Visual Studio 2022. I noticed a weird memory leak in a program I was making and after some debugging, I found it. It is possible that I'm just doing something wrong but from what I can find, It seems that as the title says if you return a usertype A from a function that is a member of usertype B and usertype B does not have any member variables it will not delete the new instance of usertype A properly. Here is some example code to demonstrate the issue:

    struct A
        int X;
        int Y;
    struct B
        int Z;
        A Get()
       	 return A();
    struct C
        A Get()
       	 return A();
    int Main()
        std::string BScript =
        "local T = B:new()\n"
        "for i = 0, 1000 ^ 2.5 do\n"
        "    local Temp = T:Get()\n"
        std::string CScript =
       	 "local T = C:new()\n"
       	 "for i = 0, 1000 ^ 2.5 do\n"
       	 "    local Temp = T:Get()\n"
       	 std::cout << "This will not create a memory leak!" << std::endl;
       	 sol::state State;
       	 State.new_usertype<A>("A", sol::constructors<void()>(),
       		 "X", &A::X,
       		 "Y", &A::Y);
       	 State.new_usertype<B>("B", sol::constructors<void()>(),
       		 "Z", &B::Z,
       		 "Get", &B::Get);
       	 std::cout << "Done! Waiting..." << std::endl;
       	 std::cout << "This will create a memory leak!" << std::endl;
       	 sol::state State;
       	 State.new_usertype<A>("A", sol::constructors<void()>(),
       		 "X", &A::X,
       		 "Y", &A::Y);
       	 State.new_usertype<B>("B", sol::constructors<void()>(),
       		 "Get", &B::Get);
       	 std::cout << "Done! Waiting..." << std::endl;
       	 std::cout << "This will also create a memory leak!" << std::endl;
       	 sol::state State;
       	 State.new_usertype<A>("A", sol::constructors<void()>(),
       		 "X", &A::X,
       		 "Y", &A::Y);
       	 State.new_usertype<C>("C", sol::constructors<void()>(),
       		 "Get", &C::Get);
       	 std::cout << "Done! Waiting..." << std::endl;
        std::cout << "Program complete" << std::endl;
        while (true);
        return EXIT_SUCCESS;

    The code contains three structs A, B and C, the functions B::Get and C::Get return a new instance of A.

    The first block of code will register the structs A and B and the struct B will be registered with both a function and a variable. It then runs BScript which just calls the B::Get function a lot of times NOT CREATING a memory leak.

    The second block of code will register the structs A and B and the struct B will register only its function. It then runs BScript which just calls the B::Get function a lot of times CREATING a memory leak. Presumably, because it doesn't have a registered variable?

    The third block of code will register the structs A and C and the struct C will only contain one function which is registered. The purpose of this is to show that what's causing the memory leak isn't forgetting to register all member variables of a struct. It then runs CScript which just calls the C::Get function a lot of times CREATING a memory leak.

    So, is this intended behaviour, am I doing something wrong or is this a bug?

    opened by Kaj9296 0
  • Overloaded base function isn't called

    Overloaded base function isn't called

    struct Test1 {
        void test() {
    struct Test2 : Test1 {
        void test(int value) {
    }; # error stack index 2, expected number, received no value: not a numeric type that fits exactly an integer (number maybe has significant decimals) (bad argument into 'void(int)')

    Is this normal, or there is a bug somewhere?

    opened by deadlocklogic 1
  • Segmentation fault when accessing objects inside a table with wrong type

    Segmentation fault when accessing objects inside a table with wrong type

    Below program is crashing after throwing the exception when accessing "test2" with the incorrect type. Incorrectly accessing "test" is throwing as expected and program runs after that. The expected behavior I suggest would be just throw an exception and not crash afterwards.

    I've tested this with sol 3.3.0 and Lua 5.3.6 and with sol 3.2.1 with Lua 5.3.5 (this is what compiler explorer is providing). It was working with the same Lua version before updating to sol3 with v2.20.6.

    #include <limits>
    #include <iostream>
    #define SOL_ALL_SAFETIES_ON 1
    #include <sol/sol.hpp>
    auto main() -> int {
        sol::state lua;
        lua["object"] = lua.create_table_with("test2", 10);
        lua["test"] = 10;
        try {
            std::cout << lua["test"].get<int>() << std::endl;
            std::cout << lua["test"].get<std::string>() << std::endl;
        } catch (const std::exception& e) {
            std::cout << "exception caught for test: " << e.what() << std::endl;
        try {
            std::cout << lua["object"]["test2"].get<int>() << std::endl;
            std::cout << lua["object"]["test2"].get<std::string>() << std::endl;
        } catch (const std::exception& e) {
            std::cout << "exception caught for test2: " << e.what() << std::endl;
        return 0;


    Program returned: 139
    munmap_chunk(): invalid pointer
    exception caught for test: lua: error: stack index -1, expected string, received number
    exception caught for test2: lua: error: attempt to index a string value

    You can test it by yourself in compiler explorer: (not current sol2 version, but it fails in 3.3.0 as well)

    The segfault is happening inside ltable.c at the marked Line:

    static Node *mainposition (const Table *t, const TValue *key) {
      switch (ttype(key)) {
        case LUA_TNUMINT:
          return hashint(t, ivalue(key));
        case LUA_TNUMFLT:
          return hashmod(t, l_hashfloat(fltvalue(key)));
        case LUA_TSHRSTR:
          return hashstr(t, tsvalue(key));
        case LUA_TLNGSTR:
          return hashpow2(t, luaS_hashlongstr(tsvalue(key)));
        case LUA_TBOOLEAN:
          return hashboolean(t, bvalue(key));
          return hashpointer(t, pvalue(key));
        case LUA_TLCF:
          return hashpointer(t, fvalue(key));
          return hashpointer(t, gcvalue(key)); // <----

    My current workaround is to check against the type before converting, but I relied on the exceptions on version v2.20.6 and I'm worried that I'm introducing crashes somewhere I'm currently not aware of.

    opened by dns13 1
  • v3.3.0(Jun 25, 2022)

    🎉 v3.3.0

    This follows the version 3 release, incorporating a few improvements from the still-in-progress v4 and a number of critical fixes for keep-alive during iteration (especially w.r.t. Lua coroutines) and fixes for Lua 5.4. It also cleans up some logical bugs in many different places and improves the header hygiene.

    It also gives a chance to update various package managers which were waiting for a newer stable release.

    What's Changed

    • Add CMake option to disable installation by @violinyanev in
    • Fix typos in configuration macros. by @atom0s in
    • Add override qualifier to bad_optional_access::what() by @cuavas in
    • Fixed typos in quick n' dirty tutorial. by @TwinHits in
    • Ignore unused variables; Ignore -Wshadow and -Wconversion on Clang by @dimitrisudell in
    • Fix argument usage typo. by @atom0s in
    • Support constexpr boost::none with recent Boost versions. by @vlichevsky in
    • Remove duplicate constructor type section from docs by @Riyyi in
    • Added FFI enabled check by @RinatNamazov in
    • Fix sol2 cmake include failing as a dependency by @edunad in
    • Fix aligned memory allocation by @Smertig in
    • Update is_string_constructible for C++23 P2166R1 by @StephanTLavavej in
    • Fixed: std::cout not found on msvc by @Klaim in
    • Add missing parenthesis for std::max by @halx99 in
    • Fix issues with is_c_str_or_string and is_c_str by @cschreib in
    • 🐛 Fix #1346 by @Immortalety in
    • ✨ Test and fix #1315 by @ShepherdSoasis in
    • CMake: Build LuaJIT: use copy_if_different by @DerSauron in
    • Fix compile error when registering new user types with operator() by @matusfedorko in
    • fix #1354 by @qinix in

    New Contributors

    • @violinyanev made their first contribution in
    • @atom0s made their first contribution in
    • @cuavas made their first contribution in
    • @TwinHits made their first contribution in
    • @dimitrisudell made their first contribution in
    • @vlichevsky made their first contribution in
    • @Riyyi made their first contribution in
    • @RinatNamazov made their first contribution in
    • @edunad made their first contribution in
    • @StephanTLavavej made their first contribution in
    • @Klaim made their first contribution in
    • @halx99 made their first contribution in
    • @cschreib made their first contribution in
    • @Immortalety made their first contribution in
    • @ShepherdSoasis made their first contribution in
    • @DerSauron made their first contribution in
    • @matusfedorko made their first contribution in
    • @qinix made their first contribution in

    Full Changelog:

    Source code(tar.gz)
    Source code(zip)
    config.hpp(2.04 KB)
    forward.hpp(37.19 KB)
    sol.hpp(978.14 KB)
  • v3.2.2(Oct 4, 2020)

    This release is a patch update. It adds a new feature but because that feature is gated behind a macro definition, the minor nor major versions are changed. New code should be unaffected!

    • New feature: function pointer retrieval! It is not on by default!
      • Please note this is unsafe, see the documentation for SOL_GET_FUNCTION_POINTERS_UNSAFE -
    • A UBSan error for null pointer arithmetic was fixed up, resulting in UB-free codegen (It hadn't become a problem yet, but it was probably going to! #1017)
    • load_result and friends are not copyable. They were never supposed to be, and since I only ever used them transiently it almost never came up until now (#995)
    • An API for accessing and messing with the garbage collector has been added (#997)
    • MoonJIT is totally supported. The author was very nice to us! (#967)
    • Recently, documentation was improved around certain configuration macros (
      • SOL_ID_SIZE
    • Configuration has been reworked through the library:
      • The user-facing definitions are, however, the same, and cleaned up a little bit.
      • You can place a folder and a in some directly that follows the convention <sol/config.hpp> and put your macro definitions in there to make it easier to manage your library-specific defines. This makes it easier to keep all your definitions together.
    • Build issues on all systems from Mac OSX with Apple Clang to Windows with VC++ should be resolved now! (#1021 #1031 #1034)
    • Issues with certain constant definitions in the Lua 5.4 release should not happen.
    • Fixed some bugs in the use of is_lvalue_reference (thanks, #1028 !)
    Source code(tar.gz)
    Source code(zip)
    config.hpp(2.04 KB)
    forward.hpp(24.72 KB)
    sol.hpp(897.35 KB)
  • v3.2.1(Jun 6, 2020)

  • v3.0.3(Jul 4, 2019)

    The tutorials were made better!

    • C++ in Lua walkthrough was greatly enhanced for quality:

    • Ownership is now very clearly explained (or at least better than before):

    • And various other minor documentation improvements

      Some variant fixes were deployed and more CMake fiddling was done.

    Have fun!~

    Source code(tar.gz)
    Source code(zip)
    forward.hpp(14.77 KB)
    sol.hpp(871.93 KB)
  • v3.0.2(May 29, 2019)

  • v2.20.6(Nov 28, 2018)

  • v2.20.5(Nov 10, 2018)

  • v2.20.4(Aug 4, 2018)

  • v2.20.2(May 22, 2018)

    With the new logo in place and everything prepared, I'm going to be focusing on developing for sol v3 now.

    This last release focuses on getting the semantics for configuration macros right and fixing some older warnings. It also handles some integer madness and does its best to straighten out exceptions.

    Newer development is going to specifically use features from C++17 and C++20, in an effort to bring the same performance, with BETTER, compile times and to investigate some of the issues discovered while writing the C++Now talk. This means that the v2.x.x releases will still work with VS 2015, and older toolsets, but the stuff in the branch sol3 will not.

    The sol3 branch will not be merged anytime soon, so don't worry about anything breaking unduly!

    Thanks for using sol2.

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(723.00 KB)
    sol_forward.hpp(11.37 KB)
  • v2.19.5(Mar 6, 2018)

    This release is a small Quality of Implementation fix. sol::reference and sol::object (but not their derived types) accept nil/none as types now when passing from C++-bound Lua functions. This emulates the default behavior of how Lua functions work. It also contains minor fixes for const vs. nonconst size() functions.

    This release also allows you to call the same function sol2 uses to set up good default tracebacks and a proper default protected_function error handler.



    Source code(tar.gz)
    Source code(zip)
    sol.hpp(703.43 KB)
    sol_forward.hpp(9.11 KB)
  • v2.19.4(Mar 2, 2018)

    This release provides an opt-out parameter for automagical types, full-on CMake support, and a myriad of other fixes and tweaks (especially to handle Eigen types). Thanks you everyone who reported issues and helped refine the library!

    This release also adds a new feature: sol::yielding, to define a function that yields it results back to Lua's control.

    Coroutines can now be constructed with an error_handler parameter, and sol2 will call that error handler in the case of failure to execute (much like protected_function). The default handler provides a traceback.

    yielding: automagical-opt-out: codecvt cleaned out:

    A new single header is provided, called "sol_forward": this contains all the forwarded declarations and allows some saving on compile times.

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(701.34 KB)
    sol_forward.hpp(9.11 KB)
  • v2.18.7(Nov 21, 2017)

    This release adds a coroutine guard from an issue investigation on gitter and prepares for new_experimental_usertype, and updates the readme and documentation to include a link for financial support, if that's your thing.

    Thank you for using sol2.

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(662.99 KB)
  • v2.18.6(Nov 21, 2017)

    This release adds some work arounds for classes that are declared final and thusly can't use sol's callable traits due to that limitation. It also improves the error handling and report for users who get errors with userdata, reporting a mirror of the actual type's name.

    This release also adds iterators to function result/protected function result, making them iterable by a terse for loop. An ipairs implementation swapping bug was also fixed in this release. LuaJIT should also no longer absolutely consume errors thrown by C++ on Linux and Windows.

    The tutorials and documentation have seen heavy improvements, and some of the tutorial code has now been properly serialized into a place for everyone to get it:

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(662.04 KB)
  • v2.18.5(Oct 30, 2017)

    This release adds some work arounds for classes that are declared final and thusly can't use sol's callable traits due to that limitation. It also improves the error handling and report for users who get errors with userdata, reporting a mirror of the actual type's name.

    This release also changes how expections are handled when we detect that it is possible to propagate errors through the Lua API boundary (e.g., when they're compiled as C++ or you're using LuaJIT compiled for a proper platform). In this case, we won't catch all exceptions: instead, they will be thrown without holding onto them.

    Also fixes: pairs/ipairs iteration bug

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(653.04 KB)
  • v2.18.4(Sep 24, 2017)

    This release of sol2 includes the addition of a new userdata checker/getter paradigm that allows non-sol2 usertypes to be integrated with sol2's mechanisms. There are a good chunk of examples from popular external frameworks, showcasing ways to do it. You can add your own custom logic to enable sol2 in your already millions-of-lines codebase and slowly ease out other libraries -- or not, and have the two play together perfectly nicely!

    Find your framework here, or just take a peek to see how it's done: Read about it in the stack API:

    Thanks to @feltech for bringing this to my attention and helping me work on it.

    Have fun, everyone!

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(637.82 KB)
  • v2.18.3(Sep 22, 2017)

    This release adds major additional support for coroutines and threading, improving the documentation and adding examples to demonstrate new uses. It also outlines a few helpful ways to handle multiple threads in a Lua environment and ways that it can affect things.

    • Threading:
    • New Coroutine Example:

    This release also includes a new compatibility layer and a shiny new clang formatter and the preparations for more robust cross-platform testing.

    Thank you to everyone who contributed to this release!

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(635.41 KB)
  • v2.18.2(Sep 3, 2017)

    This release adds some much-needed clarity to the error messages received. Alongside stack information, more descriptive errors are now serialized into the error strings, increasing the ability to reason about bugs. Android bugs and small typos have also been corrected.

    This release also includes a breaking change that will affect a tiny fraction of users using the nitty-gritty of the customization points with full-fledged customization points for their own type. Specifically, the checker now needs a handler that takes 5 arguments, not 4 (the last is an error message). All handlers must be updated to take const char* or similar.

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(604.62 KB)
  • v2.18.1(Aug 28, 2017)

    This is an important bugfix release that fixes some garbage collection errors in simple_usertype and solves a variety of bugs. It also introduces a new modifer on functions and arguments to C/C++ function calls called "filters", similar to luabind's reference_to and policies. sol2 should now be nearly 100% feature-parity with luabind.

    Happy porting!


    • sol::filters abstraction -- thanks to @mrgreywater and @OrfeasZ for the bikeshedding and help in developing this feature. Implements #472.
    • __tostring metamethods are now generated from operator<<, to_string(obj), or obj.to_string() calls


    • Android not putting its math functions in the std:: namespace for some reason: #488
    • Bogus alignment errors: #487 (also fixed by upgrading VS2017 to its latest version)
    • Add explanations to heap space errors: #496 (
    • Fix issues with indestructible types and virtual destructor types: #492
    • Garbage collection issues: #489 #490 #491
    • Garbage collection is now applied to types even if someone does not specify a usertype for it. If the type is non-destructible, it will plant an erroring garbage collection function warning you of undefined behavior if you do not register a usertype in time to handle it
    Source code(tar.gz)
    Source code(zip)
    sol.hpp(600.26 KB)
  • v2.18.0(Aug 14, 2017)

    This is an enormous improvement release that adds several new features, including support for many household name C++17 types (variant and the like). It also includes a small amount of integer handling safety thanks to @mrgreywater and some inspiration for handling and dealing with containers types thanks to @iaz3 .


    • NEW Container support, overhauled and overridable by users (inspired by @s13n):
    • A new example for using require in Lua code with a DLL that is built with sol2:
    • A new example for working with containers and messing with traits:
    • Additional automatically-generated usertype operations, including tostring and pairs (pairs metamethod is only available in Lua 5.2+):
    • Overloading fallbacks for constructors and functions using variadic_args:
    • New number handling for safety, triggered by SOL_CHECK_ARGUMENTS. See this page for more information about safety changes:

    This release also introduces:

    • necessary thread safety usages when creating multiple states across threads (solving #458)
    • some new functions to work safely with called code:
    • additional handling for __stdcall on x86, solving @horatii's issue in #463 permanently (thanks for introducing a good fix on x86, @horatii)
    • Support for g++ 7.x.x and Visual Studio 2017+
    Source code(tar.gz)
    Source code(zip)
    sol.hpp(580.29 KB)
  • v2.17.5(Jun 13, 2017)

    This release marks one of the last ones that will support GCC 4.x, Clang 3.4/3.5/3.6, and old version of Visual Studio 2015. It contains fixes for MinGW's bad std::wstring/std::u16string handling, and some minor changes to handle compilation issues and new warnings on GCC 7.x. Bugfixes for older compilers will continue into the future for some time.

    For more information about what is happening with older compilers, see:

    sol2's future will be focusing on leveraging new C++17 features and types (std::any, std::variant, etc.) when they become widely-available across the Big Three™ compilers. Since sol2 has been feature-complete for a long time, future versions will more or less contain bells and whistles, and most of the code here is fairly bug-free for most uses.

    Thank you for supporting sol2, and we hope you continue using it into the far future.

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(495.18 KB)
  • v2.17.4(May 21, 2017)

    This release is a small patchfix to fix the way sol::readonly and std:: containers behave with move-only types. Documentation was updated for sol::readonly and the library was vetted for uses of is_const and is_copy_assignable. Documentation was also updated for Compiler Errors under the Error page in the sol2 documentation:

    Please do upgrade as soon as possible!

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(470.28 KB)
  • v2.17.3(May 17, 2017)

    This release includes some fixes for LuaJIT's beta. Please use LuaJIT-beta3, and not LuaJIT-beta2, as it is redefining some functions present in the compatibility wrapper but does not include its semantic versioning scheme in any of its macros in a usable format.

    This also fixes a bug in VS2013 CTP+ that does not perform qualified name lookup properly, even with a template alias.

    Finally, this_environment -- a convenience transparent function -- is now in sol2. Note that it does not work too terribly well when combined with someone calling a Lua function directly from C++ using std::function, sol::function, or similar. But, it will capture the environment of a script or function in a script calling your code fairly effectively.


    Have fun!

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(470.05 KB)
  • v2.17.1(Apr 25, 2017)

  • v2.17.0(Apr 16, 2017)

    I never expected to make this release, but just a short while after 2.16 there is now a 2.17.0! This release includes Environments, alongside a number of small bugfixes related to globals and static order initialization explosions.

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(455.83 KB)
  • v2.16.0(Mar 26, 2017)

    This release adds a new type of constructor syntax to usertypes and also allows them to be extended with methods defined in Lua at runtime or added through the named usertype table using the Lua API in C++. It also fixes numerous bugs and beefs up the testing suite to ensure that users are guaranteed a level of functional programming while using sol2.

    This also marks a level of "feature-completeness". Beyond users making new recommendations for features, this code is essentially deployment and production ready, as it has been for several releases, but now even moreso. There are no more planned features until C++21/22, when reflection will allow us to automate usertype creation entirely.

    Thanks for helping to make sol2 a wonderful library, and keep posting issues when you come across them!

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(443.42 KB)
  • v2.15.9(Feb 20, 2017)

    This release fixes a number of bugs related to usertypes and how they were used, including #346 - #347, #345 an #344!

    It also addressed a critical issue with usertypes and returning a temporary reference if you utilized a customization point in a specific manner. (#348)

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(439.06 KB)
  • v2.15.8(Feb 19, 2017)

    This release fixes many bugs that were filed between now and the last release, improving stability and solving a few very subtle "ouches" that affected a small portion of users rather prominently. Thanks to everyone who reported issues!

    It is highly recommended to upgrade to this version immediately, even if none of the bugs affected you directly.

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(437.87 KB)
  • v2.15.7(Jan 7, 2017)

    This release adds some state and thread awareness to the various pushers for sol2, making it easier to work with threads and pass arguments off to coroutines inside of C++.

    Fixes: #309 - this issue inspired adding the support as well as figuring out more about threading in general

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(433.43 KB)
  • v2.15.6(Jan 7, 2017)

    This release addresses a number of minor bugs and provides some updated documentation, as well as gives a new definition for handling Lua compiled as C++.

    Fixes: #306 - Building Lua as C++ now has a definition to make it easier to work with sol2: #304 - LuaJIT condition fixes #305 - default handlers becoming invalid for a given Lua state (still potentially problematic: e.g., see multiple Lua states and the fact that the function is static, provides a bit of a problem) #301 - Thread state deadness was default-defined, now defined to an out-of-the-way value #300 - Apple build failures not a problem, thankfully

    Source code(tar.gz)
    Source code(zip)
    sol.hpp(433.22 KB)
  • v2.15.4(Dec 5, 2016)

The Phantom Derpstorm
C++ is my jam (but I program in many other languages, too!)
The Phantom Derpstorm
A lightweight, dependency-free library for binding Lua to C++

LuaBridge 2.6 LuaBridge is a lightweight and dependency-free library for mapping data, functions, and classes back and forth between C++ and Lua (a po

Vinnie Falco 1.4k Jan 8, 2023
libffi wrapper for quickjs

Libffi wrapper for QuickJS. Now supports almost every features of C including primitive types, structs, callbacks and so on License MIT License Copyri

null 48 Dec 6, 2022
ChakraCore is an open source Javascript engine with a C API.

ChakraCore ChakraCore is a Javascript engine with a C API you can use to add support for Javascript to any C or C compatible project. It can be compil

null 8.8k Jan 2, 2023
Structy is an irresponsibly dumb and simple struct serialization/deserialization library for C, Python, and vanilla JavaScript.

Structy Structy is an irresponsibly dumb and simple struct serialization/deserialization library for C, Python, and vanilla JavaScript. You can think

Stargirl Flowers 53 Dec 29, 2022
Libraries and examples to support Pimoroni Pico add-ons in C++ and MicroPython.

Pimoroni Pico Libraries and Examples Welcome to the brave new world of Pico! This repository contains the C/C++ and MicroPython libraries for our rang

Pimoroni Ltd 775 Jan 8, 2023
Tools and libraries to glue C/C++ APIs to high-level languages

CppSharp is a tool and set of libraries which facilitates the usage of native C/C++ code with the .NET ecosystem. It consumes C/C++ header and library

Mono Project 2.5k Jan 9, 2023
A tool for generating cross-language type declarations and interface bindings.

Djinni Djinni is a tool for generating cross-language type declarations and interface bindings. It's designed to connect C++ with either Java or Objec

Dropbox 2.8k Jan 3, 2023
Duktape - embeddable Javascript engine with a focus on portability and compact footprint

Duktape ⚠️ Master branch is undergoing incompatible changes for Duktape 3.x. To track Duktape 2.x, follow the v2-maintenance branch. Introduction Dukt

Sami Vaarala 5.5k Jan 6, 2023
The missing bridge between Java and native C++

JavaCPP Commercial support: Introduction JavaCPP provides efficient access to native C++ inside Java, not unlike the way some C/C++ compilers interact

Bytedeco 4k Dec 28, 2022
Seamless operability between C++11 and Python

pybind11 — Seamless operability between C++11 and Python Setuptools example • Scikit-build example • CMake example Warning Combining older versions of

pybind 12.1k Jan 9, 2023
SWIG is a software development tool that connects programs written in C and C++ with a variety of high-level programming languages.

SWIG (Simplified Wrapper and Interface Generator) Version: 4.1.0 (in progress) Tagline: SWIG is a compiler that integrates C and C++ with languages

SWIG 4.8k Jan 5, 2023
A minimalist and mundane scripting language.

Drift Script A minimalist and mundane scripting language. I like all simple things, simple and beautiful, simple and strong. I know that all developme

Drift 12 Nov 14, 2022
An operating system. Its main goal? Readable code, developer experience and documentation.

OS Dependencies Required for development. sudo apt install build-essential nasm grub-pc-bin grub-common xorriso Required for building cross-compiler.

Stijn Rogiest 1 Nov 15, 2022
A beginner friendly repo in the world of open source. Contribute here to add here project in any languages.

Hacktober Fest 2021 Heyy There (●'◡'●) Here you can contribute to opensource project in any valid language and project. Just follow the contribution g

Anonymous-inception 6 May 24, 2022
Repository of some great classical and Advanced cryptosystems

CryptoSystems ?? Repository of some great classical and Advanced cryptosystems Every C file here contains one of the most popular Cryptosystem in hist

Abhilash Datta 3 Nov 8, 2022
Project to create a teensy based gamecube controller with hall effect sensors, snapback filtering, and notch calibration

PhobGCC Gamecube controller motherboard using a teensy as the microcontroller. Aim is to make an accessible and consistent controller. Has the option

null 95 Dec 31, 2022
Algorithms for sound filters, like reverb, dynamic range compression, lowpass, highpass, notch, etc

sndfilter Algorithms for sound filters, like reverb, dynamic range compression, lowpass, highpass, notch, etc. It's easy to find countless math equati

Sean 362 Dec 22, 2022
Make Lua great again

LuaLibs Lua 模块合集 • 让 Lua 再次伟大 Lua module collection · Makes Lua great again 已收录项目 项目名称 简介 开发者 Lua API 版本 是否跨平台 LuaHttpLib 阻塞式 HTTP 库 Voidmatrix 5.4.0

Voidmatrix 12 Jul 14, 2022
An advanced in-memory evasion technique fluctuating shellcode's memory protection between RW/NoAccess & RX and then encrypting/decrypting its contents

Shellcode Fluctuation PoC A PoC implementation for an another in-memory evasion technique that cyclically encrypts and decrypts shellcode's contents t

Mariusz Banach 619 Dec 27, 2022
Hello, I am creating this file to make everyone understand the basis of C++ language which is actually the advanced version of C but better than C because of its OOPs feature.

Hello-in-C++ ?? ?? FOR BEGINNERS IN C++ Hello, I am creating this file to make everyone understand the basics of C++ language which is actually the ad

Ankita Mohan 2 Dec 27, 2021