From a9a190333908b55542c091fe58a49b4fed5cab32 Mon Sep 17 00:00:00 2001 From: ThePhD Date: Sat, 9 Apr 2016 17:54:19 -0400 Subject: [PATCH] improvements for the getting started tutorial based on iz's feedback. --- docs/source/features.rst | 9 +++++++-- docs/source/tutorial/getting-started.rst | 23 ++++++++++++++++++----- 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/source/features.rst b/docs/source/features.rst index 449edb21..33ff8345 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst @@ -89,7 +89,7 @@ Explanations for a few categories are below (rest are self-explanatory). +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ | tables | ~ | ~ | ✔ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ | ✗ | ✗ | ~ | +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| table chaining | ~ | ~ | ✔ | ✔ | ✔ | ✔ | ✗ | ✔ | ✔ | ✗ | ✗ | ~ | +| table chaining | ~ | ~ | ~ | ✔ | ✔ | ✔ | ✗ | ✔ | ✔ | ✗ | ✗ | ~ | +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ | arbitrary keys | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | ~ | ✔ | ✗ | ✗ | ✗ | +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ @@ -145,6 +145,7 @@ Plain C - kaguya - * Probably the closest in implementation details and interface to Sol itself +* member variables are automatically turned into ``obj:x( value )`` to set and ``obj:x()`` to get * Inspired coroutine support for Sol * Library author (satoren) is a nice guy! * C++11/14, or boostified (which makes it C++03 compatible) @@ -167,6 +168,7 @@ lua-intf - * Macro-based registration (strange pseudo-language) * Fairly fast in most regards * Registering classes/"modules" in using C++ code is extremely verbose +* In order to chain lookups, one has to do ``mykey.mykey2`` on the ``operator[]`` lookup (e.g., you can't nest them arbitrarily, you have to pre-compose the proper lookup string) (fails miserably for non-string lookups!). * Not too shabby! Selene - @@ -204,6 +206,8 @@ luabind - * One of the older frameworks, but has many people updating it and providing "deboostified" versions * Strange in-lua keywords and parsing to allow for classes to be written in lua - not sure if good feature; vendor lock-in to that library to depend on this specific class syntax? +* Comprehensive lua bindings (can even bind "properties") +* Wonky table support: no basic conversion functions on ``luabind::object``; have to push object then use lua API to get what you want lua-api-pp - @@ -225,7 +229,8 @@ SLB3 - oolua - * The syntax for this library is thicker than a brick. No, seriously. `Go read the docs`_ -* The worst in terms of how to use it: may have docs, but the DSL (despite using C++11) is extraordinarily crappy with thick, hard-to-debug/hard-to-error-check macros (and seems not to compile on VS 2015 Update 2 properly for Userdata bindings?) +* The worst in terms of how to use it: may have docs, but the DSL (despite using C++11) is extraordinarily crappy with thick, hard-to-debug/hard-to-error-check macros + - Same problem as lua-api-pp: cannot have the declaration macros anywhere but the toplevel namespace * Supports not having exceptions or rtti turned on (shiny!) * Poor RAII support: default-construct-and-get style (requires some form of initalization to perform a ``get`` of an object, and it's hard to extend) diff --git a/docs/source/tutorial/getting-started.rst b/docs/source/tutorial/getting-started.rst index 4dcd2961..bb78d61e 100644 --- a/docs/source/tutorial/getting-started.rst +++ b/docs/source/tutorial/getting-started.rst @@ -3,17 +3,20 @@ 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. -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. 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. +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. 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. If you use the github release, you *must* update submodules in order to make sure Optional is present in the repository: clone with: -.. 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++14``, ``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`_). +>>> git clone https://github.com/ThePhD/sol2.git +>>> git submodule update --init + +or, just run + +>>> git clone --recursive https://github.com/ThePhD/sol2.git When you're ready, try compiling this short snippet: .. code-block:: cpp :linenos: - :caption: the first snippet + :caption: test.cpp: the first snippet :name: the-first-snippet #include // or #include "sol.hpp", whichever suits your needs @@ -28,6 +31,16 @@ When you're ready, try compiling this short snippet: return 0; } +Using this simple command line: + +>>> g++ -std=c++14 test.cpp -llua -I"path/to/lua/include" -L"path/to/lua/lib" + +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++14``, ``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`_). + 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` enumeration. 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` to see how to work with Sol when you add it to a project!