1## Sol 2.20 2 3[![Join the chat in Discord: https://discord.gg/buxkYNT](https://img.shields.io/badge/Discord-Chat!-brightgreen.svg)](https://discord.gg/buxkYNT) 4 5[![Linux & Max OSX Build Status](https://travis-ci.org/ThePhD/sol2.svg?branch=develop)](https://travis-ci.org/ThePhD/sol2) 6[![Windows Build status](https://ci.appveyor.com/api/projects/status/n38suofr21e9uk7h?svg=true)](https://ci.appveyor.com/project/ThePhD/sol2) 7[![Documentation Status](https://readthedocs.org/projects/sol2/badge/?version=latest)](http://sol2.readthedocs.io/en/latest/?badge=latest) 8 9Sol 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. 10The library is header-only for easy integration with projects. 11 12## Documentation 13 14Find it [here](http://sol2.rtfd.io/). A run-through kind of tutorial is [here](http://sol2.readthedocs.io/en/latest/tutorial/all-the-things.html)! 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](https://github.com/ThePhD/sol2/tree/develop/examples) as well. 15 16## Sneak Peek 17 18```cpp 19#include <sol/sol.hpp> 20#include <cassert> 21 22int main() { 23 sol::state lua; 24 int x = 0; 25 lua.set_function("beep", [&x]{ ++x; }); 26 lua.script("beep()"); 27 assert(x == 1); 28} 29``` 30 31```cpp 32#include <sol/sol.hpp> 33#include <cassert> 34 35struct vars { 36 int boop = 0; 37}; 38 39int main() { 40 sol::state lua; 41 lua.new_usertype<vars>("vars", "boop", &vars::boop); 42 lua.script("beep = vars.new()\n" 43 "beep.boop = 1"); 44 assert(lua.get<vars>("beep").boop == 1); 45} 46``` 47 48More examples are given in the examples directory [here](https://github.com/ThePhD/sol2/tree/develop/examples). 49 50## Supporting 51 52Help the project grow on [patreon](https://www.patreon.com/thephd)! 53 54You can also [donate to support Sol](https://www.paypal.me/LMeneide), which is always appreciated! There are reward tiers for patrons on patreon, too! 55 56You 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. 57 58## Presentations 59 60"A Sun For the Moon - A Zero-Overhead Lua Abstraction using C++" 61ThePhD 62Lua Workshop 2016 - Mashape, San Francisco, CA 63[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2016.10.14%20-%20ThePhD%20-%20No%20Overhead%20C%20Abstraction.pdf) 64 65"Wrapping Lua C in C++ - Efficiently, Nicely, and with a Touch of Magic" 66ThePhD 67Boston C++ Meetup November 2017 - CiC (Milk Street), Boston, MA 68[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2017.11.08%20-%20ThePhD%20-%20Wrapping%20Lua%20C%20in%20C%2B%2B.pdf) 69 70"Biting the CMake Bullet" 71ThePhD 72Boston C++ Meetup February 2018 - CiC (Main Street), Cambridge, MA 73[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2018.02.06%20-%20ThePhD%20-%20Biting%20the%20CMake%20Bullet.pdf) 74 75"Compile Fast, Run Faster, Scale Forever: A look into the sol2 Library" 76ThePhD 77C++Now 2018 - Hudson Commons, Aspen Physics Center, Aspen, Colorado 78[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2018.05.10%20-%20ThePhD%20-%20Compile%20Fast%2C%20Run%20Faster%2C%20Scale%20Forever.pdf) 79 80"Scripting at the Speed of Thought: Using Lua in C++ with sol3" 81ThePhD 82CppCon 2018 - 404 Keystone, Meydenbauer Center, Aspen, Colorado 83[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2018.09.28%20-%20ThePhD%20-%20Scripting%20at%20the%20Speed%20of%20Thought.pdf) 84 85## Creating a single header 86 87You can grab a single header (and the single forward header) out of the library [here](https://github.com/ThePhD/sol2/tree/develop/single/sol). 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. 88 89If 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. 90 91## Features 92 93- [Fastest in the land](http://sol2.readthedocs.io/en/latest/benchmarks.html) (see: sol bar in graph). 94- Supports retrieval and setting of multiple types including: 95 * `std::string`, `std::wstring`, `std::u16string` and `std::u32string` support (and for views). 96 * understands and works with containers such as `std::map/unordered_map`, c-style arrays, vectors, non-standard custom containers and more. 97 * user-defined types, with or **without** registering that type 98 * `std::unique_ptr`, `std::shared_ptr`, and optional support of other pointer types like `boost::shared_ptr`. 99 * custom `optional<T>` that works with references. 100 * C++17 support for variants and similar new types. 101- Lambda, function, and member function bindings are supported. 102- Intermediate type for checking if a variable exists. 103- Simple API that completely abstracts away the C stack API, including `protected_function` with the ability to use an error-handling function. 104- `operator[]`-style manipulation of tables 105- C++ type representations in lua userdata as `usertype`s with guaranteed cleanup. 106- Customization points to allow your C++ objects to be pushed and retrieved from Lua as multiple consecutive objects, or anything else you desire! 107- Overloaded function calls: `my_function(1); my_function("Hello")` in the same lua script route to different function calls based on parameters 108- Support for tables, nested tables, table iteration with `table.for_each` / `begin()` and `end()` iterators. 109- Zero overhead for usertype function call lookup when using `SOL_USE_BOOST`, safe for critical applications 110 111## Supported Compilers 112 113Sol 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) 114or higher should be able to compile without problems. However, the officially supported and CI-tested compilers are: 115 116- GCC 5.x.x+ (MinGW 5.x.x+) 117- Clang 3.6.x+ 118- Visual Studio 2015 Community (Visual C++ 14.0)+ 119 120Please make sure you use the `-std=c++1y`, `-std=c++14`, `-std=c++1z`, `-std=c++17` or better standard flags 121(some of these flags are the defaults in later versions of GCC, such as 6+ and better). 122 123Older compilers (GCC 4.9.x, Clang 3.4.x seem to be the lowest) can work with versions as late 124as [v2.17.5](https://github.com/ThePhD/sol2/releases/tag/v2.17.5), with the flag `-std=c++14` or `-std=c++1y`. 125 126sol2 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. 127 128## Running the Tests 129 130Testing 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. 131 132You 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. 133 134## License 135 136Sol is distributed with an MIT License. You can see LICENSE.txt for more info. 137