Documentation for debugging CppInterOp using LLDB (#621)

Author: kr-2003

docs/DebuggingCppInterOp.rst

@@ -0,0 +1,176 @@
+Debugging in JIT Compiled Code
+------------------------------
+
+C++ Language Interoperability Layer - Debugging Guide
+======================================================
+
+Overview
+========
+
+This guide provides comprehensive instructions for debugging CppInterOp applications using LLDB.
+
+Prerequisites
+=============
+
+Before proceeding with debugging, ensure you have the following tools installed:
+
+- **LLDB**: The LLVM debugger
+- **LLVM/Clang**: The C++ compiler and toolchain
+- **CppInterOp**: The C++ language interoperability library
+
+The debugging tools should be available in your LLVM toolchain. On most systems, these are installed alongside your LLVM/Clang installation.
+
+Setting Up Debug Environment
+============================
+
+To effectively debug CppInterOp applications, you need to compile your code with debugging symbols and disable optimizations. This ensures that the debugger can accurately map between source code and machine instructions.
+
+**Compilation Flags**
+
+When compiling your CppInterOp application, use the following essential flags:
+
+.. code-block:: bash
+
+   $CXX -I$CPPINTEROP_DIR/include -g -O0 -lclangCppInterOp -Wl,-rpath,$CPPINTEROP_DIR/build/lib
+
+**Flag Explanation:**
+
+- ``-g``: Includes debugging information in the executable
+- ``-O0``: Disables compiler optimizations for clearer debugging
+- ``-I$CPPINTEROP_DIR/include``: Includes CppInterOp headers
+- ``-lclangCppInterOp``: Links against the CppInterOp library
+- ``-Wl,-rpath,$CPPINTEROP_DIR/build/lib``: Sets runtime library path
+
+Creating a Debug-Ready Test Program
+===================================
+
+Here's a comprehensive example that demonstrates common CppInterOp usage patterns suitable for debugging:
+
+.. code-block:: cpp
+
+  #include "clang/Interpreter/CppInterOp.h"
+  #include <iostream>
+
+  void run_code(std::string code) {
+    Cpp::Declare(code.c_str());
+  }
+
+  int main(int argc, char *argv[]) { 
+    Cpp::CreateInterpreter({"-gdwarf-4", "-O0"});
+    std::vector<Cpp::TCppScope_t> Decls;
+    std::string code = R"(
+  #include <iostream>
+  void f1() {
+    std::cout << "in f1 function" << std::endl;
+  }
+  std::cout << "In codeblock 1" << std::endl;
+  int a = 100;
+  int b = 1000;
+    )";
+    run_code(code);
+    code = R"(
+  f1();
+    )";
+    run_code(code);
+    return 0;
+  }
+
+
+**Program Structure Explanation:**
+
+This example demonstrates key debugging scenarios:
+
+1. **Interpreter Initialization**: The ``Cpp::CreateInterpreter`` call with debug flags
+2. **Code Declaration**: Dynamic C++ code execution through ``Cpp::Declare``
+3. **Mixed Execution**: Combination of compiled and interpreted code paths
+4. **Variable Scoping**: Local variables in both compiled and interpreted contexts
+
+Debugging Strategies
+====================
+
+**Debugging Compiled Code**
+
+For debugging the main executable and compiled portions of your CppInterOp application:
+
+.. code-block:: bash
+
+   lldb /path/to/executable
+   (lldb) settings set plugin.jit-loader.gdb.enable on
+   (lldb) breakpoint set --name f1
+   (lldb) r
+   1 location added to breakpoint 1
+   In codeblock 1
+   Process 49132 stopped
+   * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
+   frame #0: 0x000000010217c008 JIT(0x10215c218) f1() at input_line_1:4:13
+
+**Note**
+
+1. Ensure the JIT loader is enabled to allow LLDB to debug dynamically generated code.
+2. Use ``settings set plugin.jit-loader.gdb.enable on`` to enable JIT debugging.
+3. Set breakpoints in both compiled and interpreted code using ``breakpoint set --name function_name``.
+
+
+**Some Caveats**
+
+1. For each block of code, there is a file named ``input_line_<execution_number>`` that contains the code block. This file is in-memory and thus cannot be directly accessed.
+2. However, generating actual input_line_<number> files on disk will let LLDB pick them up and render the source content correctly during debugging. This can be achieved by modifying run_code as follows:
+
+.. code-block:: cpp
+
+    void run_code(std::string code) {
+        static size_t i = 0;
+        i++;
+        std::string filename = "input_line_" + std::to_string(i);
+        std::ofstream file(filename);
+        file << code;
+        file.close();
+        Cpp::Declare(code.c_str());
+    }
+
+.. note::
+
+    You'll need to manually delete these files later to avoid cluttering the filesystem.
+
+3. If a function is called from different cell, then it may take multiple step-ins to reach the function definition due to the way CppInterOp handles code blocks.
+
+Advanced Debugging Techniques
+=============================
+
+**Using LLDB with VS Code**
+
+For IDE-based debugging:
+
+1. Install the LLDB extension in VS Code
+2. Create a ``launch.json`` configuration:
+
+.. code-block:: json
+
+    {
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "type": "lldb-dap",
+                "request": "launch",
+                "name": "Debug",
+                "program": "/path/to/executable",
+                "sourcePath" : ["${workspaceFolder}"],
+                "cwd": "${workspaceFolder}",
+                "initCommands": [
+                    "settings set plugin.jit-loader.gdb.enable on", // This is crucial 
+                ]
+            },
+        ]
+    }
+
+
+
+Further Reading
+===============
+
+- **LLDB Documentation**: `LLDB Debugger <https://lldb.llvm.org/>`_
+- **CppInterOp Source**: `CppInterOp Repository <https://github.com/compiler-research/CppInterOp>`_
+- **Clang Documentation**: `Clang Compiler <https://clang.llvm.org/docs/>`_
+- **LLVM Debugging Guide**: `LLVM Debug Info <https://llvm.org/docs/SourceLevelDebugging.html>`_
+
+

docs/index.rst

@@ -24,5 +24,6 @@ C++ to simpler, more interactive languages like Python.
   UsingCppInterOp
   reference
   tutorials
+  DebuggingCppInterOp
   FAQ
   DevelopersDocumentation