engine: Add LRDB debugging support

- Add slimmed down LRDB library to the engine/vendor/lrdb directory.
- It can be compiled in or out via option (in by default)
- The command-line flags are --debug-lua and --debug-lua-port

Author: cassava

NOTICE.md

@@ -70,6 +70,12 @@ The following third-party libraries are included in the Cloe repository:
   - Website: https://github.com/kikito/inspect.lua
   - Source: engine/lua/inspect.lua
 
+- LRDB
+  - License: BSL-1.0
+  - License-Source: https://www.boost.org/LICENSE_1_0.txt
+  - Website: https://github.com/satoren/LRDB
+  - Source: engine/vendor/lrdb
+
 - Lust
   - License: MIT
   - License-Source: https://raw.githubusercontent.com/bjornbytes/lust/master/LICENSE

conanfile.py

@@ -50,6 +50,7 @@ class Cloe(ConanFile):
         "fPIC": [True, False],
         "fable_allow_comments": [True, False],
         "engine_server": [True, False],
+        "engine_lrdb": [True, False],
         "with_esmini": [True, False],
         "with_vtd": [True, False],
     }
@@ -58,6 +59,7 @@ class Cloe(ConanFile):
         "fPIC": True,
         "fable_allow_comments": True,
         "engine_server": True,
+        "engine_lrdb": True,
         "with_esmini": True,
         "with_vtd": False,
     }
@@ -134,6 +136,7 @@ def generate(self):
         tc.cache_variables["CLOE_VERSION"] = self.version
         tc.cache_variables["CLOE_VERSION_U32"] = version_u32
         tc.cache_variables["CLOE_ENGINE_WITH_SERVER"] = self.options.engine_server
+        tc.cache_variables["CLOE_ENGINE_WITH_LRDB"] = self.options.engine_lrdb
         tc.cache_variables["CLOE_WITH_ESMINI"] = self.options.with_esmini
         tc.cache_variables["CLOE_WITH_VTD"] = self.options.with_vtd
         tc.generate()

docs/reference/lua-initialization.md

@@ -12,6 +12,7 @@ by a Lua file: `cloe-engine run simulation.lua`
 
    - Lua package path (`--lua-path`, `CLOE_LUA_PATH`)
    - Disable system packages (`--no-system-lua`)
+   - Enable LRDB Lua debugger (`--debug-lua`)
    - Cloe plugins (`--plugin-path`, `CLOE_PLUGIN_PATH`)
 
 2. Initialize Cloe Stack
@@ -25,11 +26,13 @@ by a Lua file: `cloe-engine run simulation.lua`
    - Expose Cloe API via `cloe` Lua table
    - Load Cloe Lua runtime (located in the package `lib/cloe/lua` directory)
 
-4. Source input files
+4. Start LRDB Lua debugger (Optional)
+
+5. Source input files
 
    - Files ending with `.lua` are merged as Lua
    - Other files are read as JSON
 
-5. Start simulation
+6. Start simulation
 
    - Schedule triggers pending from the Lua script

engine/CMakeLists.txt

@@ -123,6 +123,7 @@ set_target_properties(cloe-enginelib PROPERTIES
 target_compile_definitions(cloe-enginelib
   PUBLIC
     SOL_ALL_SAFETIES_ON=1
+    LRDB_USE_BOOST_ASIO=1
     CLOE_ENGINE_VERSION="${CLOE_ENGINE_VERSION}"
     CLOE_ENGINE_TIMESTAMP="${CLOE_ENGINE_TIMESTAMP}"
     PROJECT_SOURCE_DIR=\"${CMAKE_CURRENT_SOURCE_DIR}\"
@@ -155,6 +156,16 @@ else()
   target_compile_definitions(cloe-enginelib PUBLIC CLOE_ENGINE_WITH_SERVER=0)
 endif()
 
+option(CLOE_ENGINE_WITH_LRDB "Enable LRDB Lua Debugger?" ON)
+if(CLOE_ENGINE_WITH_LRDB)
+  add_subdirectory(vendor/lrdb)
+  target_sources(cloe-enginelib PRIVATE src/lua_debugger.cpp)
+  target_link_libraries(cloe-enginelib PRIVATE lrdb::lrdb)
+  target_compile_definitions(cloe-enginelib PUBLIC CLOE_ENGINE_WITH_LRDB=1)
+else()
+  target_compile_definitions(cloe-enginelib PUBLIC CLOE_ENGINE_WITH_LRDB=0)
+endif()
+
 if(BUILD_TESTING)
     message(STATUS "Building test-enginelib executable.")
     add_executable(test-enginelib
@@ -176,7 +187,7 @@ if(BUILD_TESTING)
 endif()
 
 # Executable ---------------------------------------------------------
-message(STATUS "Building cloe-engine executable [with server=${CLOE_ENGINE_WITH_SERVER}].")
+message(STATUS "Building cloe-engine executable [with server=${CLOE_ENGINE_WITH_SERVER}, lrdb=${CLOE_ENGINE_WITH_LRDB}].")
 add_subdirectory(vendor/linenoise)
 add_executable(cloe-engine
     src/main.cpp

engine/conanfile.py

@@ -21,12 +21,16 @@ class CloeEngine(ConanFile):
         # server dependencies are incompatible with your target system.
         "server": [True, False],
 
+        # Whether the LRDB integration is compiled and built into the Cloe engine.
+        "lrdb": [True, False],
+
         # Make the compiler be strict and pedantic.
         # Disable if you upgrade compilers and run into new warnings preventing
         # the build from completing. May be removed in the future.
         "pedantic": [True, False],
     }
     default_options = {
+        "lrdb": True,
         "server": True,
         "pedantic": True,
 
@@ -72,6 +76,7 @@ def generate(self):
         tc.cache_variables["CMAKE_EXPORT_COMPILE_COMMANDS"] = True
         tc.cache_variables["CLOE_PROJECT_VERSION"] = self.version
         tc.cache_variables["CLOE_ENGINE_WITH_SERVER"] = self.options.server
+        tc.cache_variables["CLOE_ENGINE_WITH_LRDB"] = self.options.lrdb
         tc.cache_variables["TargetLintingExtended"] = self.options.pedantic
         tc.generate()
 

engine/lua/cloe-engine/init.lua

@@ -56,6 +56,7 @@ local engine = {
             ["cloe-stackfile-4.1"] = true,
 
             ["cloe-server"] = false,
+            ["cloe-lrdb"] = false,
         },
 
         --- @type table Lua table dumped as JSON report at end of simulation.

engine/src/lua_debugger.cpp

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2023 Robert Bosch GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * \file stack_lua.cpp
+ */
+
+#include "lua_setup.hpp"
+
+#include <lrdb/server.hpp>  // lrdb::server
+#include <sol/state_view.hpp>  // for state_view
+
+namespace cloe {
+
+void start_lua_debugger(sol::state& lua, int listen_port) {
+  static lrdb::server debug_server(listen_port);
+  debug_server.reset(lua.lua_state());
+}
+
+}  // namespace cloe

engine/src/lua_setup.cpp

@@ -198,7 +198,8 @@ void register_cloe_engine(sol::state_view& lua, Stack& stack) {
     "cloe-stackfile-4.1", true,
 
     // Server enabled:
-    "cloe-server", CLOE_ENGINE_WITH_SERVER != 0
+    "cloe-server", CLOE_ENGINE_WITH_SERVER != 0,
+    "cloe-lrdb", CLOE_ENGINE_WITH_LRDB != 0
   );
   // clang-format on
 

engine/src/lua_setup.hpp

@@ -58,6 +58,16 @@ struct LuaOptions {
  */
 sol::state new_lua(const LuaOptions& opt, Stack& s);
 
+#if CLOE_ENGINE_WITH_LRDB
+/**
+ * Start Lua debugger server on port.
+ *
+ * \param lua
+ * \param listen_port
+ */
+void start_lua_debugger(sol::state& lua, int listen_port);
+#endif
+
 /**
  * Merge the provided Lua file into the existing `Stack`, respecting `StackOptions`.
  *

engine/src/main.cpp

@@ -79,6 +79,11 @@ int main(int argc, char** argv) {
   run->add_flag("--require-success,!--no-require-success", run_options.require_success,
                 "Require simulation success")
       ->envname("CLOE_REQUIRE_SUCCESS");
+  run->add_flag("--debug-lua", run_options.debug_lua,
+                "Debug the Lua simulation");
+  run->add_option("--debug-lua-port", run_options.debug_lua_port,
+                  "Port to listen on for debugger to attach to")
+      ->envname("CLOE_DEBUG_LUA_PORT");
   run->add_option("files", run_files, "Files to merge into a single stackfile")->required();
 
   // One of the above subcommands must be used.

engine/src/main_commands.hpp

@@ -75,6 +75,9 @@ struct RunOptions {
   bool write_output = true;
   bool require_success = false;
   bool report_progress = true;
+
+  bool debug_lua = false;
+  int debug_lua_port = 21110;
 };
 
 int run(const RunOptions& opt, const std::vector<std::string>& filepaths);

engine/src/main_run.cpp

@@ -64,6 +64,16 @@ int run(const RunOptions& opt, const std::vector<std::string>& filepaths) {
   // Load the stack file:
   cloe::Stack stack = cloe::new_stack(opt.stack_options);
   sol::state lua = cloe::new_lua(opt.lua_options, stack);
+#if CLOE_ENGINE_WITH_LRDB
+  if (opt.debug_lua) {
+    log->info("Lua debugger listening at port: {}", opt.debug_lua_port);
+    cloe::start_lua_debugger(lua, opt.debug_lua_port);
+  }
+#else
+  if (opt.debug_lua) {
+    log->error("Lua debugger feature not available.");
+  }
+#endif
   try {
     cloe::conclude_error(*opt.stack_options.error, [&]() {
       for (const auto& file : filepaths) {

engine/src/main_version.cpp

@@ -45,6 +45,7 @@ int version(const VersionOptions& opt) {
       {"stack", CLOE_STACK_VERSION},                      // from "stack.hpp"
       {"plugin_manifest", CLOE_PLUGIN_MANIFEST_VERSION},  // from <cloe/plugin.hpp>
       {"feature_server", CLOE_ENGINE_WITH_SERVER != 0},   // from CMakeLists.txt
+      {"feature_lrdb", CLOE_ENGINE_WITH_LRDB != 0},       // from CMakeLists.txt
   };
 
   if (opt.output_json) {

engine/vendor/lrdb/CMakeLists.txt

@@ -0,0 +1,19 @@
+cmake_minimum_required(VERSION 3.15 FATAL_ERROR)
+
+project(LRDB LANGUAGES CXX)
+
+add_library(lrdb INTERFACE)
+add_library(lrdb::lrdb ALIAS lrdb)
+target_include_directories(lrdb
+  INTERFACE
+    "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>"
+    "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/third_party/picojson>"
+)
+target_link_libraries(lrdb
+  INTERFACE
+    lua::lua
+)
+set_target_properties(lrdb PROPERTIES
+  CXX_STANDARD 17
+  CXX_STANDARD_REQUIRED ON
+)

engine/vendor/lrdb/LICENSE_1_0.txt

@@ -0,0 +1,23 @@
+Boost Software License - Version 1.0 - August 17th, 2003
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+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, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

engine/vendor/lrdb/NOTICE

@@ -0,0 +1,14 @@
+LRDB Modifications
+==================
+
+The LRDB library is sourced from the GitHub repository below:
+
+  - License: BSL-1.0
+  - License-Source: https://www.boost.org/LICENSE_1_0.txt
+  - Website: https://github.com/satoren/LRDB
+
+The source code has been modified in following ways:
+
+- Remove files not relevant to our use (e.g. test, node, cmake).
+- Replace include/lrdb/debugger.hpp implementation of is_file_path_match.
+- Replace CMakeLists.txt with a simplified version.