sol2/documentation/source/tutorial/getting-started.rst

getting started
===============

Let's get you going with sol! To start, you'll need to use a lua distribution of some sort. sol doesn't provide that: it only wraps the API that comes with it, so you can pick whatever distribution you like for your application. There are lots, but the two popular ones are `vanilla Lua`_ and speedy `LuaJIT`_ . We recommend vanilla Lua if you're getting started, LuaJIT if you need speed and can handle some caveats: the interface for sol doesn't change no matter what Lua version you're using.

If you need help getting or building Lua, check out the `Lua page on getting started`_. Note that for Visual Studio, one can simply download the sources, include all the Lua library files in that project, and then build for debug/release, x86/x64/ARM rather easily and with minimal interference. Just make sure to adjust the Project Property page to build as a static library (or a DLL with the proper define set in the ``Preprocessor`` page, eg. `LUA_BUILD_AS_DLL=1`).

After that, make sure you grab either the `single header file release`_, or just perform a clone of the `github repository here`_ and set your include paths up so that you can get at ``sol.hpp`` somehow. Note that we also have the latest version of the single header file with all dependencies included kept in the `repository as well`_. We recommend the single-header-file release, since it's easier to move around, manage and update if you commit it with some form of version control. You can also clone/submodule the repository and then point at the `single/sol/sol.hpp`_ on your include files path. Clone with:

>>> git clone https://github.com/ThePhD/sol2.git

When you're ready, try compiling this short snippet:

.. literalinclude:: ../../../examples/source/tutorials/first_snippet.cpp
	:lines: 1-4, 8-
	:linenos:
	:caption: hello_lua.cpp
	:name: hello-lua

Using this simple command line:

>>> g++ -std=c++17 test.cpp -I"path/to/sol/include" -I"path/to/lua/include" -L"path/to/lua/lib" -llua

Or using your favorite IDE / tool after setting up your include paths and library paths to Lua according to the documentation of the Lua distribution you got. Remember your linked lua library (``-llua``) and include / library paths will depend on your OS, file system, Lua distribution and your installation / compilation method of your Lua distribution.

.. note::
	
	If you get an avalanche of errors (particularly referring to ``auto``), you may not have enabled C++14 / C++17 mode for your compiler. Add one of ``std=c++17``, ``std=c++1z`` OR ``std=c++1y`` to your compiler options. By default, this is always-on for VC++ compilers in Visual Studio and friends, but g++ and clang++ require a flag (unless you're on `GCC 6.0`_ or better).

If this works, you're ready to start! The first line creates the ``lua_State`` and will hold onto it for the duration of the scope its declared in (e.g., from the opening ``{`` to the closing ``}``). It will automatically close / cleanup that lua state when it gets destructed.

The second line opens a single lua-provided library, "base". There are several other libraries that come with lua that you can open by default, and those are included in the :ref:`sol::lib<lib-enum>` enumeration. You can open multiple base libraries by specifying multiple ``sol::lib`` arguments:

.. literalinclude:: ../../../examples/source/tutorials/open_multiple_libraries.cpp
	:lines: 1-4, 8-
	:linenos:
	:caption: multiple_libraries.cpp
	:name: open-multiple-libraries

If you're interested in integrating sol with a project that already uses some other library or Lua in the codebase, check out the :doc:`existing example<existing>` to see how to work with sol when you add it to a project (the existing example covers ``require`` as well)!

.. note::

	After you learn the basics of sol, it is usually advised that if you think something can work, you should TRY IT. It will probably work!


Some more ways of loading scripts and handling errors is shown `in this example`_! There is also a full, cross-platform `example of loading a DLL`_.

Next, let's start :doc:`reading/writing some variables<variables>` from Lua into C++, and vice-versa!


.. _vanilla Lua: https://www.lua.org/
.. _LuaJIT: http://luajit.org/
.. _GCC 6.0: https://gcc.gnu.org/gcc-6/changes.html
.. _single header file release: https://github.com/ThePhD/sol2/releases
.. _repository as well: https://github.com/ThePhD/sol2/blob/develop/single/include/sol/sol.hpp
.. _single/sol/sol.hpp: https://github.com/ThePhD/sol2/blob/develop/single/include/sol/sol.hpp
.. _github repository here: https://github.com/ThePhD/sol2
.. _Lua page on getting started: https://www.lua.org/start.html
.. _in this example: https://github.com/ThePhD/sol2/blob/develop/examples/source/basic.cpp
.. _example of loading a DLL: https://github.com/ThePhD/sol2/tree/develop/examples/require_dll_example