🛠 Prepare for the a sol4 release...

- 🎨 Refactor the CMake a whle bunch

.clang-format

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 # 
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in

.dockerignore

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 # 
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in

.gitignore

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 # 
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in

.travis.yml

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 # 
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in

CMakeLists.txt

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 # 
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in
@@ -22,10 +22,10 @@
 
 # # # # sol3
 # # # Required minimum version statement
-cmake_minimum_required(VERSION 3.5.0)
+cmake_minimum_required(VERSION 3.15.0)
 
 # # # project declaration
-project(sol2 VERSION 3.2.3 LANGUAGES CXX C)
+project(sol2 VERSION 3.2.5 LANGUAGES CXX C)
 
 include(GNUInstallDirs)
 
@@ -36,13 +36,15 @@ include(GNUInstallDirs)
 set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake/Modules" "${CMAKE_MODULE_PATH}")
 
 # Include standard modules
-include(CMakeDependentOption)
 include(CMakePackageConfigHelpers)
-
+include(CheckCXXCompilerFlag)
+include(CMakeDependentOption)
+include(GNUInstallDirs)
+include(FetchContent)
 
 # # # Configuration
 # # Cached defines, strings, paths and options
-set(SOL2_LUA_VERSION "5.3.5" CACHE STRING "The version of Lua needed. Can be 5.1, 5.2, 5.3, 5.4, LuaJIT, or a more specific 3-part version number for a specifc Lua (e.g., 5.3.4 or luajit-2.0.5)")
+set(SOL2_LUA_VERSION "5.3.5" CACHE STRING "The version of Lua needed. Can be 5.1, 5.2, 5.3, 5.4, LuaJIT, or a more specific 3-part version number for a specifc Lua (e.g., 5.3.5 or luajit-2.0.5)")
 set(SOL2_BUILD_LUA TRUE CACHE BOOL "Always build Lua, do not search for it in the system")
 set(SOL2_PLATFORM "x64" CACHE STRING "Target platform to compile for when building binaries (x86, x64)")
 option(SOL2_CI "Whether or not we are in continguous integration mode" OFF)
@@ -161,7 +163,7 @@ endif()
 # Generates the docs
 if (SOL2_DOCS)
 	message(STATUS "sol2 adding docs...")
-	add_subdirectory(docs)
+	add_subdirectory(documentation)
 endif()
 
 if(SOL2_ENABLE_INSTALL)
@@ -277,13 +279,9 @@ if (SOL2_IS_TOP_LEVEL AND (SOL2_DO_TESTS OR SOL2_DO_EXAMPLES))
 		set_target_properties(${lualib}
 			PROPERTIES 
 			INTERFACE_INCLUDE_DIRECTORIES ${LUA_INCLUDE_DIR}
-			INTERFACE_LINK_LIBRARIES ${LUA_SEARCH_DEPENDENCY_LIBS}
+			INTERFACE_LINK_LIBRARIES ${LUA_SEARCH_DEPENDENCY_LIBS} ${CMAKE_DL_LIBS}
 			IMPORTED_LINK_INTERFACE_LANGUAGES C
 			IMPORTED_LOCATION ${lualiblocation})
-		if (CMAKE_DL_LIBS)
-			set_property(TARGET ${lualib}
-				APPEND PROPERTY INTERFACE_LINK_LIBRARIES ${CMAKE_DL_LIBS})
-		endif()
 		set(LUA_LIBRARIES ${lualib})
 	endif()
 

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

appveyor.yml

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 # 
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in

cmake/Modules/Common/Core.cmake

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 #
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in

cmake/Modules/FindCatch.cmake

@@ -1,84 +0,0 @@
-# # # # sol3
-# The MIT License (MIT)
-#
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy of
-# this software and associated documentation files (the "Software"), to deal in
-# the Software without restriction, including without limitation the rights to
-# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-# the Software, and to permit persons to whom the Software is furnished to do so,
-# subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-include(ExternalProject)
-include(FindPackageHandleStandardArgs)
-include(Common/Core)
-
-# # Base variables
-if (Catch_FIND_VERSION)
-	set(catch_version ${Catch_FIND_VERSION})
-else()
-	set(catch_version 2.11.1)
-endif()
-
-set(catch_lib catch_lib_${catch_version})
-
-# # Useful locations
-set(catch_build_toplevel "${CMAKE_BINARY_DIR}/vendor/catch_${catch_version}")
-set(catch_include_dirs "${catch_build_toplevel}")
-
-# # catch library sources
-set(catch_sources catch.hpp)
-prepend(catch_sources "${catch_build_toplevel}/" ${catch_sources})
-
-# # !! CMake 3.5 does not have DOWNLOAD_NO_EXTRACT e.e
-# # Now I know why people don't like CMake that much: the earlier versions were kind of garbage
-# # External project to get sources
-#ExternalProject_Add(CATCH_BUILD_SOURCE
-#	BUILD_IN_SOURCE TRUE
-#	BUILD_ALWAYS FALSE
-#	DOWNLOAD_NO_EXTRACT TRUE
-#	URL https://github.com/catchorg/Catch2/releases/download/v${catch_version}/catch.hpp
-#	TLS_VERIFY TRUE
-#	PREFIX ${catch_build_toplevel}
-#	SOURCE_DIR ${catch_build_toplevel}
-#	DOWNLOAD_DIR ${catch_build_toplevel}
-#	TMP_DIR "${catch_build_toplevel}-tmp"
-#	STAMP_DIR "${catch_build_toplevel}-stamp"
-#	INSTALL_DIR "${catch_build_toplevel}/local"
-#	CONFIGURE_COMMAND ""
-#	BUILD_COMMAND ""
-#	INSTALL_COMMAND ""
-#	TEST_COMMAND ""
-#	BUILD_BYPRODUCTS "${catch_sources}")
-
-file(MAKE_DIRECTORY "${catch_build_toplevel}")
-file(DOWNLOAD https://github.com/catchorg/Catch2/releases/download/v${catch_version}/catch.hpp ${catch_sources})
-
-add_library(${catch_lib} INTERFACE)
-# add_dependencies(${catch_lib} CATCH_BUILD_SOURCE)
-target_include_directories(${catch_lib} INTERFACE ${catch_include_dirs})
-
-if (MSVC)
-	target_compile_definitions(${catch_lib} INTERFACE
-		_SILENCE_CXX17_UNCAUGHT_EXCEPTION_DEPRECATION_WARNING)
-endif()
-
-set(CATCH_FOUND TRUE)
-set(CATCH_LIBRARIES ${catch_lib})
-set(CATCH_INCLUDE_DIRS ${catch_include_dirs})
-
-FIND_PACKAGE_HANDLE_STANDARD_ARGS(Catch
-	FOUND_VAR CATCH_FOUND
-	REQUIRED_VARS CATCH_LIBRARIES CATCH_INCLUDE_DIRS
-	VERSION_VAR catch_version)

cmake/Modules/FindKaguyaBuild.cmake

@@ -2,7 +2,7 @@
 # # # # sol3
 # The MIT License (MIT)
 #
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in

cmake/Modules/FindLua/set_version_vars.cmake

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 # 
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in

cmake/Modules/FindLuaBridgeBuild.cmake

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 #
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in

cmake/Modules/FindLuaBuild.cmake

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 #
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in

cmake/Modules/FindLuaBuild/LuaJIT.cmake

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 # 
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in
@@ -415,6 +415,8 @@ add_library(${lualib} INTERFACE)
 add_dependencies(${lualib} LUA_JIT-move)
 target_include_directories(${lualib}
 	INTERFACE "${LUA_JIT_SOURCE_DIR}")
+target_link_libraries(${lualib}
+		INTERFACE ${CMAKE_DL_LIBS})
 if (BUILD_LUA_AS_DLL)
 	if (MSVC)
 		target_link_libraries(${lualib}
@@ -428,10 +430,6 @@ else()
 		INTERFACE "${LUA_JIT_DESTINATION_LUA_LIB}")
 endif()
 
-if (CMAKE_DL_LIBS)
-	target_link_libraries(${lualib}
-		INTERFACE ${CMAKE_DL_LIBS})
-endif()
 if (XCODE)
 	target_compile_options(${lualib}
 		INTERFACE -pagezero_size 10000 -image_base 100000000)

cmake/Modules/FindLuaBuild/LuaVanilla.cmake

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 # 
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in
@@ -360,9 +360,7 @@ endif()
 target_compile_options(${liblua}
 	PRIVATE ${LUA_VANILLA_LUALIB_COMPILER_OPTIONS})
 add_dependencies(${liblua} LUA_VANILLA)
-if (CMAKE_DL_LIBS)
 target_link_libraries(${liblua} PRIVATE ${CMAKE_DL_LIBS})
-endif()
 if (UNIX)
 	target_link_libraries(${liblua} PRIVATE m)
 endif()
@@ -399,10 +397,7 @@ if (LUA_BUILD_LUA_INTERPRETER)
 		target_compile_definitions(${luainterpreter} 
 			PRIVATE LUA_USE_LINUX)
 	endif()
-	target_link_libraries(${luainterpreter} PRIVATE ${liblua})
-	if (CMAKE_DL_LIBS)
-		target_link_libraries(${luainterpreter} PRIVATE ${CMAKE_DL_LIBS})
-	endif()
+	target_link_libraries(${luainterpreter} PRIVATE ${liblua} ${CMAKE_DL_LIBS})
 	if (UNIX)
 		target_link_libraries(${luainterpreter} PRIVATE m readline)
 	endif()
@@ -437,10 +432,7 @@ if (LUA_BUILD_LUA_COMPILER)
 		target_compile_definitions(${luacompiler} 
 			PRIVATE LUA_USE_LINUX)
 	endif()
-	target_link_libraries(${luacompiler} PRIVATE ${liblua})
-	if (CMAKE_DL_LIBS)
-		target_link_libraries(${luacompiler} PRIVATE ${CMAKE_DL_LIBS})
-	endif()
+	target_link_libraries(${luacompiler} PRIVATE ${liblua} ${CMAKE_DL_LIBS})
 	if (UNIX)
 		# TODO: make readline optional?
 		target_link_libraries(${luacompiler} PRIVATE m readline)

cmake/Modules/FindLuwraBuild.cmake

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 #
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in

cmake/Modules/FindSphinx.cmake

@@ -0,0 +1,68 @@
+# # # # sol3
+# The MIT License (MIT)
+#
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+include(FindPackageHandleStandardArgs)
+include(FeatureSummary)
+
+find_program(Sphinx_Build_EXECUTABLE NAMES sphinx-build DOC "Path to sphinx-build executable")
+
+if (Sphinx_Build_EXECUTABLE)
+  set(Sphinx_Build_FOUND YES)
+endif()
+
+if (Sphinx_Build_FOUND)
+  execute_process(
+    COMMAND ${Sphinx_Build_EXECUTABLE} --version
+    OUTPUT_VARIABLE Sphinx_Build_VERSION_OUTPUT
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    ENCODING UTF-8)
+  if (Sphinx_Build_VERSION_OUTPUT)
+    string(REGEX
+      MATCH "[^0-9]*([0-9]+)[.]([0-9]+)?[.]?([0-9]+)?[.]?([0-9]+)?.*"
+      Sphinx_Build_VERSION_CHECK ${Sphinx_Build_VERSION_OUTPUT})
+  endif()
+  if (Sphinx_Build_VERSION_CHECK)
+    string(JOIN "." Sphinx_Build_VERSION
+      ${CMAKE_MATCH_1}
+      ${CMAKE_MATCH_2}
+      ${CMAKE_MATCH_3}
+      ${CMAKE_MATCH_4})
+    set(Sphinx_Build_VERSION "${Sphinx_Build_VERSION}" CACHE STRING "sphinx-build version" FORCE)
+  endif()
+endif()
+
+find_package_handle_standard_args(Sphinx
+  REQUIRED_VARS Sphinx_Build_EXECUTABLE
+  VERSION_VAR Sphinx_Build_VERSION
+  HANDLE_COMPONENTS)
+
+set_package_properties(Sphinx
+  PROPERTIES
+    DESCRIPTION "Sphinx Documentation Generator"
+    URL "https://sphinx-doc.org")
+
+if (Sphinx_Build_FOUND AND NOT TARGET Sphinx::Build)
+  add_executable(Sphinx::Build IMPORTED)
+  set_property(TARGET Sphinx::Build PROPERTY IMPORTED_LOCATION ${Sphinx_Build_EXECUTABLE})
+  set_property(TARGET Sphinx::Build PROPERTY VERSION ${Sphinx_Build_VERSION})
+  mark_as_advanced(Sphinx_Build_EXECUTABLE Sphinx_Build_VERSION)
+endif()

cmake/Modules/FindToLuappBuild.cmake

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 #
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in
@@ -65,7 +65,7 @@ set_target_properties(${toluapp_lib} PROPERTIES
 	POSITION_INDEPENDENT_CODE TRUE)
 target_include_directories(${toluapp_lib}
 	PUBLIC ${toluapp_include_dirs})
-target_link_libraries(${toluapp_lib} PRIVATE ${LUA_LIBRARIES})
+target_link_libraries(${toluapp_lib} PRIVATE ${LUA_LIBRARIES} ${CMAKE_DL_LIBS})
 if (MSVC)
 	target_compile_options(${toluapp_lib}
 		PRIVATE /W1)
@@ -77,9 +77,6 @@ else()
 		INTERFACE -Wno-noexcept-type
 		PUBLIC -Wno-ignored-qualifiers -Wno-unused-parameter)
 endif()
-if (CMAKE_DL_LIBS)
-	target_link_libraries(${toluapp_lib} PRIVATE ${CMAKE_DL_LIBS})
-endif()
 # add compatibility define
 target_compile_definitions(${toluapp_lib}
 		PRIVATE COMPAT53_PREFIX=toluapp_compat53)

cmake/sol2-config.cmake.in

@@ -1,7 +1,7 @@
 # # # # sol3
 # The MIT License (MIT)
 # 
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy of
 # this software and associated documentation files (the "Software"), to deal in

docs/CMakeLists.txt

@@ -1,46 +0,0 @@
-# # # # sol3
-# The MIT License (MIT)
-# 
-# Copyright (c) 2013-2020 Rapptz, ThePhD, and contributors
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy of
-# this software and associated documentation files (the "Software"), to deal in
-# the Software without restriction, including without limitation the rights to
-# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-# the Software, and to permit persons to whom the Software is furnished to do so,
-# subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-# # # # sol3, documentation generation
-# # # Required minimum version statement
-cmake_minimum_required(VERSION 3.5.0)
-	
-find_package(Python3 COMPONENTS Interpreter)
-
-if (NOT Python3_FOUND AND NOT Python3_Interpreter_FOUND)
-	message(FATAL_ERROR "sol2 documentation cannot be generated as python 3 has not been found: install or set the python 3 interpreter for the docs to find it and be sure to pip install sphinx")
-endif()
-
-find_program(sol2_make_executable make make.exe mingw32-make mingw32-make.exe)
-if(NOT sol2_make_executable)
-	message(FATAL_ERROR "could not find a suitable make executable to build Sphinx documentation")
-endif()
-
-add_custom_command(OUTPUT docs_invisible_file_always_generate
-	USES_TERMINAL
-	COMMAND "${sol2_make_executable}" -C "${CMAKE_CURRENT_SOURCE_DIR}" html "BUILDDIR=${CMAKE_CURRENT_BINARY_DIR}")
-add_custom_target(docs 
-	DEPENDS docs_invisible_file_always_generate)
-
-if(SOL2_ENABLE_INSTALL)
-	install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/docs/html" DESTINATION "${CMAKE_INSTALL_DOCDIR}")
-endif()

documentation/.clang-format

@@ -0,0 +1,110 @@
+# # # # sol3
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+BasedOnStyle: WebKit
+IndentWidth: 5
+TabWidth: 5
+ContinuationIndentWidth: 5
+UseTab: ForIndentation
+
+# Namespaces
+NamespaceIndentation: All
+CompactNamespaces: true
+FixNamespaceComments: true
+
+# Overall Alignment
+ColumnLimit: 75
+AlignAfterOpenBracket: DontAlign # uses ContinuationIndentWidth for this instead
+AccessModifierOffset: -5 # do not push public: or private: around
+#AlignConsecutiveAssignments: true # affects more than what's expected: do not use
+#AlignConsecutiveDeclarations: true # affects more than what's expected: do not use
+
+# Type Alignment
+DerivePointerAlignment: false
+PointerAlignment: Left
+AlwaysBreakTemplateDeclarations: true
+AlwaysBreakBeforeMultilineStrings: true
+
+# Comments
+AlignTrailingComments: true
+ReflowComments: true
+
+# Macros
+AlignEscapedNewlines: Left
+#IndentPPDirectives: None
+
+# Functions
+AllowShortFunctionsOnASingleLine: None
+AlwaysBreakAfterReturnType: None
+BreakConstructorInitializers: BeforeComma
+ConstructorInitializerIndentWidth: 0
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+BinPackArguments: false
+BinPackParameters: true
+
+# Classes
+BreakBeforeInheritanceComma: false
+
+# Braces
+Cpp11BracedListStyle: false
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterEnum: false
+  AfterStruct: false
+  AfterControlStatement: false
+  AfterClass: false
+  AfterNamespace: false
+  AfterStruct: false
+  AfterUnion: false
+  BeforeElse: true
+  BeforeCatch: true
+  IndentBraces: false
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: true
+
+# Control Statements
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+IndentCaseLabels: false
+
+# Spaces
+SpaceAfterCStyleCast: false
+SpacesInCStyleCastParentheses: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesInAngles: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+MaxEmptyLinesToKeep: 3
+
+# OCD
+SortUsingDeclarations: true
+SortIncludes: false
+
+---
+Language: Cpp
+Standard: Cpp11

documentation/CMakeLists.txt

@@ -0,0 +1,104 @@
+# # # # sol3
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+# # # # sol3, documentation generation
+# # # Required minimum version statement
+cmake_minimum_required(VERSION 3.15.0)
+	
+find_package(Doxygen REQUIRED)
+find_package(Python3 REQUIRED)
+find_package(Sphinx REQUIRED)
+
+# Find all the public headers
+file(GLOB_RECURSE sol2_public_headers
+  LIST_DIRECTORIES NO
+  CONFIGURE_DEPENDS ${PROJECT_SOURCE_DIR}/include/**.*)
+# make a list copy for use with dependency tracking later down below
+set(sol2_doxygen_public_headers ${sol2_public_headers})
+# Remove every single public header
+list(FILTER sol2_doxygen_public_headers EXCLUDE REGEX /detail/.*)
+# separate text with spaces and surround them with quotes for Doxygen to understand them all
+list(TRANSFORM sol2_doxygen_public_headers REPLACE "(.+)" [["\1"]])
+list(JOIN sol2_doxygen_public_headers " " sol2_doxygen_public_headers)
+
+set(SOL2_DOXYGEN_PROJECT_DESCRIPTION ${PROJECT_DESCRIPTION})
+set(SOL2_DOXYGEN_PROJECT_VERSION ${PROJECT_VERSION})
+set(SOL2_DOXYGEN_PROJECT_NAME ${PROJECT_NAME})
+set(SOL2_DOXYGEN_INPUT ${sol2_doxygen_public_headers})
+set(SOL2_DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
+set(SOL2_DOXYGEN_XML_OUTPUT_DIR ${SOL2_DOXYGEN_OUTPUT_DIR}/xml)
+set(SOL2_DOXYGEN_HTML_OUTPUT_DIR ${SOL2_DOXYGEN_OUTPUT_DIR}/html)
+set(SOL2_DOXYGEN_INDEX_FILE ${SOL2_DOXYGEN_XML_OUTPUT_DIR}/index.xml)
+set(SOL2_DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(SOL2_DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+set(SOL2_SPHINX_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/source)
+set(SOL2_SPHINX_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+
+# Get all Sphinx source files
+file(GLOB_RECURSE sol2_sphinx_sources
+  LIST_DIRECTORIES NO
+  CONFIGURE_DEPENDS ${SOL2_SPHINX_SOURCE_DIR}/**.*)
+
+#Replace variables inside @@ with the current values
+configure_file(${SOL2_DOXYFILE_IN} ${SOL2_DOXYFILE_OUT} @ONLY)
+
+# Ensure Doxygen/Sphinx won't crash because it doesn't create directories for us
+file(MAKE_DIRECTORY ${SOL2_DOXYGEN_OUTPUT_DIR})
+file(MAKE_DIRECTORY ${SOL2_DOXYGEN_XML_OUTPUT_DIR})
+file(MAKE_DIRECTORY ${SOL2_DOXYGEN_HTML_OUTPUT_DIR})
+file(MAKE_DIRECTORY ${SOL2_SPHINX_BUILD_DIR})
+
+set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_CLEAN_FILES
+  ${SOL2_DOXYGEN_XML_OUTPUT_DIR}
+  ${SOL2_DOXYGEN_HTML_OUTPUT_DIR}
+  ${SOL2_DOXYGEN_OUTPUT_DIR}
+  ${SOL2_SPHINX_BUILD_DIR})
+
+add_custom_command(OUTPUT ${SOL2_DOXYGEN_INDEX_FILE}
+	COMMAND ${DOXYGEN_EXECUTABLE} ${SOL2_DOXYFILE_OUT}
+	MAIN_DEPENDENCY ${SOL2_DOXYFILE_IN} ${SOL2_DOXYFILE_OUT}
+	DEPENDS ${sol2_public_headers}
+	COMMENT "[sol2/documentation] Generating Doxygen XML..."
+)
+add_custom_target(sol2.documentation.doxygen ALL DEPENDS ${SOL2_DOXYGEN_INDEX_FILE})
+
+if (NOT SOL2_DOCUMENTATION_NO_SPHINX)
+	add_custom_target(sol2.documentation.sphinx ALL
+    COMMAND Sphinx::Build
+      -b html
+      -Dbreathe_projects.sol2=${SOL2_DOXYGEN_XML_OUTPUT_DIR}
+      ${SOL2_SPHINX_SOURCE_DIR}
+      ${SOL2_SPHINX_BUILD_DIR}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    DEPENDS ${SOL2_DOXYGEN_INDEX_FILE} ${sol2_sphinx_sources}
+    COMMENT "[sol2/documentation] Generating Sphinx documentation..."
+    COMMAND_EXPAND_LISTS
+    VERBATIM)
+
+	add_dependencies(sol2.documentation.sphinx sol2.documentation.doxygen)
+endif()
+
+# For the install target
+include(GNUInstallDirs)
+install(DIRECTORY ${SOL2_SPHINX_BUILD_DIR}
+	DESTINATION ${CMAKE_INSTALL_DOCDIR}
+)

documentation/requirements.txt

@@ -0,0 +1,3 @@
+breathe
+cmake
+ninja

documentation/source/api/protected_function.rst

@@ -105,7 +105,8 @@ Get and set the Lua entity that is used as the default error handler. The defaul
 	:caption: variable: handler
 	:name: protected-function-error-handler
 
-	reference error_handler;
+	reference get_error_handler() const;
+	void set_error_handler(reference handler);
 
 The error-handler that is called should a runtime error that Lua can detect occurs. The error handler function needs to take a single string argument (use type std::string if you want to use a C++ function bound to lua as the error handler) and return a single string argument (again, return a std::string or string-alike argument from the C++ function if you're using one as the error handler). If :doc:`exceptions<../exceptions>` are enabled, sol will attempt to convert the ``.what()`` argument of the exception into a string and then call the error handling function. It is a :doc:`reference<reference>`, as it must refer to something that exists in the lua registry or on the Lua stack. This is automatically set to the default error handler when ``protected_function`` is constructed.
 

documentation/source/api/stack_reference.rst

@@ -26,4 +26,4 @@ Finally, there is a special abstraction that provides further stack optimization
 
 .. warning::
 
-	Do not use ``sol::stack_count`` with a ``sol::stack_aligned_protected_function``. The default behavior checks if the ``error_handler`` member variable is valid, and attempts to push the handler onto the stack in preparation for calling the function. This inevitably changes the stack. Only use ``sol::stack_aligned_protected_function`` with ``sol::stack_count`` if you know that the handler is not valid (it is ``nil`` or its ``error_handler.valid()`` function returns ``false``), or if you use ``sol::stack_aligned_stack_handler_protected_function``, which references an existing stack index that can be before the precise placement of the function and its arguments.
+	Do not use ``sol::stack_count`` with a ``sol::stack_aligned_protected_function``. The default behavior checks if the ``get_error_handler`` function returns a valid object, and attempts to push the handler onto the stack in preparation for calling the function. This inevitably changes the stack. Only use ``sol::stack_aligned_protected_function`` with ``sol::stack_count`` if you know that the handler is not valid (it is ``nil`` or the ``get_error_handler().valid()`` function call returns ``false``), or if you use ``sol::stack_aligned_stack_handler_protected_function``, which references an existing stack index that can be before the precise placement of the function and its arguments.

documentation/source/conf.py

@@ -13,8 +13,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
+import sys
+import subprocess
+import typing
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -29,7 +31,10 @@ import os
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo']
+extensions = [
+    'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'breathe',
+    'sphinx.ext.autosectionlabel'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -46,8 +51,8 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = 'sol'
-copyright = '2019, ThePhD'
+project = 'sol2'
+copyright = '2021, ThePhD'
 author = 'ThePhD'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -55,9 +60,9 @@ author = 'ThePhD'
 # built documents.
 #
 # The short X.Y version.
-version = '3.2'
+version = '4.0'
 # The full version, including alpha/beta/rc tags.
-release = '3.2.3'
+release = '4.0.0-alpha'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -74,7 +79,7 @@ language = None
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns: typing.List[str] = []
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -95,7 +100,7 @@ exclude_patterns = []
 pygments_style = 'sphinx'
 
 # The default highlighting language: default is python
-highlight_language = 'c++'
+highlight_language = 'cpp'
 
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
@@ -141,7 +146,7 @@ html_theme_path = [
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path: typing.List[str] = []
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -208,7 +213,7 @@ htmlhelp_basename = 'Soldoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
-latex_elements = {
+latex_elements: dict = {
     # The paper size ('letterpaper' or 'a4paper').
     #'papersize': 'letterpaper',
 
@@ -279,3 +284,69 @@ texinfo_documents = [
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+# -- Options for Breathe -------------------------------------------
+
+# C++ Index Configuration
+#
+cpp_index_common_prefix = ['sol::']
+
+# Breathe Configuration
+#
+breathe_projects = {}
+breathe_default_project = "sol2"
+
+# -- Options for autosectionlabel ---------------------------------
+
+# autosectionlabel Configuration
+#
+autosectionlabel_prefix_document = True
+
+# ReadTheDocs Build Help
+#
+
+
+def run_cmake_doxygen():
+	"""Run the cmake command to get the doxygen sources"""
+
+	# Make sure the directory exists
+	cmake_dir = os.path.join(os.getcwd(), '_build/cmake-build')
+	xml_dir = os.path.join(cmake_dir, 'documentation/doxygen/xml')
+	os.makedirs(cmake_dir, exist_ok=True)
+	os.makedirs(xml_dir, exist_ok=True)
+	print("[conf.py] CMake Directory: %s" % cmake_dir)
+	print("[conf.py] XML Directory: %s" % xml_dir)
+
+	try:
+		retcode = subprocess.call(
+		    "cmake -DZTD_TEXT_DOCUMENTATION:BOOL=TRUE -DZTD_TEXT_DOCUMENTATION_NO_SPHINX:BOOL=TRUE ../../../..",
+		    shell=True,
+		    cwd=cmake_dir)
+	except OSError as e:
+		sys.stderr.write("cmake generation execution failed: %s\n" % e)
+		return
+
+	try:
+		retcode = subprocess.call("cmake --build .",
+		                          shell=True,
+		                          cwd=cmake_dir)
+	except OSError as e:
+		sys.stderr.write("cmake generation execution failed: %s\n" % e)
+		return
+
+	breathe_projects["sol2"] = xml_dir
+
+
+def generate_doxygen_xml(app):
+	"""Run the doxygen make commands if we're on the ReadTheDocs server"""
+
+	read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
+
+	if read_the_docs_build:
+		run_cmake_doxygen()
+
+
+def setup(app):
+
+	# Add hook for building doxygen xml when needed
+	app.connect("builder-inited", generate_doxygen_xml)

documentation/source/features.rst

@@ -29,7 +29,7 @@ what sol supports
  	- Pull out any Lua function with :doc:`sol::function<api/function>`: ``sol::function fx = table["socket_send"];``
  	- Can also set callables into :doc:`operator[] proxies<api/proxy>`: ``table["move_dude"] = &engine::move_dude;``
  	- Safety: use :doc:`sol::protected_function<api/protected_function>` to catch any kind of error
- 		+ ANY kind: C++ exception or Lua erors are trapped and run through the optional ``error_handler`` variable
+ 		+ ANY kind: C++ exception or Lua errors are trapped and run through the optional error handler stored in the protected function
  	- *Advanced:* :doc:`overloading of a single function name<api/overload>` so you don't need to do boring typechecks
  	- *Advanced:* :doc:`efficient handling and well-documented<functions>` way of dealing with arguments