SXXXXXXX_CppPythonDebug/doc/English-manual.md

USER MANUAL (ENGLISH)

---

Cpp-Python GDB Debug Helper - User Manual

1. Introduction

Welcome to Cpp-Python GDB Debug Helper! This software is designed to assist C/C++ developers in debugging their programs by providing an intuitive graphical interface to control GDB (the GNU Debugger) and, crucially, to facilitate the inspection and export of complex data in structured formats like JSON and CSV.

If you've ever found yourself navigating intricate data structures or long arrays in the GDB terminal, or wished you could save the state of a variable for more thorough analysis, this tool is for you. It leverages GDB's Python API to "dissect" your variables and present them clearly.

Key Features at a Glance:

• Graphical control of the GDB session (start, breakpoints, execution).
• Dumping of C/C++ variables into a readable JSON format.
• Customizable configuration for GDB and the dumping process.
• Export of dumped data to JSON or CSV.
• Display of GDB output and application logs.

2. Installation and Requirements

System Requirements:

• Python: Version 3.7 or later. You can download it from python.org. Ensure Python is added to your system's PATH.
• GDB (GNU Debugger): A version of GDB that includes Python scripting support (most recent versions do). If you are using MinGW on Windows, GDB is typically included. Ensure the GDB executable is accessible.
• Operating System: Primarily tested on Windows, but it should work on Linux or macOS with GDB and Python installed (may require pexpect instead of wexpect on non-Windows systems, although wexpect is a fork aiming for compatibility).

Application Installation:

1. Clone the Repository (if applicable) or Download Source Files:

   git clone <YOUR_GITEA_REPOSITORY_URL>
   cd <project_directory_name>
   

2. Create a Virtual Environment (Recommended):

   python -m venv venv
   # On Windows
   venv\Scripts\activate
   # On Linux/macOS
   source venv/bin/activate
   

3. Install Dependencies: A requirements.txt file (if provided) should list the dependencies. The main ones are:
   • wexpect: For controlling the GDB process on Windows.
   • appdirs: For cross-platform configuration directory management. You can install them using pip:

   pip install wexpect appdirs
   ```    If a `requirements.txt` file is present:
   ```bash
   pip install -r requirements.txt
   

Verify GDB Installation: Open a terminal and type gdb --version. You should see GDB version information. If the command is not found, GDB is not in your PATH or not installed.

3. Quick Start Guide

Follow these steps to get started quickly:

1. Launch the Application: From the project's root directory, run:

   python -m cpp_python_debug
   

   The main application window will open.

2. Configure GDB (First Time Only):

   • Go to "Options" > "Configure Application...".
   • In the "Paths" tab, click "Browse..." next to "GDB Executable" and select your gdb.exe file (e.g., C:\MinGW\bin\gdb.exe).
   • The "GDB Dumper Script" should be auto-detected if the gdb_dumper.py script is in its standard location (core/gdb_dumper.py relative to the project). Otherwise, you can specify it manually.
   • Click "Save".

3. Set Target and Breakpoint in the Main Window:

   • Target Executable: Click "Browse..." and select the C/C++ executable (compiled with debug symbols, e.g., -g flag with GCC/Clang) you want to debug.
   • Breakpoint Location: Enter where you want the program to stop (e.g., main, MyClass::myMethod, myfile.cpp:123).
   • Variable/Expression: Enter the name of the variable or expression you want to inspect when the breakpoint is hit (e.g., myVector, *this, global_struct.member).

4. Start Debugging:

   • Click "1. Start GDB Session". The "GDB Raw Output" section will show GDB starting up.
   • If GDB and the dumper script are configured correctly, the status at the top of the window should indicate this.

5. Set the Breakpoint:

   • Click "2. Set Breakpoint".

6. Run the Program:

   • Click "3. Run Program" (or "3. Continue" if the program has already started).
   • The program should run and stop at your specified breakpoint. The GDB output will show where it stopped.

7. Dump the Variable:

   • Click "4. Dump Variable".
   • The "Parsed JSON Output" tab will display the variable's structure in JSON format.
   • The GDB raw output will show START_JSON_OUTPUT and END_JSON_OUTPUT delimiters around the raw JSON.

8. Save Data (Optional):

   • Use the "Save as JSON" or "Save as CSV" buttons to save the dumped data.

9. End the Session:

   • Click "Stop GDB Session" to terminate GDB.
   • Close the application via "Options" > "Exit" or the window's close button. Settings will be saved.