|
| 1 | +--- |
| 2 | +title: "Implementing Debugging Support for xeus-cpp" |
| 3 | +layout: post |
| 4 | +excerpt: "A GSoC 2025 project aiming at integration of debugger into the xeus-cpp kernel for Jupyter using LLDB and its Debug Adapter Protocol (lldb-dap)." |
| 5 | +sitemap: false |
| 6 | +author: Abhinav Kumar |
| 7 | +permalink: blogs/gsoc25_abhinav_kumar_introduction_blog/ |
| 8 | +banner_image: /images/blog/gsoc-banner.png |
| 9 | +date: 2025-05-22 |
| 10 | +tags: gsoc c++ debugger dap clang jupyter |
| 11 | +--- |
| 12 | + |
| 13 | +### Introduction |
| 14 | + |
| 15 | +I am Abhinav Kumar, a final-year Computer Science and Engineering undergraduate at Indian Institute of Technology(IIT) Indore. I'm thrilled to be working with CERN-HSF for Google Summer of Code 2025 on the project "Implementing Debugging Support for xeus-cpp." |
| 16 | + |
| 17 | +**Mentors**: Anutosh Bhat, Vipul Cariappa, Aaron Jomy, Vassil Vassilev |
| 18 | + |
| 19 | + |
| 20 | +### The Need for Seamless C++ Debugging in Jupyter |
| 21 | + |
| 22 | +[Jupyter](https://jupyter.org/) notebooks have revolutionized interactive computing, and kernels like [xeus-cpp](https://github.com/compiler-research/xeus-cpp/) bring the power of C++ to this environment. However, while writing and executing C++ code incrementally is great, the debugging experience can be a hurdle. Developers often need to step through their code, inspect variables, and understand the program's state, especially when dealing with the complexities that C++ can present. This project aims to bridge that gap by integrating robust debugging capabilities directly into the xeus-cpp kernel. |
| 23 | + |
| 24 | +### Project Goal: Interactive Debugging with LLDB and DAP |
| 25 | +The core idea is to bring a full-fledged debugging experience to xeus-cpp users within Jupyter. This means enabling features like: |
| 26 | + |
| 27 | +1. **Breakpoint Management**: Setting and removing breakpoints with ease. |
| 28 | +2. **Variable Inspection**: Examining the values of variables at different execution stages. |
| 29 | +3. **Step-Through Execution**: Controlling the flow of code execution (step in, step over, step out). |
| 30 | +4. **Stack Tracing**: Understanding the call stack to pinpoint issues. |
| 31 | + |
| 32 | +To achieve this, the project will leverage existing, powerful technologies: |
| 33 | + |
| 34 | +1. **LLDB**: The [LLVM debugger](https://lldb.llvm.org/), which has excellent support for JIT-compiled code and Clang integration—perfect for how xeus-cpp executes code dynamically. |
| 35 | +2. **Debug Adapter Protocol (DAP)**: A [standardized protocol](https://microsoft.github.io/debug-adapter-protocol//) by Microsoft that allows debuggers to communicate with development tools. This ensures compatibility with Jupyter's frontend and follows the successful model of [xeus-python](https://github.com/jupyter-xeus/xeus-python). |
| 36 | + |
| 37 | +A key design principle is to run the debugger (specifically, [lldb-dap](https://lldb.llvm.org/resources/lldbdap.html), which acts as a DAP server for LLDB) as an external process. This is crucial for kernel stability, preventing the Jupyter kernel from freezing when a breakpoint is hit. |
| 38 | + |
| 39 | +### Proposed Architecture Overview |
| 40 | +The proposed system involves a few key components working together: |
| 41 | +<img src="/images/blog/debugger_xeus_cpp_architecture.png" alt="Project Architecture" style="width: 90%; height: auto"/> |
| 42 | + |
| 43 | +1. **Jupyter Environment (Notebook & Server)**: The user interface where DAP requests are initiated and responses are displayed. |
| 44 | + |
| 45 | +2. **xeus-cpp Kernel**: |
| 46 | + - ``xcpp::debugger``: A new class that will manage the debugging session, inheriting from **xeus::xdebugger_base**. It will handle DAP messages and interact with the lldb-dap client. |
| 47 | + - ``xcpp::xlldb_dap_client``: This component will manage the actual DAP communication with the external lldb-dap process. |
| 48 | + - ``JIT Engine``: Compiles the C++ code from cells and notifies LLDB about new symbols. |
| 49 | + |
| 50 | +3. **External Debugger (lldb-dap & LLDB)**: |
| 51 | + - ``lldb-dap``: Runs as a separate server, translating DAP messages into LLDB API calls and vice-versa. |
| 52 | + - ``LLDB``: Executes the debugging actions on the JIT-compiled code. |
| 53 | + |
| 54 | +This modular design, inspired by [xeus-python](https://github.com/jupyter-xeus/xeus-python), aims for a lightweight integration that reuses existing xeus infrastructure where possible. |
| 55 | + |
| 56 | +### Progress and Path Forward |
| 57 | + |
| 58 | +I've already made some promising headway: |
| 59 | + |
| 60 | +1. Successfully demonstrated that LLDB can attach to and debug JIT-compiled code generated by [CppInterOp](https://github.com/compiler-research/CppInterOp/) (which xeus-cpp relies on). This involved ensuring symbols are resolved correctly when ``plugin.jit-loader.gdb.enable`` is active in LLDB. |
| 61 | +2. Set up debugging in VSCode using lldb-dap for JIT-compiled code, proving the viability of lldb-dap for this context. |
| 62 | +3. Experimented with running the lldb-dap executable on a specific port and sending DAP requests (initialize, launch, setBreakpoints, continue) via a Python script, successfully hitting breakpoints and getting stack traces. |
| 63 | + |
| 64 | +The roadmap includes: |
| 65 | + |
| 66 | +1. **Implementing debugger class**: Defining the main debugger class, handling the debugger lifecycle, and managing LLDB-DAP settings. A key modification will be using a "launch" request instead of "attach" (as xeus-python does), because LLDB needs to launch our custom executable containing the JIT code. This might require minor adjustments in xeus-zmq. |
| 67 | +2. **Developing lldb-dap client**: This class will inherit from ``xeus::xdap_tcp_client`` and manage the low-level DAP communication. |
| 68 | +3. **Robust Testing**: Implementing a comprehensive testing framework using [GoogleTest](https://github.com/google/googletest). |
| 69 | + |
| 70 | +### Expected Benefits and Future Scope |
| 71 | + |
| 72 | +Successfully completing this project will significantly enhance the C++ development experience within Jupyter notebooks. It will provide: |
| 73 | + |
| 74 | +1. A seamless, interactive debugging workflow for xeus-cpp users. |
| 75 | +2. Increased productivity by allowing developers to quickly identify and fix bugs in their C++ notebook code. |
| 76 | +3. A more robust and feature-complete C++ kernel for the Jupyter ecosystem. |
| 77 | + |
| 78 | +Looking ahead, the architecture is designed with future-proofing in mind, potentially supporting advanced features like remote debugging, alternative debuggers or debugger in xeus-cpp-lite. |
0 commit comments