From e97913c97dd16dd3001d1674d4ab20b43ff9d6b0 Mon Sep 17 00:00:00 2001 From: ThePhD Date: Fri, 13 May 2016 11:50:06 -0400 Subject: [PATCH] [ci-skip] heavy documentation updates. Closes #89 --- docs/source/cmake.rst | 54 +++++++++++++++++++ docs/source/features.rst | 111 +++++++++++++++++++-------------------- docs/source/index.rst | 3 +- docs/source/origin.rst | 2 +- 4 files changed, 112 insertions(+), 58 deletions(-) create mode 100644 docs/source/cmake.rst diff --git a/docs/source/cmake.rst b/docs/source/cmake.rst new file mode 100644 index 00000000..2d9e378d --- /dev/null +++ b/docs/source/cmake.rst @@ -0,0 +1,54 @@ +CMake Script +============ + +Thanks to `Kevin Brightwell`_, you can drop this CMake Script into your CMake Projects to have Sol part of one of its builds: + +.. code-block:: cmake + :caption: CMake Build Script + :name: cmake-build-script + + # Needed for ExternalProject_Add() + include(ExternalProject) + + # Needed for building single header for sol2 + find_package(PythonInterp 3 REQUIRED) + + # Configuration data for What sol2 version to use and where to put it + set(SOL2_TAG v2.5.6) + set(SOL2_HPP "${CMAKE_BINARY_DIR}/include/sol.hpp") + + # Download and "install" sol2 + ExternalProject_add( + sol2 + PREFIX ${VENDOR_PATH} # Set this value yourself + + GIT_REPOSITORY "https://github.com/ThePhD/sol2.git" + GIT_TAG ${SOL2_TAG} + + # No CMake commands to run, so tell CMake not to configure + CONFIGURE_COMMAND "" + + # Generate the single header and put it in ${SOL2_HPP} + BINARY_DIR ${VENDOR_PREFIX}/src/sol2 + BUILD_COMMAND + ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/include + COMMAND + ${PYTHON_EXECUTABLE} ./single.py -o "${SOL2_HPP}" + + # No install or test command for the library + INSTALL_COMMAND "" + TEST_COMMAND "") + + # Conditionally turn on SOL_CHECK_ARGUMENTS if using Debug mode + if (CMAKE_BUILD_TYPE MATCHES "[Dd]ebug") + if (VERBOSE) + message(STATUS "Turning on SOL_CHECK_ARGUMENTS in Debug mode.") + endif() + add_definitions(-DSOL_CHECK_ARGUMENTS) + endif() + + # Make sure sol2 is found as a system directory + include_directories(SYSTEM ${CMAKE_BINARY_DIR}/include) + + +.. _Kevin Brightwell: https://github.com/ThePhD/sol2/issues/89 diff --git a/docs/source/features.rst b/docs/source/features.rst index d4f31e7f..a702adb8 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst @@ -82,56 +82,56 @@ Explanations for a few categories are below (rest are self-explanatory). * lua thread: basic wrapping of the lua thread API; ties in with coroutine. * coroutines: allowing a function to be called multiple times, -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| | plain C | luawrapper | lua-intf | luabind | Selene | Sol | oolua | lua-api-pp | kaguya | SLB | SWIG | luacppinterface | -| | | | | | | | | | | | | | -+===========================+=============+============+==========+=========+==========+===========+===========+================+==========+==========+===========+=================+ -| optional | ~ | ✗ | ✗ | ✗ | ✗ | ✔ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| tables | ~ | ~ | ~ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ | ✗ | ✗ | ~ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| table chaining | ~ | ~ | ~ | ✔ | ✔ | ✔ | ✗ | ✔ | ✔ | ✗ | ✗ | ~ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| arbitrary keys | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | ~ | ✔ | ✗ | ✗ | ✗ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| user-defined types (udts) | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| udts: member functions | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| udts: variables | ~ | ~ | ~ | ~ | ~ | ✔ | ~ | ~ | ~ | ✗ | ✔ | ✗ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| stack abstractions | ~ | ✔ | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ~ | ✗ | ~ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| lua function from C(++) | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| function binding | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ~ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| protected function | ~ | ✗ | ~ | ~ | ~ | ✔ | ~ | ✔ | ~ | ~ | ~ | ~ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| multi-return | ~ | ✗ | ✗ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ | ~ | ✔ | ~ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| inheritance | ~ | ✗ | ✗ | ✔ | ✔ | ✔ | ~ | ~ | ✔ | ~ | ✔ | ~ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| overloading | ~ | ✗ | ✗ | ✗ | ✗ | ✔ | ✗ | ✗ | ✔ | ✔ | ✔ | ✗ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| lua thread | ~ | ✗ | ✗ | ✗ | ✗ | ✔ | ✔ | ✗ | ✔ | ✗ | ✗ | ✗ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| coroutines | ~ | ✗ | ✗ | ✔ | ✔ | ✔ | ✗ | ✗ | ✔ | ✗ | ✗ | ✗ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| no-rtti support | ✔ | ✗ | ~ | ✗ | ✗ | ✔ | ✔ | ✗ | ✔ | ✔ | ~ | ✔ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| no-exception support | ✔ | ✗ | ~ | ~ | ✗ | ✔ | ✔ | ✗ | ✔ | ✔ | ~ | ✔ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| Lua 5.1 | ✔ | ✔ | ~ | ✔ | ✗ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| Lua 5.2 | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| Lua 5.3 | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| luajit | ✔ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ -| distribution | compile | header | both | compile | header | header | compile | compile | header | compile | generated | compile | -+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+ ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| | plain C | luawrapper | lua-intf | luabind | Selene | Sol | oolua | lua-api-pp | kaguya | SLB | SWIG | luacppinterface | luwra | +| | | | | | | | | | | | | | | ++===========================+=============+============+==========+=========+==========+===========+===========+================+==========+==========+===========+=================+=======+ +| optional | ~ | ✗ | ✗ | ✗ | ✗ | ✔ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| tables | ~ | ~ | ~ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ | ✗ | ✗ | ~ | ✔ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| table chaining | ~ | ~ | ~ | ✔ | ✔ | ✔ | ✗ | ✔ | ✔ | ✗ | ✗ | ~ | ✔ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| arbitrary keys | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | ~ | ✔ | ✗ | ✗ | ✗ | ✗ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| user-defined types (udts) | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| udts: member functions | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| udts: variables | ~ | ~ | ~ | ~ | ~ | ✔ | ~ | ~ | ~ | ✗ | ✔ | ✗ | ~ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| stack abstractions | ~ | ✔ | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ~ | ✗ | ~ | ✔ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| lua function from C(++) | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| function binding | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| protected function | ~ | ✗ | ~ | ~ | ~ | ✔ | ~ | ✔ | ~ | ~ | ~ | ~ | ~ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| multi-return | ~ | ✗ | ✗ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ | ~ | ✔ | ~ | ~ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| inheritance | ~ | ✗ | ✗ | ✔ | ✔ | ✔ | ~ | ~ | ✔ | ~ | ✔ | ~ | ✗ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| overloading | ~ | ✗ | ✗ | ✗ | ✗ | ✔ | ✗ | ✗ | ✔ | ✔ | ✔ | ✗ | ✗ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| lua thread | ~ | ✗ | ✗ | ✗ | ✗ | ✔ | ✔ | ✗ | ✔ | ✗ | ✗ | ✗ | ✗ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| coroutines | ~ | ✗ | ✗ | ✔ | ✔ | ✔ | ✗ | ✗ | ✔ | ✗ | ✗ | ✗ | ✗ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| no-rtti support | ✔ | ✗ | ~ | ✗ | ✗ | ✔ | ✔ | ✗ | ✔ | ✔ | ~ | ✔ | ~ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| no-exception support | ✔ | ✗ | ~ | ~ | ✗ | ✔ | ✔ | ✗ | ✔ | ✔ | ~ | ✔ | ~ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| Lua 5.1 | ✔ | ✔ | ~ | ✔ | ✗ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | ~ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| Lua 5.2 | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| Lua 5.3 | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| luajit | ✔ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | ~ | ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ +| distribution | compile | header | both | compile | header | header | compile | compile | header | compile | generated | compile | header| ++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+-------+ notes on implementations @@ -238,10 +238,9 @@ oolua - luwra - -* Mentioned here because... well, it's a thing -* Lightweight (read: feature-starved) wrapper library -* Can push/pop to the global namespace, but doing anymthing more detailed is... harder -* Might as well go with luawrapper if you're going to bother +* Recently improved by a lot: can chain tables and such, even if performance is a bit sad for that use case +* Function calls and the like ridiculously fast, but uses macros to get there (can a template solution do just as good? Sol is going to find out!) +* Can push/pop to the global namespace, but doing anything more detailed is... harder +* No member variable support - get turned into getter/setter functions, similar to kaguya - -.. _Go read the docs: https://oolua.org/docs/index.html \ No newline at end of file +.. _Go read the docs: https://oolua.org/docs/index.html diff --git a/docs/source/index.rst b/docs/source/index.rst index b0919288..efe37147 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -27,12 +27,13 @@ get going: tutorial/all-the-things tutorial/tutorial-top - api/api-top features + api/api-top benchmarks safety exceptions rtti + cmake licenses origin diff --git a/docs/source/origin.rst b/docs/source/origin.rst index 3abd9d6f..cc2e3d72 100644 --- a/docs/source/origin.rst +++ b/docs/source/origin.rst @@ -11,7 +11,7 @@ And lo, `Danny Y., Rapptz`_ did stand firm in the sea and cast his hands to the seriously --------- -Sol was originally started by many moon cycles ago to interop with Lua and C++. `Rapptz`_ It was very successful and many rejoiced at having an easy to use abstraction on top of the Lua API. Rapptz continued to make a number of great projects and has been busy with other things, so upon seeing the repository grow stagnant and tired in the last year, `ThePhD`_ forked it into Sol2 and rebooted the code with the hopes of reaching the Milestone and the documentation you have today. +Sol was originally started by many moon cycles ago to interop with Lua and C++. `Rapptz`_ It was very successful and many rejoiced at having an easy to use abstraction on top of the Lua API. Rapptz continued to make a number of great projects and has been busy with other things, so upon seeing the repository grow stagnant and tired in the last very long while (over a year), `ThePhD`_ forked it into Sol2 and rebooted the code with the hopes of reaching the Milestone and the documentation you have today. To get to the old repo, head over `here`_.