Oss release master created 2021-11-10-09-16

see CHANGELOG.md for details

Original commit sha: 65416eb4c0fd704742e0a620e322080c9604865b

Co-authored-by: Daniel Haas <25718295+bojackHaasman@users.noreply.github.com>
Co-authored-by: Tobias Hammer <tohammer@users.noreply.github.com>
Co-authored-by: Bernhard Kisslinger <65217745+bkisslinger@users.noreply.github.com>
Co-authored-by: Violin Yanev <violinyanev@users.noreply.github.com>

CHANGELOG.md

@@ -1,5 +1,21 @@
 # master
 
+# v0.12.0
+
+**API Changes**
+
+* Re-implemented Lua environment sandboxing
+    * This is a safety feature which was temporarily reverted to allow usage of global variables
+    * This version reintroduces it - there are now better alternatives:
+        * [init() function](https://ramses-logic.readthedocs.io/en/v0.11.0/lua_syntax.html#global-variables-and-the-init-function)
+        * [Custom modules](https://ramses-logic.readthedocs.io/en/v0.11.0/lua_syntax.html#custom-modules)
+    * Docs for new behavior: see [Lua docs](https://ramses-logic.readthedocs.io/en/v0.12.0/lua_syntax.html#environments-and-isolation)
+
+**Features**
+
+* Added a new tool - a viewer binary which can load, show and configure binary ramses/logic scenes
+    * For more info, read the [docs](https://ramses-logic.readthedocs.io/en/v0.12.0/viewer.html#ramses-logic-viewer)
+
 # v0.11.0
 
 **Features**

CMakeLists.txt

@@ -14,7 +14,7 @@ cmake_minimum_required(VERSION 3.13)
 #==========================================================================
 
 set(RLOGIC_VERSION_MAJOR 0)
-set(RLOGIC_VERSION_MINOR 11)
+set(RLOGIC_VERSION_MINOR 12)
 set(RLOGIC_VERSION_PATCH 0)
 
 set(RLOGIC_VERSION ${RLOGIC_VERSION_MAJOR}.${RLOGIC_VERSION_MINOR}.${RLOGIC_VERSION_PATCH})
@@ -97,12 +97,6 @@ set(RLOGIC_INSTALL_ARCHIVE_PATH     lib)
 
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)
 
-set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules" ${CMAKE_MODULE_PATH})
-
-include(cmake/platformConfig.cmake)
-include(cmake/externalTools.cmake)
-include(cmake/folderize.cmake)
-
 # By default redirect binaries and shared libs to /bin for easier development
 if (NOT CMAKE_LIBRARY_OUTPUT_DIRECTORY)
     message(STATUS "Redirect ramses logic library output to ${CMAKE_CURRENT_BINARY_DIR}/bin")
@@ -119,6 +113,12 @@ if(NOT ramses-logic_FORCE_OFF_TESTS AND (ramses-logic_FORCE_BUILD_TESTS OR CMAKE
     set(ramses-logic_BUILD_TESTS ON)
 endif()
 
+set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules" ${CMAKE_MODULE_PATH})
+
+include(cmake/platformConfig.cmake)
+include(cmake/externalTools.cmake)
+include(cmake/folderize.cmake)
+
 if(ramses-logic_BUILD_TESTS)
     include(cmake/testSetup.cmake)
 endif()
@@ -249,6 +249,10 @@ if(ramses-logic_BUILD_EXAMPLES)
     add_subdirectory(examples)
 endif()
 
+if(ramses-logic_BUILD_TOOLS)
+    add_subdirectory(tools)
+endif()
+
 include(cmake/addCheckerTargets.cmake)
 
 #==========================================================================

README.md

@@ -34,6 +34,7 @@ Prefer to learn by example? Have a look at our [self-contained example snippets]
 
 |Logic    | Included Ramses version       | Minimum required Ramses version    | Binary file compatibility    |
 |---------|-------------------------------|------------------------------------|------------------------------|
+|0.12.0   | 27.0.113                      | same as 0.6.0                      | 0.9.x                        |
 |0.11.0   | 27.0.113                      | same as 0.6.0                      | 0.9.x                        |
 |0.10.2   | 27.0.112                      | same as 0.6.0                      | 0.9.x                        |
 |0.10.1   | 27.0.111                      | same as 0.6.0                      | 0.9.x                        |
@@ -61,7 +62,6 @@ listed alongside their licenses here:
 * Sol (MIT)
 * Flatbuffers (Apache-2.0)
 * Fmtlib (MIT)
-* ImGui (MIT)
 * Googletest (BSD-3-Clause)
 * Google Benchmark (Apache-2.0)
 

cmake/platformConfig.cmake

@@ -138,11 +138,31 @@ ENDIF()
 # Special handling for C++17 filesystem
 # Unfortunately not trivial, please keep this CMake config in one place!
 
+function(check_handle_special_filesystem_lib libname)
+    include(CheckCXXSourceCompiles)
+    set(CMAKE_REQUIRED_LIBRARIES ${libname})
+    check_cxx_source_compiles("int main() {}" RLOGIC_HAS_STD_FS)
+
+    if (RLOGIC_HAS_STD_FS)
+        link_libraries(${libname})
+    else()
+        if (ramses-logic_BUILD_TESTS)
+            message(FATAL_ERROR "std::filesystem libary not found. Cannot use emulation with tests enabled")
+        endif()
+        if (NOT CMAKE_SYSTEM_NAME STREQUAL Linux)
+            message(FATAL_ERROR "std::filesystem libary not found. Can use emulation only on Linux")
+        endif()
+
+        message(STATUS "std::filesystem libary not found, enable emulation")
+        add_definitions("-DRLOGIC_STD_FILESYSTEM_EMULATION")
+    endif()
+endfunction()
+
 # GCC prior version 9.1 puts filesystem in a separate static lib (stdc++fs) and potentially in the experimental namespace
 if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "GNU" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 9.1)
-    link_libraries(stdc++fs)
+    check_handle_special_filesystem_lib(stdc++fs)
     # gcc prior version 8 puts symbols in the experimental namespace
-    if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 8)
+    if(RLOGIC_HAS_STD_FS AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 8)
         add_definitions("-DRLOGIC_STD_FILESYSTEM_EXPERIMENTAL")
     endif()
 endif()
@@ -154,17 +174,19 @@ if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang" AND CMAKE_CXX_COMPILER_VERSION VE
     string(FIND "${CMAKE_CXX_FLAGS}" "-stdlib=libc++" USES_LIBCXX)
     if(USES_LIBCXX EQUAL -1)
         # Link stdc++fs from the std lib
-        link_libraries(stdc++fs)
+        check_handle_special_filesystem_lib(stdc++fs)
         # llvm prior version 7 puts symbols in the experimental namespace
-        if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 7)
+        if(RLOGIC_HAS_STD_FS AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 7)
             add_definitions("-DRLOGIC_STD_FILESYSTEM_EXPERIMENTAL")
         endif()
     else()
         message(STATUS "Detected usage of libc++, using libc++ specific compiler flags")
         # See docs for more details https://libcxx.llvm.org/docs/UsingLibcxx.html#using-libc-experimental-and-experimental
         if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 7)
-            link_libraries(c++experimental)
-            add_definitions("-DRLOGIC_STD_FILESYSTEM_EXPERIMENTAL")
+            check_handle_special_filesystem_lib(c++experimental)
+            if (RLOGIC_HAS_STD_FS)
+                add_definitions("-DRLOGIC_STD_FILESYSTEM_EXPERIMENTAL")
+            endif()
         else()
             link_libraries(libc++fs)
         endif()

doc/sphinx/api.rst

@@ -507,9 +507,10 @@ such pointers after loading from file.
 File compatibility
 --------------------------------------------------
 
-Since version ``0.7.0``, Ramses Logic binary files are backwards and forwards compatible.
-This means that a newer version of the runtime can be used to load an older binary file and vice-versa.
-For the exact compatibility info, see the `version matrix <https://ramses-logic.readthedocs.io/en/latest/readme_ref.html#version-matrix>`_.
+Since version ``0.7.0``, Ramses Logic binary files are backwards compatible.
+This means that a newer version of the runtime can be used to load an older binary file, unless the file format version
+had a breaking change and a newer version of the Logic Engine must be used.
+The exact compatibility info is documented in the `version matrix <https://ramses-logic.readthedocs.io/en/latest/readme_ref.html#version-matrix>`_.
 There are some limitations:
 
 * Loading a file older than v0.7.0 will result in an error with a runtime equal or newer than v0.7.0

doc/sphinx/index.rst

@@ -23,6 +23,12 @@ Ramses Logic documentation
 
     build
 
+.. toctree::
+    :maxdepth: 3
+    :caption: Viewer
+
+    viewer
+
 .. toctree::
     :maxdepth: 3
     :caption: Lua Syntax

doc/sphinx/lua_syntax.rst

@@ -192,7 +192,8 @@ have a primitive type (e.g. ``INT``) or a complex type (a struct) which can have
 Global variables and the init() function
 ==============================================
 
-Global symbols (symbols declared outside of the scope of functions) are **not** visible in the ``interface()`` or the ``run()`` functions.
+Global symbols (symbols declared outside of the scope of functions) are **not** visible in the ``interface()`` or the ``run()`` functions
+(see :ref:`Environments and isolation`).
 This restriction makes sure that scripts are stateless and not execution-dependent and that they behave the same after loading from a file as when they
 were created.
 
@@ -223,6 +224,23 @@ two functions - ``interface()`` and ``run()``.
 
 You can also use modules in ``init()``, see the :ref:`modules section <Using Lua modules>`.
 
+==============================================
+Environments and isolation
+==============================================
+
+``Lua`` is a powerful scripting language which can do practically anything. This can be a problem sometimes - especially
+if the scripts are running in a restricted environment with strict safety and security concerns. In order to reduce the
+risk of security attacks and stability problems, the ``Logic Engine`` isolates scripts in their own `environment <https://www.lua.org/pil/14.3.html>`_ and limits
+the access of data and code. This ensures that a script can not be influenced by other scripts, modules, or dynamically loaded
+content, unless explicitly desired by the content creator.
+
+The following set of rules describes which part of the ``Lua`` script is assigned to which environment:
+
+* Each script has its own ``runtime`` environment - applied to the ``run()`` function
+* The ``init()`` function is also executed in the runtime environment
+* The ``interface()`` function is executed in a temporary environment which is destroyed afterwards (alongside all its data!)
+* The ``interface()`` function has access to modules and the ``GLOBAL`` table, but nothing else
+
 ==================================================
 Indexing inside Lua
 ==================================================