README.md
1# sol2
2
3[](http://sol2.readthedocs.io/en/latest/?badge=latest)
4
5
6
7sol2 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.
8
9
10
11## Sneak Peek
12
13```cpp
14#include <sol/sol.hpp>
15#include <cassert>
16
17int main() {
18 sol::state lua;
19 int x = 0;
20 lua.set_function("beep", [&x]{ ++x; });
21 lua.script("beep()");
22 assert(x == 1);
23}
24```
25
26```cpp
27#include <sol/sol.hpp>
28#include <cassert>
29
30struct vars {
31 int boop = 0;
32};
33
34int main() {
35 sol::state lua;
36 lua.new_usertype<vars>("vars", "boop", &vars::boop);
37 lua.script("beep = vars.new()\n"
38 "beep.boop = 1");
39 assert(lua.get<vars>("beep").boop == 1);
40}
41```
42
43More examples are given in the examples directory [here](https://github.com/ThePhD/sol2/tree/develop/examples).
44
45
46## Documentation
47
48Find 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/table_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.
49
50
51
52
53# "I need X Feature or Fix, Right Now™"
54
55Find the support option that's right for you, [here](https://github.com/ThePhD/.github/blob/main/SUPPORT.md)! If you're happy to wait, you can just file a boring issue and we'll get to it Whenever There Is Time™.
56
57
58
59## I want to donate to help!
60
61You can find [donation and sponorship options here](https://github.com/ThePhD/.github/blob/main/SUPPORT.md#support-in-general) 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!
62
63
64
65
66# Features
67
68- [Fastest in the land](http://sol2.readthedocs.io/en/latest/benchmarks.html) (see: sol3 bar in graph).
69- Supports retrieval and setting of multiple types including:
70 * `std::string`, `std::wstring`, `std::u16string` and `std::u32string` support (and for views).
71 * understands and works with containers such as `std::map/unordered_map`, c-style arrays, vectors, non-standard custom containers and more.
72 * user-defined types, with or **without** registering that type
73 * `std::unique_ptr`, `std::shared_ptr`, and optional support of other pointer types like `boost::shared_ptr`.
74 * custom `optional<T>` that works with references, and support for the inferior `std::optional`.
75 * C++17 support for variants and similar new types.
76- Lambda, function, and member function bindings are supported.
77- Intermediate type for checking if a variable exists.
78- Simple API that completely abstracts away the C stack API, including `protected_function` with the ability to use an error-handling function.
79- `operator[]`-style manipulation of tables
80- C++ type representations in Lua userdata as `usertype`s with guaranteed cleanup.
81- Customization points to allow your C++ objects to be pushed and retrieved from Lua as multiple consecutive objects, or anything else you desire!
82- Overloaded function calls: `my_function(1); my_function("Hello")` in the same Lua script route to different function calls based on parameters
83- Support for tables, nested tables, table iteration with `table.for_each` / `begin()` and `end()` iterators.
84- Zero string overhead for usertype function lookup.
85
86
87
88## Supported Compilers
89
90sol2 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:
91
92- GCC 7.x.x+ (MinGW 7.x.x+)
93- Clang 3.9.x+
94- Visual Studio 2017 Community (Visual C++ 15.0)+
95
96Please make sure you use the `-std=c++2a`, `-std=c++1z`, `-std=c++17` or better standard flags
97(some of these flags are the defaults in later versions of GCC, such as 7+ and better).
98
99If 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.
100
101sol3 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!
102
103
104
105## Creating a single header
106
107You can grab a single header (and the single forward header) out of the library [here](https://github.com/ThePhD/sol2/tree/develop/single). 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`](https://github.com/ThePhD/sol2/blob/develop/single/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.
108
109If 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.
110
111
112
113
114# Testing
115
116Testing 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.
117
118You 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).
119
120
121
122# Presentations
123
124"A Sun For the Moon - A Zero-Overhead Lua Abstraction using C++"
125ThePhD
126Lua Workshop 2016 - Mashape, San Francisco, CA
127[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2016.10.14%20-%20ThePhD%20-%20No%20Overhead%20C%20Abstraction.pdf)
128
129"Wrapping Lua C in C++ - Efficiently, Nicely, and with a Touch of Magic"
130ThePhD
131Boston C++ Meetup November 2017 - CiC (Milk Street), Boston, MA
132[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2017.11.08%20-%20ThePhD%20-%20Wrapping%20Lua%20C%20in%20C%2B%2B.pdf)
133
134"Biting the CMake Bullet"
135ThePhD
136Boston C++ Meetup February 2018 - CiC (Main Street), Cambridge, MA
137[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2018.02.06%20-%20ThePhD%20-%20Biting%20the%20CMake%20Bullet.pdf)
138
139"Compile Fast, Run Faster, Scale Forever: A look into the sol2 Library"
140ThePhD
141C++Now 2018 - Hudson Commons, Aspen Physics Center, Aspen, Colorado
142[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)
143
144"Scripting at the Speed of Thought: Using Lua in C++ with sol3"
145ThePhD
146CppCon 2018 - 404 Keystone, Meydenbauer Center, Aspen, Colorado
147[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2018.09.28%20-%20ThePhD%20-%20Scripting%20at%20the%20Speed%20of%20Thought.pdf)
148
149"The Plan for Tomorrow: Compile-Time Extension Points in C++"
150ThePhD
151C++Now 2019 - Flug Auditorium, Aspen Physics Center, Aspen, Colorado
152[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2019.05.10%20-%20ThePhD%20-%20The%20Plan%20for%20Tomorrow%20-%20Compile-Time%20Extension%20Points%20in%20C%2b%2b.pdf)
153
154
155
156
157# License
158
159sol2 is distributed with an MIT License. You can see LICENSE.txt for more info.
160
161If you need a custom solution, [feel free to reach out](https://soasis.org/contact/opensource/).
162