🎉 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 https://github.com/ThePhD/sol2/pull/1056
• Fix typos in configuration macros. by @atom0s in https://github.com/ThePhD/sol2/pull/1058
• Add override qualifier to bad_optional_access::what() by @cuavas in https://github.com/ThePhD/sol2/pull/1065
• Fixed typos in quick n' dirty tutorial. by @TwinHits in https://github.com/ThePhD/sol2/pull/1077
• Ignore unused variables; Ignore -Wshadow and -Wconversion on Clang by @dimitrisudell in https://github.com/ThePhD/sol2/pull/1059
• Fix argument usage typo. by @atom0s in https://github.com/ThePhD/sol2/pull/1091
• Support constexpr boost::none with recent Boost versions. by @vlichevsky in https://github.com/ThePhD/sol2/pull/1129
• Remove duplicate constructor type section from docs by @Riyyi in https://github.com/ThePhD/sol2/pull/1116
• Added FFI enabled check by @RinatNamazov in https://github.com/ThePhD/sol2/pull/1194
• Fix sol2 cmake include failing as a dependency by @edunad in https://github.com/ThePhD/sol2/pull/1196
• Fix aligned memory allocation by @Smertig in https://github.com/ThePhD/sol2/pull/1193
• Update is_string_constructible for C++23 P2166R1 by @StephanTLavavej in https://github.com/ThePhD/sol2/pull/1222
• Fixed: std::cout not found on msvc by @Klaim in https://github.com/ThePhD/sol2/pull/1295
• Add missing parenthesis for std::max by @halx99 in https://github.com/ThePhD/sol2/pull/1292
• Fix issues with is_c_str_or_string and is_c_str by @cschreib in https://github.com/ThePhD/sol2/pull/1331
• 🐛 Fix #1346 by @Immortalety in https://github.com/ThePhD/sol2/pull/1347
• ✨ Test and fix #1315 by @ShepherdSoasis in https://github.com/ThePhD/sol2/pull/1369
• CMake: Build LuaJIT: use copy_if_different by @DerSauron in https://github.com/ThePhD/sol2/pull/1352
• Fix compile error when registering new user types with operator() by @matusfedorko in https://github.com/ThePhD/sol2/pull/1277
• fix #1354 by @qinix in https://github.com/ThePhD/sol2/pull/1355

New Contributors

• @violinyanev made their first contribution in https://github.com/ThePhD/sol2/pull/1056
• @atom0s made their first contribution in https://github.com/ThePhD/sol2/pull/1058
• @cuavas made their first contribution in https://github.com/ThePhD/sol2/pull/1065
• @TwinHits made their first contribution in https://github.com/ThePhD/sol2/pull/1077
• @dimitrisudell made their first contribution in https://github.com/ThePhD/sol2/pull/1059
• @vlichevsky made their first contribution in https://github.com/ThePhD/sol2/pull/1129
• @Riyyi made their first contribution in https://github.com/ThePhD/sol2/pull/1116
• @RinatNamazov made their first contribution in https://github.com/ThePhD/sol2/pull/1194
• @edunad made their first contribution in https://github.com/ThePhD/sol2/pull/1196
• @StephanTLavavej made their first contribution in https://github.com/ThePhD/sol2/pull/1222
• @Klaim made their first contribution in https://github.com/ThePhD/sol2/pull/1295
• @halx99 made their first contribution in https://github.com/ThePhD/sol2/pull/1292
• @cschreib made their first contribution in https://github.com/ThePhD/sol2/pull/1331
• @Immortalety made their first contribution in https://github.com/ThePhD/sol2/pull/1347
• @ShepherdSoasis made their first contribution in https://github.com/ThePhD/sol2/pull/1369
• @DerSauron made their first contribution in https://github.com/ThePhD/sol2/pull/1352
• @matusfedorko made their first contribution in https://github.com/ThePhD/sol2/pull/1277
• @qinix made their first contribution in https://github.com/ThePhD/sol2/pull/1355

Full Changelog: https://github.com/ThePhD/sol2/compare/v3.2.3...v3.3.0

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 - https://sol2.readthedocs.io/en/latest/safety.html
• 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 (https://sol2.readthedocs.io/en/latest/safety.html):
  • SOL_CONTAINERS_START
  • SOL_NO_THREAD_LOCAL
  • 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 !)

This release is basically what it says on the tin: please stop erroring my users, Visual Studio.

Pretty please. :)

The tutorials were made better!

• C++ in Lua walkthrough was greatly enhanced for quality: https://sol2.readthedocs.io/en/latest/tutorial/cxx-in-lua.html

• Ownership is now very clearly explained (or at least better than before): https://sol2.readthedocs.io/en/latest/tutorial/ownership.html

• And various other minor documentation improvements

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

Have fun!~

This is the official sol3 release. Get it while it's hot, and read up about it using the blog posts and the documentation:

• https://thephd.github.io/sol3-released
• https://thephd.github.io/sol3-compile-times-binary-sizes
• https://sol2.rtfd.io

Thank you for your love and support over the years!

This fix backports a handling of the regular std::optional properly.

Thanks to everyone who made this release nice!

This release is a move of some of the bugfixes and improvements that were contained in sol3 back into sol2, with some modification to not break things!

This closes all known open issues, including those reported privately VIA Discord and E-mail. Thank you for your help in making sol2 great!

This release adds a number of bug fixes to 2.20 backported from current sol3 development. No major features were added in this change and it solves quite a few problems.

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.

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.

Docs: sol2.readthedocs.io/en/latest/api/state.html#sol-state-automatic-handlers

Example: https://github.com/ThePhD/sol2/blob/develop/examples/functions_empty_arguments.cpp

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: http://sol2.readthedocs.io/en/latest/api/yielding.html
automagical-opt-out: http://sol2.readthedocs.io/en/latest/api/usertype.html#automagical-usertypes
codecvt cleaned out: http://sol2.readthedocs.io/en/latest/codecvt.html

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

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.

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: https://github.com/ThePhD/sol2/tree/develop/examples/tutorials/quick_n_dirty

http://sol2.readthedocs.io/en/latest/tutorial/all-the-things.html

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

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: https://github.com/ThePhD/sol2/tree/develop/examples/interop
Read about it in the stack API: http://sol2.readthedocs.io/en/latest/api/stack.html#objects-extension-points

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

Have fun, everyone!

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: http://sol2.readthedocs.io/en/latest/threading.html
• New Coroutine Example: https://github.com/ThePhD/sol2/blob/develop/examples/coroutine_state.cpp

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!

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.

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!

Features:

• 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

Fixes:

• 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 (http://sol2.readthedocs.io/en/latest/errors.html#compiler-out-of-heap-space)
• 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

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 .

Notables:

• NEW Container support, overhauled and overridable by users (inspired by @s13n): http://sol2.readthedocs.io/en/latest/containers.html
• A new example for using require in Lua code with a DLL that is built with sol2: https://github.com/ThePhD/sol2/tree/develop/examples/require_dll_example
• A new example for working with containers and messing with traits: https://github.com/ThePhD/sol2/blob/develop/examples/container_usertype_as_container.cpp
• Additional automatically-generated usertype operations, including tostring and pairs (pairs metamethod is only available in Lua 5.2+): https://github.com/ThePhD/sol2/blob/develop/examples/usertype_automatic_operators.cpp
• Overloading fallbacks for constructors and functions using variadic_args: https://github.com/ThePhD/sol2/blob/develop/examples/overloading_with_fallback.cpp
• New number handling for safety, triggered by SOL_CHECK_ARGUMENTS. See this page for more information about safety changes: http://sol2.readthedocs.io/en/latest/safety.html#config

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: http://sol2.readthedocs.io/en/latest/api/state.html#state-script-function
• 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+

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: http://sol2.readthedocs.io/en/latest/compilation.html#supported-compilers

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.