fix up CMake files once more, and hopefully prepare for a new test coverage paradigm

notably, test normal + single + generated + Lua 5.3.5 only once,
then only run the runtime_test and compile_test for normal for all other permutations to help increase text matrix throughput

cmake/Modules/FindToLuappBuild.cmake

@@ -57,7 +57,7 @@ ExternalProject_Add(TOLUAPP_BUILD_SOURCE
 	TEST_COMMAND ""
 	BUILD_BYPRODUCTS "${toluapp_sources}")
 
-set(toluapp_lib toluapp_lib_5.2.4)
+set(toluapp_lib toluapp_lib_${toluapp_version})
 add_library(${toluapp_lib} SHARED ${toluapp_sources})
 add_dependencies(${toluapp_lib} TOLUAPP_BUILD_SOURCE)
 set_target_properties(${toluapp_lib} PROPERTIES
@@ -70,7 +70,7 @@ if (MSVC)
 	target_compile_options(${toluapp_lib}
 		PRIVATE /W1)
 	target_compile_definitions(${toluapp_lib}
-		PRIVATE TOLUA_API=__declspec(dllexport))
+		PRIVATE "TOLUA_API=__declspec(dllexport)")
 else()
 	target_compile_options(${toluapp_lib}
 		PRIVATE -w

docs/CMakeLists.txt

@@ -27,17 +27,17 @@ cmake_minimum_required(VERSION 3.5.0)
 find_package(PythonInterp 3)
 
 if (NOT PYTHONINTERP_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")
+	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")
+if(NOT sol2_make_executable)
+    message(FATAL_ERROR "could not find a suitable make executable to build Sphinx documentation")
 endif()
 
-add_custom_command(OUTPUT make_docs
-		COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_CURRENT_SOURCE_DIR}/docs" ${CMAKE_CURRENT_BINARY_DIR}
-		COMMAND "${sol2_make_executable}" -C "${CMAKE_CURRENT_BINARY_DIR}" html)
-	add_custom_target(docs ALL DEPENDS make_docs)
-	install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/docs/html" DESTINATION "${CMAKE_INSTALL_DOCDIR}")
-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)
+install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/docs/html" DESTINATION "${CMAKE_INSTALL_DOCDIR}")

docs/source/api/as_args.rst

@@ -15,7 +15,7 @@ as_args
 ``sol::as_args`` is a function that that takes an iterable and turns it into multiple arguments to a function call. It forwards its arguments, and is meant to be used as shown below:
 
 
-.. literalinclude:: ../../../examples/args_from_container.cpp
+.. literalinclude:: ../../../examples/source/args_from_container.cpp
 	:caption: args_from_container.cpp
 	:linenos:
 

docs/source/api/as_function.rst

@@ -12,7 +12,7 @@ This function serves the purpose of ensuring that a callable struct (like a lamb
 
 This class can also make it so usertypes bind variable types as functions to for usertype bindings.
 
-.. literalinclude:: ../../../examples/docs/as_function.cpp
+.. literalinclude:: ../../../examples/source/docs/as_function.cpp
 	:linenos:
 
 
@@ -20,5 +20,5 @@ Note that if you actually want a userdata, but you want it to be callable, you s
 
 Here's an example of binding a variable as a function to a usertype:
 
-.. literalinclude:: ../../../examples/docs/as_function_usertype_member_variable.cpp
+.. literalinclude:: ../../../examples/source/docs/as_function_usertype_member_variable.cpp
 	:linenos:

docs/source/api/as_returns.rst

@@ -15,5 +15,5 @@ as_returns
 This allows you to wrap up a source that has ``begin`` and ``end`` iterator-returning functions on it and return it as multiple results into Lua. To have more control over the returns, use :doc:`sol::variadic_results<variadic_results>`.
 
 
-.. literalinclude:: ../../../examples/as_returns.cpp
+.. literalinclude:: ../../../examples/source/as_returns.cpp
 	:linenos:

docs/source/api/as_table.rst

@@ -13,7 +13,7 @@ as_table
 
 This function serves the purpose of ensuring that an object is pushed -- if possible -- like a table into Lua. The container passed here can be a pointer, a reference, a ``std::reference_wrapper`` around a container, or just a plain container value. It must have a begin/end function, and if it has a ``std::pair<Key, Value>`` as its ``value_type``, it will be pushed as a dictionary. Otherwise, it's pushed as a sequence.
 
-.. literalinclude:: ../../../examples/docs/as_table_ipairs.cpp
+.. literalinclude:: ../../../examples/source/docs/as_table_ipairs.cpp
 	:linenos:
 
 Note that any caveats with Lua tables apply the moment it is serialized, and the data cannot be gotten out back out in C++ as a C++ type. You can deserialize the Lua table into something explicitly using the ``sol::as_table_t`` marker for your get and conversion operations using Sol. At that point, the returned type is deserialized **from** a table, meaning you cannot reference any kind of C++ data directly as you do with regular userdata/usertypes. *All C++ type information is lost upon serialization into Lua.*

docs/source/api/c_call.rst

@@ -23,7 +23,7 @@ It is advisable for the user to consider making a macro to do the necessary ``de
 
 Here's an example below of various ways to use ``sol::c_call``:
 
-.. literalinclude:: ../../../examples/c_call.cpp
+.. literalinclude:: ../../../examples/source/c_call.cpp
 	:linenos:
 
 .. _one similar to this: http://stackoverflow.com/a/5628222/5280922

docs/source/api/environment.rst

@@ -18,7 +18,7 @@ This type is passed to :ref:`sol::state(_view)::script/do_x<state-script-functio
 
 There are many more uses, including storing state or special dependent variables in an environment that you pre-create using regular table opertions, and then changing at-will:
 
-.. literalinclude:: ../../../examples/docs/preparing_environments.cpp
+.. literalinclude:: ../../../examples/source/docs/preparing_environments.cpp
 	:linenos:
 
 Also note that ``sol::environment`` derives from ``sol::table``, which also derives from ``sol::reference``: in other words, copying one ``sol::environment`` value to another ``sol::environment`` value **does not** deep-copy the table, just creates a new reference pointing to the same lua object.

docs/source/api/function.rst

@@ -22,14 +22,14 @@ Function is a correct-assuming version of :doc:`protected_function<protected_fun
 
 Calls the constructor and creates this type, straight from the stack. For example:
 
-.. literalinclude:: ../../../examples/tie.cpp
+.. literalinclude:: ../../../examples/source/tie.cpp
 	:caption: funcs.lua
 	:lines: 9-13
 	:linenos:
 
 The following C++ code will call this function from this file and retrieve the return value:
 
-.. literalinclude:: ../../../examples/tie.cpp
+.. literalinclude:: ../../../examples/source/tie.cpp
 	:lines: 1-7,16-22
 	:linenos:
 
@@ -37,7 +37,7 @@ The call ``woof(20)`` generates a :ref:`unsafe_function_result<unsafe-function-r
 
 You can also return multiple values by using ``std::tuple``, or if you need to bind them to pre-existing variables use ``sol::tie``:
 
-.. literalinclude:: ../../../examples/tie.cpp
+.. literalinclude:: ../../../examples/source/tie.cpp
 	:lines: 24-
 	:linenos:
 

docs/source/api/metatable_key.rst

@@ -10,6 +10,6 @@ metatable_key
 
 You can use this in conjunction with :doc:`sol::table<table>` to set/get a metatable. Lua metatables are powerful ways to override default behavior of objects for various kinds of operators, among other things. Here is an entirely complete example, showing getting and working with a :doc:`usertype<usertype>`'s metatable defined by Sol:
 
-.. literalinclude:: ../../../examples/metatable_key_low_level.cpp
+.. literalinclude:: ../../../examples/source/metatable_key_low_level.cpp
 	:caption: messing with metatables
 	:linenos:

docs/source/api/overload.rst

@@ -32,19 +32,19 @@ Its use is simple: wherever you can pass a function type to Lua, whether its on
 
 The functions can be any kind of function / function object (lambda). Given these functions and struct:
 
-.. literalinclude:: ../../../examples/overloading_with_members.cpp
+.. literalinclude:: ../../../examples/source/overloading_with_members.cpp
 	:linenos:
 	:lines: 1-27
 
 You then use it just like you would for any other part of the api:
 
-.. literalinclude:: ../../../examples/overloading_with_members.cpp
+.. literalinclude:: ../../../examples/source/overloading_with_members.cpp
 	:linenos:
 	:lines: 29-45
 
 Doing the following in Lua will call the specific overloads chosen, and their associated functions:
 
-.. literalinclude:: ../../../examples/overloading_with_members.cpp
+.. literalinclude:: ../../../examples/source/overloading_with_members.cpp
 	:linenos:
 	:lines: 47-
 

docs/source/api/property.rst

@@ -13,6 +13,6 @@ property
 
 These set of functions create a type which allows a setter and getter pair (or a single getter, or a single setter) to be used to create a variable that is either read-write, read-only, or write-only. When used during :doc:`usertype<usertype>` construction, it will create a variable that uses the setter/getter member function specified.
 
-.. literalinclude:: ../../../examples/property.cpp
+.. literalinclude:: ../../../examples/source/property.cpp
 	:linenos:
 

docs/source/api/protect.rst

@@ -10,5 +10,5 @@ protect
 
 ``sol::protect( my_func )`` allows you to protect a function call or member variable call when it is being set to Lua. It can be used with usertypes or when just setting a function into Sol. Below is an example that demonstrates that a call that would normally not error without :doc:`Safety features turned on<../safety>` that instead errors and makes the Lua safety-call wrapper ``pcall`` fail:
 
-.. literalinclude:: ../../../examples/protect.cpp
+.. literalinclude:: ../../../examples/source/protect.cpp
 	:linenos:	

docs/source/api/protected_function.rst

@@ -11,13 +11,13 @@ Inspired by a request from `starwing`_ in the :doc:`old sol repository<../origin
 
 When called without the return types being specified by either a ``sol::types<...>`` list or a ``call<Ret...>( ... )`` template type list, it generates a :doc:`protected_function_result<proxy>` class that gets implicitly converted to the requested return type. For example:
 
-.. literalinclude:: ../../../examples/error_handler.cpp
+.. literalinclude:: ../../../examples/source/error_handler.cpp
 	:linenos:
 	:lines: 10-28
 
 The following C++ code will call this function from this file and retrieve the return value, unless an error occurs, in which case you can bind an error handling function like so:
 
-.. literalinclude:: ../../../examples/error_handler.cpp
+.. literalinclude:: ../../../examples/source/error_handler.cpp
 	:linenos:
 	:lines: 1-6,30-66
 
@@ -26,7 +26,7 @@ This code is much more long-winded than its :doc:`function<function>` counterpar
 
 Alternatively, with a bad or good function call, you can use ``sol::optional`` to check if the call succeeded or failed:
 
-.. literalinclude:: ../../../examples/error_handler.cpp
+.. literalinclude:: ../../../examples/source/error_handler.cpp
 	:linenos:
 	:lines: 67-
 

docs/source/api/proxy.rst

@@ -27,19 +27,19 @@ proxy
 
 ``proxy`` is returned by lookups into :doc:`sol::table<table>` and table-like entities. Because it is templated on key and table type, it would be hard to spell: you can capture it using the word ``auto`` if you feel like you need to carry it around for some reason before using it. ``proxy`` evaluates its arguments lazily, when you finally call ``get`` or ``set`` on it. Here are some examples given the following lua script:
 
-.. literalinclude:: ../../../examples/table_proxy.cpp
+.. literalinclude:: ../../../examples/source/table_proxy.cpp
 	:linenos:
 	:lines: 11-15
 
 After loading that file in or putting it in a string and reading the string directly in lua (see :doc:`state`), you can start kicking around with it in C++ like so:
 
-.. literalinclude:: ../../../examples/table_proxy.cpp
+.. literalinclude:: ../../../examples/source/table_proxy.cpp
 	:linenos:
 	:lines: 1-8,18-40
 
 We don't recommend using ``proxy`` lazy evaluation the above to be used across classes or between function: it's more of something you can do to save a reference to a value you like, call a script or run a lua function, and then get it afterwards. You can also set functions (and function objects) this way, and retrieve them as well:
 
-.. literalinclude:: ../../../examples/table_proxy.cpp
+.. literalinclude:: ../../../examples/source/table_proxy.cpp
 	:linenos:
 	:lines: 41-
 

docs/source/api/readonly.rst

@@ -14,7 +14,7 @@ The goal of read-only is to protect a variable set on a usertype or a function.
 If you are looking to make a read-only table, you need to go through a bit of a complicated song and dance by overriding the ``__index`` metamethod. Here's a complete example on the way to do that using ``sol``:
 
 
-.. literalinclude:: ../../../examples/read_only.cpp
+.. literalinclude:: ../../../examples/source/read_only.cpp
 	:caption: read_only.cpp
 	:linenos:
 

docs/source/api/stack_reference.rst

@@ -17,7 +17,7 @@ This type is particular to working with the stack. It does not push the function
 
 Furthermore, if you know you have a function in the right place alongside proper arguments on top of it, you can use the ``sol::stack_count`` structure and give its constructor the number of arguments off the top that you want to call your pre-prepared function with:
 
-.. literalinclude:: ../../../examples/stack_aligned_function.cpp
+.. literalinclude:: ../../../examples/source/stack_aligned_function.cpp
 	:caption: stack_aligned_function.cpp
 	:linenos:
 	:name: stack-aligned-function-example

docs/source/api/state.rst

@@ -100,7 +100,7 @@ If your script returns a value, you can capture it from the returned :ref:`sol::
 
 To handle errors when using the second overload, provide a callable function/object that takes a ``lua_State*`` as its first argument and a ``sol::protected_function_result`` as its second argument. ``sol::script_default_on_error`` and ``sol::script_pass_on_error`` are 2 functions provided by sol that will either generate a traceback error to return / throw (if throwing is allowed); or, pass the error on through and return it to the user (respectively). An example of having your:
 
-.. literalinclude:: ../../../examples/docs/state_script_safe.cpp
+.. literalinclude:: ../../../examples/source/docs/state_script_safe.cpp
 	:linenos:
 	:name: state-script-safe
 

docs/source/api/this_state.rst

@@ -9,5 +9,5 @@ this_state
 
 This class is a transparent type that is meant to be gotten in functions to get the current lua state a bound function or usertype method is being called from. It does not actually retrieve anything from lua nor does it increment the argument count, making it "invisible" to function calls in lua and calls through ``std::function<...>`` and :doc:`sol::function<function>` on this type. It can be put in any position in the argument list of a function:
 
-.. literalinclude:: ../../../examples/this_state.cpp
+.. literalinclude:: ../../../examples/source/this_state.cpp
 	:linenos:

docs/source/api/tie.rst

@@ -5,7 +5,7 @@ tie
 
 `std::tie()`_ does not work well with :doc:`sol::function<function>`'s ``sol::function_result`` returns. Use ``sol::tie`` instead. Because they're both named `tie`, you'll need to be explicit when you use Sol's by naming it with the namespace (``sol::tie``), even with a ``using namespace sol;``. Here's an example:
 
-.. literalinclude:: ../../../examples/tie.cpp
+.. literalinclude:: ../../../examples/source/tie.cpp
 	:linenos:
 
 .. _std::tie(): http://en.cppreference.com/w/cpp/utility/tuple/tie

docs/source/api/usertype.rst

@@ -199,7 +199,7 @@ runtime functions
 
 You can add functions at runtime **to the whole class** (not to individual objects). Set a name under the metatable name you bound using ``new_usertype`` to an object. For example:
 
-.. literalinclude:: ../../../examples/docs/runtime_extension.cpp
+.. literalinclude:: ../../../examples/source/docs/runtime_extension.cpp
 	:caption: runtime_extension.cpp
 	:name: runtime-extension-example
 	:linenos:
@@ -232,7 +232,7 @@ Register the base classes explicitly.
 
 	Always specify your bases if you plan to retrieve a base class using the Sol abstraction directly and not casting yourself.
 
-.. literalinclude:: ../../../examples/docs/inheritance.cpp
+.. literalinclude:: ../../../examples/source/docs/inheritance.cpp
 	:caption: inheritance.cpp
 	:name: inheritance-example
 	:linenos:

docs/source/api/var.rst

@@ -5,5 +5,5 @@ var
 
 The sole purpose of this tagging type is to work with :doc:`usertypes<usertype>` to provide ``my_class.my_static_var`` access, and to also provide reference-based access as well.
 
-.. literalinclude:: ../../../examples/usertype_var.cpp
+.. literalinclude:: ../../../examples/source/usertype_var.cpp
 	:linenos:

docs/source/api/variadic_args.rst

@@ -11,15 +11,15 @@ This class is meant to represent every single argument at its current index and
 
 ``variadic_args`` also has ``begin()`` and ``end()`` functions that return (almost) random-acess iterators. These return a proxy type that can be implicitly converted to a type you want, much like the :doc:`table proxy type<proxy>`.
 
-.. literalinclude:: ../../../examples/variadic_args.cpp
+.. literalinclude:: ../../../examples/source/variadic_args.cpp
 	:linenos:
 
 You can also "save" arguments and the like later, by stuffing them into a ``std::vector<sol::object>`` or something similar that serializes them into the registry. Below is an example of saving all of the arguments provided by ``sol::variadic_args`` in a lambda capture variable called ``args``.
 
-.. literalinclude:: ../../../examples/variadic_args_storage.cpp
+.. literalinclude:: ../../../examples/source/variadic_args_storage.cpp
 	:linenos:
 
 Finally, note that you can use ``sol::variadic_args`` constructor to "offset"/"shift over" the arguments being viewed:
 
-.. literalinclude:: ../../../examples/variadic_args_shifted.cpp
+.. literalinclude:: ../../../examples/source/variadic_args_shifted.cpp
 	:linenos:

docs/source/containers.rst

@@ -217,7 +217,7 @@ a complete example
 
 Here's a complete working example of it working for Lua 5.3 and Lua 5.2, and how you can retrieve out the container in all versions:
 
-.. literalinclude:: ../../examples/containers.cpp
+.. literalinclude:: ../../examples/source/containers.cpp
 	:name: containers-example
 	:linenos:
 
@@ -236,7 +236,7 @@ There are also other ways to iterate over key/values, but they can be difficult
 
 If you can't upgrade, use the "member" function ``my_container:pairs()`` in Lua to perform iteration:
 
-.. literalinclude:: ../../examples/container_with_pairs.cpp
+.. literalinclude:: ../../examples/source/container_with_pairs.cpp
 	:name: containers-pairs-example
 	:linenos:
 

docs/source/exceptions.rst

@@ -9,7 +9,7 @@ If you turn this off, the default `at_panic`_ function :doc:`state<api/state>` s
 
 To make this not be the case, you can set a panic function directly with ``lua_atpanic( lua, my_panic_function );`` or when you create the ``sol::state`` with ``sol::state lua(my_panic_function);``. Here's an example ``my_panic_function`` you can have that prints out its errors:
 
-.. literalinclude:: ../../examples/docs/my_panic.cpp
+.. literalinclude:: ../../examples/source/docs/my_panic.cpp
 	:caption: typical panic function
 	:name: typical-panic-function
 	:linenos:
@@ -26,7 +26,7 @@ various sol and lua handlers
 
 Lua comes with two kind of built-in handlers that sol provides easy opt-ins for. One is the ``panic`` function, as :ref:`demonstrated above<typical-panic-function>`. Another is the ``pcall`` error handler, used with :doc:`sol::protected_function<api/protected_function>`. It is any function that takes a single argument. The single argument is the error type being passed around: in Lua, this is a single string message:
 
-.. literalinclude:: ../../examples/protected_functions.cpp
+.. literalinclude:: ../../examples/source/protected_functions.cpp
 	:caption: regular error handling
 	:name: regular-error-handling
 	:linenos:
@@ -34,7 +34,7 @@ Lua comes with two kind of built-in handlers that sol provides easy opt-ins for.
 
 The other handler is specific to sol2. If you open a ``sol::state``, or open the default state handlers for your ``lua_State*`` (see :ref:`sol::state's automatic handlers<state-automatic-handlers>` for more details), there is a ``sol::exception_handler_function`` type. It allows you to register a function in the event that an exception happens that bubbles out of your functions. The function requires that you push 1 item onto the stack that will be used with a call to `lua_error`_
 
-.. literalinclude:: ../../examples/exception_handler.cpp
+.. literalinclude:: ../../examples/source/exception_handler.cpp
 	:caption: exception handling
 	:name: exception-handling
 	:linenos:

docs/source/functions.rst

@@ -42,7 +42,7 @@ To be explicit about wanting a struct to be interpreted as a function, use ``my_
 
 Furthermore, it is important to know that lambdas without a specified return type (and a non-const, non-reference-qualified ``auto``) will decay return values. To capture or return references explicitly, use ``decltype(auto)`` or specify the return type **exactly** as desired:
 
-.. literalinclude:: ../../examples/docs/references_in_lambdas.cpp
+.. literalinclude:: ../../examples/source/docs/references_in_lambdas.cpp
 	:name: refereces-in-lambdas-example
 	:linenos:
 	

docs/source/index.rst

@@ -57,11 +57,11 @@ the basics:
 	The code below *and* more examples can be found in the `examples directory`_
 
 
-.. literalinclude:: ../../examples/docs/simple_functions.cpp
+.. literalinclude:: ../../examples/source/docs/simple_functions.cpp
 	:name: simple-functions-example
 	:linenos:
 
-.. literalinclude:: ../../examples/docs/simple_structs.cpp
+.. literalinclude:: ../../examples/source/docs/simple_structs.cpp
 	:name: simple-structs-example
 	:linenos:	
 

docs/source/threading.rst

@@ -34,6 +34,6 @@ You can mitigate some of the pressure of using coroutines and threading by using
 
 Here's an example of explicit state transferring below:
 
-.. literalinclude:: ../../examples/docs/state_transfer.cpp
+.. literalinclude:: ../../examples/source/docs/state_transfer.cpp
 	:name: state-transfer
 	:linenos:

docs/source/tutorial/all-the-things.rst

@@ -18,7 +18,7 @@ You'll need to ``#include <sol/sol.hpp>``/``#include "sol.hpp"`` somewhere in yo
 
 The implementation for ``assert.hpp`` with ``c_assert`` looks like so:
 
-.. literalinclude:: ../../../examples/assert.hpp
+.. literalinclude:: ../../../examples/source/assert.hpp
 	:linenos:
 	:lines: 1-3, 19-
 
@@ -27,7 +27,7 @@ This is the assert used in the quick code below.
 opening a state
 ---------------
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/opening_a_state.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/opening_a_state.cpp
 	:linenos:
 
 
@@ -39,7 +39,7 @@ using sol2 on a lua_State\*
 For your system/game that already has Lua or uses an in-house or pre-rolled Lua system (LuaBridge, kaguya, Luwra, etc.), but you'd still like sol2 and nice things:
 
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/opening_state_on_raw_lua.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/opening_state_on_raw_lua.cpp
 	:linenos:
 
 .. _running-lua-code:
@@ -47,13 +47,13 @@ For your system/game that already has Lua or uses an in-house or pre-rolled Lua
 running lua code
 ----------------
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/running_lua_code.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/running_lua_code.cpp
 	:linenos:
 	:lines: 1-10, 16-26
 
 To run Lua code but have an error handler in case things go wrong:
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/running_lua_code.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/running_lua_code.cpp
 	:linenos:
 	:lines: 28-39,47-
 
@@ -68,7 +68,7 @@ You can use the individual load and function call operator to load, check, and t
 	This is ONLY if you need some sort of fine-grained control: for 99% of cases, :ref:`running lua code<running-lua-code>` is preferred and avoids pitfalls in not understanding the difference between script/load and needing to run a chunk after loading it.
 
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/running_lua_code_low_level.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/running_lua_code_low_level.cpp
 	:linenos:
 	:lines: 1-10, 16-40, 47-49
 
@@ -80,37 +80,37 @@ set and get variables
 
 You can set/get everything using table-like syntax.
 	
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/set_and_get_variables.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp
 	:linenos:
 	:lines: 1-19
 
 Equivalent to loading lua values like so:
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/set_and_get_variables.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp
 	:linenos:
 	:lines: 22-34
 
 You can show they are equivalent:
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/set_and_get_variables.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp
 	:linenos:
 	:lines: 36-44
 
 Retrieve these variables using this syntax:
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/set_and_get_variables.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp
 	:linenos:
 	:lines: 45-64
 
 Retrieve Lua types using ``object`` and other ``sol::`` types.
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/set_and_get_variables.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp
 	:linenos:
 	:lines: 66-
 
 You can erase things by setting it to ``nullptr`` or ``sol::lua_nil``.
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/set_and_get_variables_exists.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/set_and_get_variables_exists.cpp
 	:linenos:
 
 Note that if its a :doc:`userdata/usertype<../api/usertype>` for a C++ type, the destructor will run only when the garbage collector deems it appropriate to destroy the memory. If you are relying on the destructor being run when its set to ``sol::lua_nil``, you're probably committing a mistake.
@@ -120,13 +120,13 @@ tables
 
 Tables can be manipulated using accessor-syntax. Note that :doc:`sol::state<../api/state>` is a table and all the methods shown here work with ``sol::state``, too.
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/tables_and_nesting.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/tables_and_nesting.cpp
 	:linenos:
 	:lines: 1-34
 
 If you're going deep, be safe: 
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/tables_and_nesting.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/tables_and_nesting.cpp
 	:linenos:
 	:lines: 35-
 
@@ -135,13 +135,13 @@ make tables
 
 There are many ways to make a table. Here's an easy way for simple ones:
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/make_tables.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/make_tables.cpp
 	:linenos:
 	:lines: 1-21
 
 Equivalent Lua code, and check that they're equivalent:
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/make_tables.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/make_tables.cpp
 	:linenos:
 	:lines: 22-
 
@@ -155,7 +155,7 @@ functions
 
 They're easy to use, from Lua and from C++:
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/functions_easy.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/functions_easy.cpp
 	:linenos:
 	:lines: 1-
 
@@ -163,13 +163,13 @@ If you need to protect against errors and parser problems and you're not ready t
 
 You can bind member variables as functions too, as well as all KINDS of function-like things:
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/functions_all.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/functions_all.cpp
 	:linenos:
 	:lines: 1-50
 
 The lua code to call these things is:
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/functions_all.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/functions_all.cpp
 	:linenos:
 	:lines: 51-
 
@@ -181,7 +181,7 @@ self call
 
 You can pass the ``self`` argument through C++ to emulate 'member function' calls in Lua.
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/self_call.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/self_call.cpp
 	:linenos:
 	:lines: 1-
 
@@ -189,7 +189,7 @@ You can pass the ``self`` argument through C++ to emulate 'member function' call
 multiple returns from lua
 -------------------------
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/multiple_returns_from_lua.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/multiple_returns_from_lua.cpp
 	:linenos:
 	:lines: 1-
 
@@ -197,7 +197,7 @@ multiple returns from lua
 multiple returns to lua
 -----------------------
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/multiple_returns_to_lua.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/multiple_returns_to_lua.cpp
 	:linenos:
 	:lines: 1-
 
@@ -217,7 +217,7 @@ Everything that is not a:
 Is set as a :doc:`userdata + usertype<../api/usertype>`.
 
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/userdata.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/userdata.cpp
 	:linenos:
 	:lines: 1-57,97-
 
@@ -225,13 +225,13 @@ Is set as a :doc:`userdata + usertype<../api/usertype>`.
 
 If you want it to refer to something, whose memory you know won't die in C++ while it is used/exists in Lua, do the following:
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/userdata_memory_reference.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/userdata_memory_reference.cpp
 	:linenos:
 	:lines: 1-45
 
 You can retrieve the userdata in the same way as everything else. Importantly, note that you can change the data of usertype variables and it will affect things in lua if you get a pointer or a reference:
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/userdata_memory_reference.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/userdata_memory_reference.cpp
 	:linenos:
 	:lines: 46-
 
@@ -249,7 +249,7 @@ namespacing
 
 You can emulate namespacing by having a table and giving it the namespace names you want before registering enums or usertypes:
 
-.. literalinclude:: ../../../examples/tutorials/quick_n_dirty/namespacing.cpp
+.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/namespacing.cpp
 	:linenos:
 	:lines: 1-
 

docs/source/tutorial/customization.rst

@@ -5,17 +5,17 @@ Sometimes, overriding Sol to make it handle certain ``struct``'s and ``class``'e
 
 These are template class/structs, so you'll override them using a technique C++ calls *class/struct specialization*. Below is an example of a struct that gets broken apart into 2 pieces when going in the C++ --> Lua direction, and then pulled back into a struct when going in the Lua --> C++:
 
-.. literalinclude:: ../../../examples/customization.cpp
+.. literalinclude:: ../../../examples/source/customization_multiple.cpp
 	:name: customization-overriding
 	:linenos:
-	:lines: 1-72
+	:lines: 1-52
 
 This is the base formula that you can follow to extend to your own classes. Using it in the rest of the library should then be seamless:
 
-.. literalinclude:: ../../../examples/customization.cpp
+.. literalinclude:: ../../../examples/source/customization_multiple.cpp
 	:name: customization-overriding-use
 	:linenos:
-	:lines: 73-
+	:lines: 52-
 
 And that's it!
 

docs/source/tutorial/variables.rst

@@ -8,28 +8,28 @@ reading
 
 Given this lua file that gets loaded into sol:
 
-.. literalinclude:: ../../../examples/tutorials/variables_demo.cpp
+.. literalinclude:: ../../../examples/source/tutorials/variables_demo.cpp
 	:linenos:
 	:lines: 15-18
 
 You can interact with the Lua Virtual Machine like so:
 
 
-.. literalinclude:: ../../../examples/tutorials/variables_demo.cpp
+.. literalinclude:: ../../../examples/source/tutorials/variables_demo.cpp
 	:linenos:
 	:lines: 1-10, 12-12, 20-24, 70-
 
 From this example, you can see that there's many ways to pull out the varaibles you want. For example, to determine if a nested variable exists or not, you can use ``auto`` to capture the value of a ``table[key]`` lookup, and then use the ``.valid()`` method:
 
 
-.. literalinclude:: ../../../examples/tutorials/variables_demo.cpp
+.. literalinclude:: ../../../examples/source/tutorials/variables_demo.cpp
 	:linenos:
 	:lines: 1-10, 12-12, 34-43, 70-
 
 
 This comes in handy when you want to check if a nested variable exists. You can also check if a toplevel variable is present or not by using ``sol::optional``, which also checks if A) the keys you're going into exist and B) the type you're trying to get is of a specific type:
 
-.. literalinclude:: ../../../examples/tutorials/variables_demo.cpp
+.. literalinclude:: ../../../examples/source/tutorials/variables_demo.cpp
 	:linenos:
 	:caption: optional lookup
 	:lines: 1-10, 12-12, 43-58, 70-
@@ -37,7 +37,7 @@ This comes in handy when you want to check if a nested variable exists. You can
 
 This can come in handy when, even in optimized or release modes, you still want the safety of checking.  You can also use the `get_or` methods to, if a certain value may be present but you just want to default the value to something else:
 
-.. literalinclude:: ../../../examples/tutorials/variables_demo.cpp
+.. literalinclude:: ../../../examples/source/tutorials/variables_demo.cpp
 	:linenos:
 	:caption: optional lookup
 	:lines: 1-10, 12-12, 60-
@@ -51,19 +51,19 @@ writing
 
 Writing gets a lot simpler. Even without scripting a file or a string, you can read and write variables into lua as you please:
 
-.. literalinclude:: ../../../examples/tutorials/write_variables_demo.cpp
+.. literalinclude:: ../../../examples/source/tutorials/write_variables_demo.cpp
 	:linenos:
 	:name: writing-variables-demo
 
 This example pretty much sums up what can be done. Note that the syntax ``lua["non_existing_key_1"] = 1`` will make that variable, but if you tunnel too deep without first creating a table, the Lua API will panic (e.g., ``lua["does_not_exist"]["b"] = 20`` will trigger a panic). You can also be lazy with reading / writing values:
 
-.. literalinclude:: ../../../examples/tutorials/lazy_demo.cpp
+.. literalinclude:: ../../../examples/source/tutorials/lazy_demo.cpp
 	:linenos:
 
 
 Finally, it's possible to erase a reference/variable by setting it to ``nil``, using the constant ``sol::nil`` in C++:
 
-.. literalinclude:: ../../../examples/tutorials/erase_demo.cpp
+.. literalinclude:: ../../../examples/source/tutorials/erase_demo.cpp
 	:linenos:
 
 

examples/CMakeLists.txt

@@ -36,12 +36,24 @@ if (SOL2_INTEROP_EXAMPLES OR SOL2_INTEROP_EXAMPLES_SINGLE OR SOL2_INTEROP_EXAMPL
 	add_subdirectory(interop/luwra)
 endif()
 
+# # Utility assert.hpp "library" 
+add_library(sol2_assert INTERFACE)
+add_library(sol2::assert ALIAS sol2_assert)
+set_target_properties(sol2_assert
+	PROPERTIES
+	INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_SOURCE_DIR}/include"
+	EXPORT_NAME sol2::assert)
+if (SOL2_CI)
+	target_compile_definitions(sol2_assert 
+		PUBLIC SOL2_CI)
+endif()
+
 # # single-source compilable examples
 
 file(GLOB EXAMPLES_SRC source/*.cpp source/tutorials/quick_n_dirty/*.cpp source/docs/*.cpp)
 source_group(examples FILES ${EXAMPLES_SRC})
 
-function (MAKE_EXAMPLE example_source_file example_suffix target_sol example_test_var)
+function (MAKE_EXAMPLE example_source_file example_suffix target_sol)
 	
 	get_filename_component(example_name ${example_source_file} NAME_WE)
 	file(RELATIVE_PATH example_source_file_relative ${CMAKE_SOURCE_DIR} ${example_source_file})
@@ -56,7 +68,7 @@ function (MAKE_EXAMPLE example_source_file example_suffix target_sol example_tes
 		set(example_output_name "${example_output_relative_dir_name}.${example_name}")
 	endif()
 
-	add_executable(${example_name} ${example_source_file} source/assert.hpp)
+	add_executable(${example_name} ${example_source_file})
 	set_target_properties(${example_name} 
 		PROPERTIES
 		OUTPUT_NAME "${example_output_name}"
@@ -69,31 +81,22 @@ function (MAKE_EXAMPLE example_source_file example_suffix target_sol example_tes
 			"$<$<CONFIG:RelWithDebInfo>:/MD>"
 			"$<$<CONFIG:MinSizeRel>:/MD>")
 		target_compile_definitions(${example_name}
-			PRIVATE /DUNICODE /D_UNICODE 
-			/D_CRT_SECURE_NO_WARNINGS /D_CRT_SECURE_NO_DEPRECATE)
+			PRIVATE UNICODE _UNICODE 
+			_CRT_SECURE_NO_WARNINGS _CRT_SECURE_NO_DEPRECATE )
 	else()
 		target_compile_options(${example_name}
-			PRIVATE -std=c++1z -Wno-unknown-warning -Wno-unknown-warning-option 
+			PRIVATE -std=c++1z -Wno-noexcept-type -Wno-unknown-warning -Wno-unknown-warning-option 
 			-Wall -Wextra -Wpedantic -pedantic -pedantic-errors)
 	endif()
 	
-	target_link_libraries(${example_name} ${target_sol})
-	target_link_libraries(${example_name} ${LUA_LIBRARIES})
+	target_link_libraries(${example_name} 
+		PRIVATE ${target_sol} ${LUA_LIBRARIES} sol2::assert)
+	
 	if(CMAKE_DL_LIBS)
 		target_link_libraries(${example_name} ${CMAKE_DL_LIBS})
 	endif()
-	if (SOL2_CI)
-		target_compile_definitions(${example_name} 
-			PRIVATE SOL2_CI)
-	endif()
 	
-	if (MSVC)
-	else()
-		target_compile_options(${example_name}
-			PRIVATE -Wno-noexcept-type)
-	endif()
-	
-	if (${example_test_var})
+	if (SOL2_TESTS_EXAMPLES)
 		add_test(NAME ${example_output_name} COMMAND ${example_name})
 	endif()
 	install(TARGETS ${example_name} RUNTIME DESTINATION bin)
@@ -101,18 +104,18 @@ endfunction(MAKE_EXAMPLE)
 
 if (SOL2_EXAMPLES)
 	foreach(example_source_file ${EXAMPLES_SRC})
-		MAKE_EXAMPLE(${example_source_file} "" sol2::sol2 SOL2_TESTS_EXAMPLES)
+		MAKE_EXAMPLE(${example_source_file} "" sol2::sol2)
 	endforeach()
 endif()
 
 if (SOL2_EXAMPLES_SINGLE)
 	foreach(example_source_file ${EXAMPLES_SRC})
-		MAKE_EXAMPLE(${example_source_file} ".single" sol2::sol2_single SOL2_TESTS_EXAMPLES)
+		MAKE_EXAMPLE(${example_source_file} ".single" sol2::sol2_single)
 	endforeach()
 endif()
 
 if (SOL2_EXAMPLES_SINGLE_GENERATED)
 	foreach(example_source_file ${EXAMPLES_SRC})
-		MAKE_EXAMPLE(${example_source_file} ".single.generated" sol2::sol2_single_generated SOL2_TESTS_EXAMPLES)
+		MAKE_EXAMPLE(${example_source_file} ".single.generated" sol2::sol2_single_generated)
 	endforeach()
 endif()

examples/interop/LuaBridge/CMakeLists.txt

@@ -29,7 +29,9 @@ function (make_luabridge_interop_example target_library example_suffix)
 	set(example_name "${example_name}${example_suffix}")
 	
 	add_executable(${example_name} source/LuaBridge.cpp)
-	target_link_libraries(${example_name} PUBLIC ${LUA_LIBRARIES} PRIVATE ${LUABRIDGE_LIBRARIES} ${target_library})
+	target_link_libraries(${example_name} 
+		PRIVATE ${LUA_LIBRARIES} ${LUABRIDGE_LIBRARIES} 
+		${target_library} sol2::assert)
 
 	if (MSVC)
 		target_compile_options(${example_name}
@@ -38,24 +40,20 @@ function (make_luabridge_interop_example target_library example_suffix)
 			"$<$<CONFIG:RelWithDebInfo>:/MD>"
 			"$<$<CONFIG:MinSizeRel>:/MD>")
 		target_compile_definitions(${example_name}
-			PRIVATE /DUNICODE /D_UNICODE 
-			/D_CRT_SECURE_NO_WARNINGS /D_CRT_SECURE_NO_DEPRECATE)
+			PRIVATE /W1
+			UNICODE _UNICODE 
+			_CRT_SECURE_NO_WARNINGS _CRT_SECURE_NO_DEPRECATE)
 	else()
 		target_compile_options(${example_name}
-			PRIVATE -std=c++1z
+			PRIVATE -std=c++1z -w
 			-Wno-noexcept-type -Wno-unknown-warning -Wno-unknown-warning-option 
 			-Wall -Wextra -Wpedantic -pedantic -pedantic-errors)
 	endif()
 
-
 	if (CMAKE_DL_LIBS)
 		target_link_libraries(${example_name} PRIVATE ${CMAKE_DL_LIBS})
 	endif()
-	if (MSVC)
-		target_compile_options(${example_name} PRIVATE /W1)
-	else()
-		target_compile_options(${example_name} PRIVATE -w)
-	endif()
+
 	if (SOL2_TESTS_INTEROP_EXAMPLES)
 		add_test(NAME ${example_name} COMMAND ${example_name})
 	endif()

examples/interop/LuaBridge/source/LuaBridge.cpp

@@ -5,7 +5,7 @@
 #include <LuaBridge/LuaBridge.h>
 
 #include <iostream>
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 // LuaBridge,
 // no longer maintained, by VinnieFalco:

examples/interop/kaguya/CMakeLists.txt

@@ -28,32 +28,31 @@ function (make_kaguya_interop_example target_library example_suffix)
 	set(example_name kaguya_interop_example)
 	set(example_name "${example_name}${example_suffix}")
 	
+	add_executable(${example_name} source/kaguya.cpp)
+	target_link_libraries(${example_name} 
+		PRIVATE ${LUA_LIBRARIES} ${KAGUYA_LIBRARIES} 
+		${target_library} sol2::assert)
+	
 	if (MSVC)
 		target_compile_options(${example_name}
-			PRIVATE /std:c++latest /EHsc "$<$<CONFIG:Debug>:/MDd>"
+			PRIVATE /W1 /std:c++latest /EHsc "$<$<CONFIG:Debug>:/MDd>"
 			"$<$<CONFIG:Release>:/MD>"
 			"$<$<CONFIG:RelWithDebInfo>:/MD>"
 			"$<$<CONFIG:MinSizeRel>:/MD>")
 		target_compile_definitions(${example_name}
-			PRIVATE /DUNICODE /D_UNICODE 
-			/D_CRT_SECURE_NO_WARNINGS /D_CRT_SECURE_NO_DEPRECATE)
+			PRIVATE UNICODE _UNICODE 
+			_CRT_SECURE_NO_WARNINGS _CRT_SECURE_NO_DEPRECATE)
 	else()
 		target_compile_options(${example_name}
-			PRIVATE -std=c++1z
+			PRIVATE -std=c++1z -w 
 			-Wno-noexcept-type -Wno-unknown-warning -Wno-unknown-warning-option 
 			-Wall -Wextra -Wpedantic -pedantic -pedantic-errors)
 	endif()
-	
-	add_executable(${example_name} source/kaguya.cpp)
-	target_link_libraries(${example_name} PUBLIC ${LUA_LIBRARIES} PRIVATE ${KAGUYA_LIBRARIES} ${target_library})
+
 	if (CMAKE_DL_LIBS)
 		target_link_libraries(${example_name} PRIVATE ${CMAKE_DL_LIBS})
 	endif()
-	if (MSVC)
-		target_compile_options(${example_name} PRIVATE /W1)
-	else()
-		target_compile_options(${example_name} PRIVATE -w)
-	endif()
+	
 	if (SOL2_TESTS_INTEROP_EXAMPLES)
 		add_test(NAME ${example_name} COMMAND ${example_name})
 	endif()

examples/interop/kaguya/source/kaguya.cpp

@@ -5,7 +5,7 @@
 #include <sol/sol.hpp>
 
 #include <iostream>
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 // kaguya code lifted from README.md,
 // written by satoren:

examples/interop/luwra/CMakeLists.txt

@@ -29,7 +29,9 @@ function (make_luwra_interop_example target_library example_suffix)
 	set(example_name "${example_name}${example_suffix}")
 	
 	add_executable(${example_name} source/luwra.cpp)
-	target_link_libraries(${example_name} PUBLIC ${LUA_LIBRARIES} PRIVATE ${LUWRA_LIBRARIES} ${target_library})
+	target_link_libraries(${example_name} 
+		PRIVATE ${LUA_LIBRARIES} ${LUWRA_LIBRARIES} 
+		${target_library} sol2::assert)
 
 	if (MSVC)
 		target_compile_options(${example_name}
@@ -38,24 +40,19 @@ function (make_luwra_interop_example target_library example_suffix)
 			"$<$<CONFIG:RelWithDebInfo>:/MD>"
 			"$<$<CONFIG:MinSizeRel>:/MD>")
 		target_compile_definitions(${example_name}
-			PRIVATE /DUNICODE /D_UNICODE 
-			/D_CRT_SECURE_NO_WARNINGS /D_CRT_SECURE_NO_DEPRECATE)
+			PRIVATE /W1 UNICODE _UNICODE 
+			_CRT_SECURE_NO_WARNINGS _CRT_SECURE_NO_DEPRECATE)
 	else()
 		target_compile_options(${example_name}
-			PRIVATE -std=c++1z
+			PRIVATE -std=c++1z -w
 			-Wno-noexcept-type -Wno-unknown-warning -Wno-unknown-warning-option 
 			-Wall -Wextra -Wpedantic -pedantic -pedantic-errors)
 	endif()
 
-
 	if (CMAKE_DL_LIBS)
 		target_link_libraries(${example_name} PRIVATE ${CMAKE_DL_LIBS})
 	endif()
-	if (MSVC)
-		target_compile_options(${example_name} PRIVATE /W1)
-	else()
-		target_compile_options(${example_name} PRIVATE -w)
-	endif()
+
 	if (SOL2_TESTS_INTEROP_EXAMPLES)
 		add_test(NAME ${example_name} COMMAND ${example_name})
 	endif()

examples/interop/luwra/source/luwra.cpp

@@ -5,7 +5,7 @@
 #include <luwra.hpp>
 
 #include <iostream>
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 // luwra,
 // another C++ wrapper library:

examples/interop/tolua/CMakeLists.txt

@@ -27,8 +27,11 @@ find_package(ToLuappBuild REQUIRED)
 function(make_tolua_interop_example target_library example_suffix)
 	set(example_name tolua_interop_example)
 	set(example_name "${example_name}${example_suffix}")
+
 	add_executable(${example_name} source/tolua.cpp)
-	target_link_libraries(${example_name} PUBLIC ${LUA_LIBRARIES} PRIVATE ${TOLUAPP_LIBRARIES} ${target_library})
+	target_link_libraries(${example_name} 
+		PRIVATE sol2::assert
+		${LUA_LIBRARIES} ${TOLUAPP_LIBRARIES} ${target_library})
 	
 	if (MSVC)
 		target_compile_options(${example_name}
@@ -37,11 +40,11 @@ function(make_tolua_interop_example target_library example_suffix)
 			"$<$<CONFIG:RelWithDebInfo>:/MD>"
 			"$<$<CONFIG:MinSizeRel>:/MD>")
 		target_compile_definitions(${example_name}
-			PRIVATE /DUNICODE /D_UNICODE 
-			/D_CRT_SECURE_NO_WARNINGS /D_CRT_SECURE_NO_DEPRECATE)
+			PRIVATE /W1 UNICODE _UNICODE 
+			_CRT_SECURE_NO_WARNINGS _CRT_SECURE_NO_DEPRECATE)
 	else()
 		target_compile_options(${example_name}
-			PRIVATE -std=c++1z
+			PRIVATE -std=c++1z -w
 			-Wno-noexcept-type -Wno-unknown-warning -Wno-unknown-warning-option 
 			-Wall -Wextra -Wpedantic -pedantic -pedantic-errors)
 	endif()
@@ -49,11 +52,7 @@ function(make_tolua_interop_example target_library example_suffix)
 	if (CMAKE_DL_LIBS)
 		target_link_libraries(${example_name} PRIVATE ${CMAKE_DL_LIBS})
 	endif()
-	if (MSVC)
-		target_compile_options(${example_name} PRIVATE /W1)
-	else()
-		target_compile_options(${example_name} PRIVATE -w)
-	endif()
+
 	if (SOL2_TESTS_INTEROP_EXAMPLES)
 		add_test(NAME ${example_name} COMMAND ${example_name})
 	endif()
@@ -67,4 +66,4 @@ if (SOL2_INTEROP_EXAMPLES_SINGLE)
 endif()
 if (SOL2_INTEROP_EXAMPLES_SINGLE_GENERATED)
 	make_tolua_interop_example(sol2::sol2_single_generated ".single.generated")
-endif()
+endif()

examples/interop/tolua/source/tolua.cpp

@@ -9,7 +9,7 @@
 #include "tolua_Player.h"
 
 #include <iostream>
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 // tolua code lifted from some blog, if the link dies
 // I don't know where else you're gonna find the reference,

examples/require_dll_example/CMakeLists.txt

@@ -26,8 +26,8 @@
 # # Also hides variables from directory/global scope
 function(make_require_from_dll_example target_lib example_lib_name_suffix)
 	# define sources
-	set(my_object_sources my_object.cpp my_object.hpp my_object_api.hpp)
-	set(require_from_dll_sources require_from_dll.cpp)
+	set(my_object_sources source/my_object.cpp)
+	set(require_from_dll_sources source/require_from_dll.cpp)
 
 	# define names
 	set(example_lib_name my_object)
@@ -35,19 +35,20 @@ function(make_require_from_dll_example target_lib example_lib_name_suffix)
 	set(example_lib_name "${example_lib_name}${example_lib_name_suffix}")
 	set(example_name "${example_name}${example_lib_name_suffix}")
 	
-	# is the lua library a shared or static library?
-	list(GET LUA_LIBRARIES 0 lua_lib_target)
-	get_target_property(lua_lib_type ${lua_lib_target} TYPE)
-
 	# add library target my_object for the require_from_dll program
 	add_library(${example_lib_name} SHARED ${my_object_sources})
 	set_target_properties(${example_lib_name} PROPERTIES
 		PREFIX "")
 
-	target_include_directories(${example_lib_name} PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}")
-	target_compile_definitions(${example_lib_name} PUBLIC MY_OBJECT_DLL PRIVATE MY_OBJECT_BUILD)
-	target_link_libraries(${example_lib_name} PRIVATE ${target_lib})
-	target_include_directories(${example_lib_name} PUBLIC "${LUA_INCLUDE_DIRS}")
+	target_include_directories(${example_lib_name} 
+		PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include")
+	target_compile_definitions(${example_lib_name} 
+		PUBLIC MY_OBJECT_DLL 
+		PRIVATE MY_OBJECT_BUILD)
+	target_link_libraries(${example_lib_name} 
+		PUBLIC ${target_lib} ${LUA_LIBRARIES} sol2::assert)
+	target_include_directories(${example_lib_name} 
+		PUBLIC "${LUA_INCLUDE_DIRS}")
 	
 	if (MSVC)
 		target_compile_options(${example_lib_name}
@@ -56,41 +57,27 @@ function(make_require_from_dll_example target_lib example_lib_name_suffix)
 			"$<$<CONFIG:RelWithDebInfo>:/MD>"
 			"$<$<CONFIG:MinSizeRel>:/MD>")
 		target_compile_definitions(${example_lib_name}
-			PRIVATE /DUNICODE /D_UNICODE 
-			/D_CRT_SECURE_NO_WARNINGS /D_CRT_SECURE_NO_DEPRECATE)
+			PRIVATE UNICODE _UNICODE 
+			_CRT_SECURE_NO_WARNINGS _CRT_SECURE_NO_DEPRECATE)
 	else()
 		target_compile_options(${example_lib_name}
-			PRIVATE 
-			-Wno-noexcept-type -Wno-unknown-warning -Wno-unknown-warning-option 
+			PRIVATE -Wno-noexcept-type -Wno-unknown-warning -Wno-unknown-warning-option 
 			-Wall -Wextra -Wpedantic -pedantic -pedantic-errors)
+		if (IS_X86)
+			target_compile_options(${example_lib_name} BEFORE PRIVATE -m32)
+		endif()
 	endif()
 
 	if(CMAKE_DL_LIBS)
 		target_link_libraries(${example_lib_name} PUBLIC ${CMAKE_DL_LIBS})
 	endif()
-	if (SOL2_CI)
-		target_compile_definitions(${example_lib_name} PRIVATE SOL2_CI)
-	endif()
-	if (NOT MSVC)
-		target_compile_options(${example_lib_name} PRIVATE -Wno-noexcept-type)
-		if (lua_lib_type MATCHES "STATIC")
-			# ensure that the whole archive is input into the linker
-			# this ensure static builds are included properly
-			target_link_libraries(${example_lib_name} PRIVATE
-				-Wl,-whole-archive ${LUA_LIBRARIES} -Wl,-no-whole-archive)
-		else()
-			target_link_libraries(${example_lib_name} PRIVATE ${LUA_LIBRARIES})
-		endif()
-	else()
-		target_link_libraries(${example_lib_name} PRIVATE ${LUA_LIBRARIES})
-	endif()
-	if (IS_X86)
-		target_compile_options(${example_lib_name} BEFORE PRIVATE -m32)
-	endif()
 	
 	# add executable target that represents require_from_dll program
 	add_executable(${example_name} ${require_from_dll_sources})
-	target_link_libraries(${example_name} PRIVATE my_object ${target_lib})
+	target_link_libraries(${example_name} 
+		PRIVATE my_object ${LUA_LIBRARIES} ${target_lib})
+	target_include_directories(${example_name} 
+		PRIVATE ${LUA_INCLUDE_DIRS})
 
 	if (MSVC)
 		target_compile_options(${example_name}
@@ -99,8 +86,8 @@ function(make_require_from_dll_example target_lib example_lib_name_suffix)
 			"$<$<CONFIG:RelWithDebInfo>:/MD>"
 			"$<$<CONFIG:MinSizeRel>:/MD>")
 		target_compile_definitions(${example_name}
-			PRIVATE /DUNICODE /D_UNICODE 
-			/D_CRT_SECURE_NO_WARNINGS /D_CRT_SECURE_NO_DEPRECATE)
+			PRIVATE UNICODE _UNICODE 
+			_CRT_SECURE_NO_WARNINGS _CRT_SECURE_NO_DEPRECATE)
 	else()
 		target_compile_options(${example_name}
 			PRIVATE -std=c++1z
@@ -111,26 +98,21 @@ function(make_require_from_dll_example target_lib example_lib_name_suffix)
 	if(CMAKE_DL_LIBS)
 		target_link_libraries(${example_name} PRIVATE ${CMAKE_DL_LIBS})
 	endif()
-	if (CI)
-		target_compile_definitions(${example_name} PRIVATE SOL2_CI)
-	endif()
-	if (NOT MSVC)
-		target_compile_options(${example_name} PRIVATE )
-	endif()
 	
-	# avoid multiply defined references due to linking in the same static library
-	# twice over, and get "multiple definition" errors during linking
-	if (NOT lua_lib_type MATCHES "STATIC")
-		target_link_libraries(${example_name} PRIVATE ${LUA_LIBRARIES})
-	endif()
-	target_include_directories(${example_name} PRIVATE ${LUA_INCLUDE_DIRS})
-
 	if (SOL2_TESTS_DYNAMIC_LOADING_EXAMPLES)
 		get_target_property(example_working_dir ${example_name} RUNTIME_OUTPUT_DIRECTORY)
 		add_test(NAME ${example_name} COMMAND ${example_name} WORKING_DIRECTORY "${example_working_dir}")
 	endif()
 endfunction()
 
+list(GET LUA_LIBRARIES 0 lua_lib_target)
+get_target_property(lua_lib_type ${lua_lib_target} TYPE)
+if (lua_lib_type MATCHES "STATIC")
+	# avoid multiply defined references due to linking in the same static library
+	# twice over, and get "multiple definition" errors during linking
+	return()
+endif()
+
 if (SOL2_DYNAMIC_LOADING_EXAMPLES)
 	make_require_from_dll_example(sol2::sol2 "")
 endif()

examples/require_dll_example/include/my_object/my_object.hpp

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "my_object_api.hpp"
+#include <my_object/my_object_api.hpp>
 
 // forward declare as a C struct 
 // so a pointer to lua_State can be part of a signature

examples/require_dll_example/source/my_object.cpp

@@ -1,4 +1,4 @@
-#include "my_object.hpp"
+#include <my_object/my_object.hpp>
 
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>

examples/require_dll_example/source/require_from_dll.cpp

@@ -1,8 +1,8 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "my_object.hpp"
-#include "../assert.hpp"
+#include <my_object/my_object.hpp>
+#include <assert.hpp>
 
 #include <iostream>
 

examples/source/docs/references_in_lambdas.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "../assert.hpp"
+#include <assert.hpp>
 
 int main(int, char*[]) {
 

examples/source/docs/simple_functions.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 
 #include <sol/sol.hpp>
-#include "../assert.hpp"
+#include <assert.hpp>
 
 int main() {
 	sol::state lua;

examples/source/docs/simple_structs.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 
 #include <sol/sol.hpp>
-#include "../assert.hpp"
+#include <assert.hpp>
 
 struct vars {
 	int boop = 0;

examples/source/docs/state_transfer.cpp

@@ -2,7 +2,7 @@
 
 #include <sol/sol.hpp>
 
-#include "../assert.hpp"
+#include <assert.hpp>
 #include <iostream>
 
 int main (int, char*[]) {

examples/source/tutorials/quick_n_dirty/functions_all.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "../../assert.hpp"
+#include <assert.hpp>
 #include <iostream>
 
 void some_function() {

examples/source/tutorials/quick_n_dirty/functions_easy.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 int main(int, char*[]) {
 	sol::state lua;

examples/source/tutorials/quick_n_dirty/make_tables.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 int main(int, char* []) {
 	sol::state lua;

examples/source/tutorials/quick_n_dirty/multiple_returns_from_lua.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 int main(int, char* []) {
 	sol::state lua;

examples/source/tutorials/quick_n_dirty/multiple_returns_to_lua.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 int main(int, char* []) {
 	sol::state lua;

examples/source/tutorials/quick_n_dirty/namespacing.cpp

@@ -2,7 +2,7 @@
 #include <sol/sol.hpp>
 
 #include <iostream>
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 int main() {
 	std::cout << "=== namespacing ===" << std::endl;

examples/source/tutorials/quick_n_dirty/opening_a_state.cpp

@@ -2,7 +2,7 @@
 #include <sol/sol.hpp>
 
 #include <iostream>
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 int main(int, char*[]) {
 	std::cout << "=== opening a state ===" << std::endl;

examples/source/tutorials/quick_n_dirty/running_lua_code.cpp

@@ -3,7 +3,7 @@
 
 #include <fstream>
 #include <iostream>
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 int main(int, char*[]) {
 	std::cout << "=== running lua code ===" << std::endl;

examples/source/tutorials/quick_n_dirty/running_lua_code_low_level.cpp

@@ -4,7 +4,7 @@
 #include <fstream>
 #include <iostream>
 #include <cstdio>
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 int main(int, char*[]) {
 	std::cout << "=== running lua code (low level) ===" << std::endl;

examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 int main(int, char*[]) {
 	sol::state lua;

examples/source/tutorials/quick_n_dirty/set_and_get_variables_exists.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 int main(int, char*[]) {
 	sol::state lua;

examples/source/tutorials/quick_n_dirty/tables_and_nesting.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "../../assert.hpp"
+#include <assert.hpp>
 
 int main(int, char*[]) {
 

examples/source/tutorials/quick_n_dirty/userdata.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "../../assert.hpp"
+#include <assert.hpp>
 #include <iostream>
 
 struct Doge {

examples/source/tutorials/quick_n_dirty/userdata_memory_reference.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "../../assert.hpp"
+#include <assert.hpp>
 #include <iostream>
 
 struct Doge {

examples/source/tutorials/variables_demo.cpp

@@ -2,7 +2,7 @@
 #include <sol.hpp>
 
 #include <tuple>
-#include "../assert.hpp"
+#include <assert.hpp>
 #include <utility> // for std::pair
 
 int main() {

examples/source/wip/lua_inheritance.cpp

@@ -1,7 +1,7 @@
 #define SOL_CHECK_ARGUMENTS 1
 #include <sol/sol.hpp>
 
-#include "../assert.hpp"
+#include <assert.hpp>
 #include <iostream>
 
 int main(int, char*[]) {

tests/compile_tests/CMakeLists.txt

@@ -35,7 +35,8 @@ function(CREATE_TEST test_target_name test_name target_sol)
 		PROPERTIES
 		OUTPUT_NAME ${test_name}
 		EXPORT_NAME sol2::${test_name})
-	target_link_libraries(${test_target_name} ${target_sol})
+	target_link_libraries(${test_target_name} 
+		PUBLIC Threads::Threads ${LUA_LIBRARIES} ${CATCH_LIBRARIES} ${target_sol})
 	
 	if (MSVC)
 		target_compile_options(${test_target_name}
@@ -44,8 +45,8 @@ function(CREATE_TEST test_target_name test_name target_sol)
 			"$<$<CONFIG:RelWithDebInfo>:/MD>"
 			"$<$<CONFIG:MinSizeRel>:/MD>")
 		target_compile_definitions(${test_target_name}
-			PRIVATE /DUNICODE /D_UNICODE 
-			/D_CRT_SECURE_NO_WARNINGS /D_CRT_SECURE_NO_DEPRECATE)
+			PRIVATE UNICODE _UNICODE 
+			_CRT_SECURE_NO_WARNINGS _CRT_SECURE_NO_DEPRECATE)
 	else()
 		target_compile_options(${test_target_name}
 			PRIVATE -std=c++1z -Wno-unknown-warning -Wno-unknown-warning-option 
@@ -74,11 +75,9 @@ function(CREATE_TEST test_target_name test_name target_sol)
 			PRIVATE SOL2_CI)
 	endif()
 	if (CMAKE_DL_LIBS)
-		target_link_libraries(${test_target_name}
+		target_link_libraries(${test_target_name} PUBLIC
 			${CMAKE_DL_LIBS})
 	endif()
-	target_link_libraries(${test_target_name}
-		Threads::Threads ${LUA_LIBRARIES} ${CATCH_LIBRARIES})
 	
 	add_test(NAME ${test_name} COMMAND ${test_target_name})
 	install(TARGETS ${test_target_name} RUNTIME DESTINATION bin)

tests/runtime_tests/CMakeLists.txt

@@ -37,15 +37,9 @@ function(CREATE_TEST test_target_name test_name target_sol)
 		PROPERTIES
 		OUTPUT_NAME ${test_name}
 		EXPORT_NAME sol2::${test_name})
-	target_link_libraries(${test_target_name} ${target_sol})
+	target_link_libraries(${test_target_name} 
+		PUBLIC Threads::Threads ${LUA_LIBRARIES} ${CATCH_LIBRARIES} ${target_sol})
 	
-	add_definitions(/DUNICODE /D_UNICODE /D_CRT_SECURE_NO_WARNINGS /D_CRT_SECURE_NO_DEPRECATE)
-	add_compile_options(/EHsc)
-	add_compile_options("$<$<CONFIG:Debug>:/MDd>"
-		"$<$<CONFIG:Release>:/MD>"
-		"$<$<CONFIG:RelWithDebInfo>:/MD>"
-		"$<$<CONFIG:MinSizeRel>:/MD>")
-
 	if (MSVC)
 		if (NOT CMAKE_COMPILER_ID MATCHES "Clang")
 			target_compile_options(${test_target_name} 
@@ -70,8 +64,8 @@ function(CREATE_TEST test_target_name test_name target_sol)
 			"$<$<CONFIG:RelWithDebInfo>:/MD>"
 			"$<$<CONFIG:MinSizeRel>:/MD>")
 		target_compile_definitions(${test_target_name}
-			PRIVATE /DUNICODE /D_UNICODE 
-			/D_CRT_SECURE_NO_WARNINGS /D_CRT_SECURE_NO_DEPRECATE)
+			PRIVATE UNICODE _UNICODE 
+			_CRT_SECURE_NO_WARNINGS _CRT_SECURE_NO_DEPRECATE)
 	else()
 		target_compile_options(${test_target_name}
 			PRIVATE -std=c++1z -Wno-unknown-warning -Wno-unknown-warning-option 
@@ -87,8 +81,6 @@ function(CREATE_TEST test_target_name test_name target_sol)
 		target_link_libraries(${test_target_name}
 			${CMAKE_DL_LIBS})
 	endif()
-	target_link_libraries(${test_target_name}
-		Threads::Threads ${LUA_LIBRARIES} ${CATCH_LIBRARIES})
 	
 	add_test(NAME ${test_name} COMMAND ${test_target_name})
 	install(TARGETS ${test_target_name} RUNTIME DESTINATION bin)