VALLONGOL/SXXXXXXX_CppPythonDebug
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
master
SXXXXXXX_CppPythonDebug/doc/English-manual.md
VALLONGOL a4f54214b2 update manual
2025-06-13 16:10:56 +02:00

20 KiB
Raw Permalink Blame History

Cpp-Python GDB Debug Helper - User Manual

1. Introduction

1.1 What is Cpp-Python GDB Debug Helper?

The Cpp-Python GDB Debug Helper is a Graphical User Interface (GUI) designed to enhance and simplify the process of debugging C/C++ applications using the GNU Debugger (GDB). It aims to provide a more user-friendly experience compared to the GDB command-line interface, especially for tasks like inspecting complex data structures and automating repetitive debugging scenarios.

1.2 Who is it for?

This tool is primarily aimed at C/C++ developers who use GDB for debugging and would benefit from:

  • A visual interface for common GDB operations.
  • Easier inspection of complex C++ data types (structs, classes, STL containers).
  • Automation of debugging sequences through configurable profiles.
  • Structured output of variable dumps in JSON or CSV formats.

1.3 Key Features

  • Interactive Manual Debugging: Start GDB, set breakpoints, run your target program, and inspect variables.
  • Advanced Variable Dumping: Utilizes a custom GDB Python script to dump the state of C/C++ variables, including complex data structures like classes, structs, pointers, arrays, and std::string, into a structured JSON format.
  • Automated Debug Profiles: Create, manage, and execute debug profiles. Each profile can define:
    • Target executable and program parameters.
    • Multiple debug "actions", each specifying a breakpoint, variables to dump, final output format (JSON/CSV), output directory, and filename patterns.
  • Symbol Analysis: Analyze your compiled executable to extract information about functions, global variables, user-defined types, and source files. This data aids in configuring debug actions.
  • Live Scope Inspection: When configuring an action, the tool can query GDB live to list variables (locals and arguments) available at a specified breakpoint, allowing for precise selection.
  • Configurable Environment: Set paths for GDB, the custom Python dumper script, and various timeouts for GDB operations.
  • Flexible Output: Save dumped data in JSON or CSV formats with customizable filenames using placeholders for better organization.
  • GUI Logging: View application logs and raw GDB output directly within the interface.

2. System Requirements & Setup

2.1 Supported Operating Systems

  • Windows (Primary): The application is primarily developed and tested on Windows. It uses the pexpect library's Windows-compatible backend (PopenSpawn) for robust process control.
  • Linux/macOS (Experimental): The application should be compatible with Unix-like systems as pexpect is cross-platform.

2.2 Python

  • Python 3.7 or newer is recommended.

2.3 Required Python Libraries

You will need to install the following Python libraries. You can install them using pip: pip install pexpect appdirs

  • pexpect: For controlling GDB as a child process.
  • appdirs: Used for determining platform-independent user configuration and data directories (though the primary configuration is now stored relative to the application).
  • Tkinter: This is included with standard Python installations and is used for the GUI.

2.4 GDB Installation

  • A working installation of the GNU Debugger (GDB) is required.
  • Ensure that GDB is either added to your system's PATH environment variable or you provide the full path to the GDB executable in the application's configuration.
  • GDB versions 8.x and newer are recommended for the best Python scripting support.

2.5 Compiling Your C/C++ Target Application

  • Your C/C++ application must be compiled with debugging symbols.
  • For GCC/G++ or Clang, use the -g flag: g++ -g -o myprogram myprogram.cpp.
  • Avoid high levels of optimization (e.g., -O2, -O3) if they interfere with debugging. Consider using -Og (optimize for the debug experience).

3. Installation and Execution

3.1 Running from Source Code

  1. Ensure all prerequisites from Section 2 are met.
  2. Download or clone the source code repository.
  3. Navigate to the root directory of the project (cpp_python_debug).
  4. Run the main script as a module: python -m cpp_python_debug

3.2 Running the Compiled (--onedir) Version

The application can be packaged into a distribution folder using PyInstaller.

  1. Unzip or copy the distribution folder (e.g., CppPythonDebugHelper) to your desired location. This folder is self-contained.
  2. Inside the folder, find and run the main executable (e.g., CppPythonDebugHelper.exe).
  3. All files generated by the application (configurations, logs, dumps) will be created inside this folder, making it fully portable.

4. File and Directory Structure

The application creates and manages several files and directories. Understanding this structure is key to finding your configurations and output.

  • When running from source: All paths are relative to the project's root directory.
  • When running the compiled version: All paths are relative to the folder containing the main executable.
  • config/
    • gdb_debug_gui_settings.v2.json: The main configuration file. It stores all your settings, including paths, timeouts, and all your debug profiles. This file is in JSON format.
  • logs/
    • cpppythondebughelper_gui.log: The main log file for the GUI application itself. Useful for troubleshooting GUI issues.
    • gdb_dumper_script_internal.log: A dedicated log file for the gdb_dumper.py script. This is extremely useful for debugging issues that occur inside GDB during a variable dump.
    • manual_gdb_dumps/: The directory where temporary dump files (.gdbdump.json) from the "Manual Debug" tab are stored before you save them to a final location.
    • gdb_dumper_diagnostics/: (Optional) If you enable "Enable Diagnostic JSON Dump to File" in the settings, this folder will contain a raw JSON copy of every single variable dump, which is useful for debugging the dumper script itself.
  • <Profile Output Directory>: The directory you specify in a profile's action is where the final dump files (JSON or CSV) for that profile run will be saved. The application will create a run-specific subfolder here (e.g., MyDumps/MyProfile_20231027_143000/).

5. Quick Start Guide

  1. Launch the Application as described in Section 3.
  2. Initial Configuration: On first launch, go to Options > Configure Application....
    • In the Paths & Directories tab, browse to your GDB executable.
    • (Strongly Recommended) Also browse to the gdb_dumper.py script located in the core subdirectory of the source code (or cpp_python_debug/core in the compiled version).
    • Click Save.
  3. Your First Manual Debug Session:
    • Go to the Manual Debug tab.
    • Select your compiled C/C++ executable.
    • Enter a breakpoint (e.g., main).
    • Click 1. Start GDB.
    • Click 2. Set Breakpoint.
    • Click 3. Run Program.
    • When the breakpoint is hit, enter a variable name and click 4. Dump Variable.
    • Observe the "Parsed JSON/Status Output" tab. It will show a status message confirming the dump and the path to a temporary .gdbdump.json file.
    • The Save as JSON and Save as CSV buttons will become active. Use them to save the captured data to a permanent location.

6. User Interface Overview

(A screenshot of the main window with areas annotated would be ideal here)

6.1 Menu Bar

  • Options: "Configure Application...", "Exit".
  • Profiles: "Manage Profiles...".

6.2 Critical Configuration Status Area

Displays status of GDB executable and Dumper script. Includes a "Configure..." button.

6.3 Mode Panel (Tabs)

  • Manual Debug Tab: For interactive, step-by-step debugging.
  • Automated Profile Execution Tab: For running pre-configured debug sequences.

6.4 Output and Log Area (Tabs)

  • GDB Raw Output Tab: Raw text communication with the GDB process.
  • Parsed JSON/Status Output Tab: Displays the status payload received from the GDB dumper script or pretty-prints simple JSON.
  • Application Log Tab: Log messages from the GUI application itself.

6.5 Status Bar

Brief messages about the application's current state or last operation.

7. Configuration Window (Options > Configure Application...)

(A screenshot of the Configuration Window with tabs would be beneficial here)

Organized into tabs:

7.1 Paths & Directories Tab

  • GDB Executable Path: Full path to GDB. Crucial.
  • GDB Python Dumper Script Path: Full path to gdb_dumper.py. Strongly recommended for full functionality.

7.2 Timeouts Tab (seconds)

Configure timeouts for GDB operations: GDB Start, GDB Command, Program Run/Continue, Dump Variable, Kill Program, GDB Quit.

7.3 Dumper Options Tab

Control the behavior of gdb_dumper.py: Max Array Elements, Max Recursion Depth, Max String Length, and options for diagnostic logging.

8. Manual Debug Mode in Detail

(A screenshot of the Manual Debug tab would be useful)

This mode provides a step-by-step interface for a single debug session.

8.1 Workflow

  1. Set Target & Parameters: Specify the executable and any command-line arguments.
  2. Set Breakpoint & Variable: Define where to stop and what to inspect. You can use the advanced @ syntax here as well (e.g., my_ptr@100 or my_matrix@rows,cols).
  3. Control Session: Use the numbered buttons (1. Start GDB, 2. Set Breakpoint, 3. Run Program, 4. Dump Variable, Stop GDB) to control the flow.
  4. Dump Data: The "Dump Variable" action invokes the gdb_dumper.py script, which saves the variable's state directly to a temporary .gdbdump.json file.
  5. Save Data: After a successful dump, the "Save as..." buttons become active, allowing you to save the captured data permanently as JSON or CSV. The CSV conversion will use the advanced formatting for matrices if applicable.

8.2 Interpreting Output

  • GDB Raw Output: Shows all communication with GDB, including the status message from the dumper script.
  • Parsed JSON/Status Output: Displays the status payload from the dumper, confirming the action and providing the path to the temporary file.

9. Profile Manager & Automated Execution

(Screenshot of Profile Manager recommended)

This is the core feature for automating debugging.

9.1 Profile Manager (Profiles > Manage Profiles...)

This window is the hub for creating and managing your automated debug scenarios. A profile consists of:

  1. Profile Details: Name, target executable, and program parameters.
  2. Symbol Analysis Data: You can run an analysis on the target executable. The tool uses GDB to find all functions, global variables, etc., and stores this information in the profile. This helps you accurately set up actions.
  3. Actions: A list of debug actions.

9.2 Action Editor

Each action defines a specific task to be performed at a breakpoint.

  • Breakpoint Location: Where GDB should stop.
  • Variables to Dump: A list of variables or expressions to dump (one per line).
    • NEW: Advanced Syntax for Arrays and Matrices: You can provide dimensions for pointer types to dump them as arrays or matrices. This is crucial for handling dynamically allocated memory that GDB cannot inspect on its own.
      • 1D Array (Vector): my_vector_ptr@size
      • 2D Array (Matrix): my_matrix_ptr@rows,cols
    • The size, rows, and cols can be either integer literals (e.g., @100) or other variables visible in the GDB context at that breakpoint (e.g., @my_struct.size, @num_rows,num_cols). This is extremely powerful for dynamically sized data.
  • Output Format: Final format (JSON or CSV).
  • Output Directory: The base directory for the output files.
  • Filename Pattern: A template for naming the output files.
  • Execution Flow: Controls whether to continue after the dump and whether to dump on every hit or just the first.

9.3 Automated Execution Flow

  1. Select a profile from the dropdown on the "Automated Profile Execution" tab.
  2. Click Run Profile.
  3. The ProfileExecutor starts GDB and runs the program.
  4. When a breakpoint is hit, the corresponding action is triggered.
  5. The gdb_dumper.py script is invoked. It dumps the specified variable to an intermediate .gdbdump.json file. This JSON file is now structured with a metadata section (containing information like matrix dimensions) and a data section.
  6. The main application then processes this structured JSON file:
    • If the desired format is JSON, the entire structured object (metadata and data) is saved to the final file.
    • If the desired format is CSV, it reads the structured JSON, writes the metadata as commented header lines in the CSV file, and then flattens the data payload into the appropriate format (e.g., coordinate format for matrices).
  7. The "Produced Files Log" is updated in real-time.

10. Troubleshooting / FAQ

Q: GDB not found / Dumper script issues / No debugging symbols. A: Ensure your configured paths in Options > Configure Application... are correct. Check the Application Log and GDB Raw Output tabs for specific error messages from GDB or the dumper script.

Q: The application hangs or times out. A: Your target program might be taking a long time. Try increasing the timeouts in the Configuration Window. For very large data dumps (e.g., large matrices), the "Dump Variable" timeout may need to be significantly increased.

Q: How can I get more debug information from gdb_dumper.py? A:

  1. Check the logs/gdb_dumper_script_internal.log file. This is the first place to look for errors happening inside the dumper.
  2. For even more detail, enable "Enable Diagnostic JSON Dump to File" in the Dumper Options. This saves a raw JSON copy of every dump to the logs/gdb_dumper_diagnostics/ directory, allowing you to see exactly what the dumper is producing.

11. Use Cases / Examples

11.1 Dumping a std::vector

  • Scenario: You want to inspect the contents of a std::vector<MyObject> myVector every time it's modified inside a processVector function.
  • Profile Setup:
    • Action 1: Breakpoint at the start of processVector.
    • Action 2: Breakpoint at the end of processVector.
    • Both actions dump the myVector variable.
  • Result: When the profile runs, files like vector_dumps/MyProfile_timestamp/processVector_myVector_timestamp.json (or .csv) will be created, allowing you to see the state of the vector before and after processing.

11.2 Tracing a Global Variable

  • Scenario: You need to track how a global variable globalCounter changes at different key points in your application.
  • Profile Setup: Create multiple actions, each with a different breakpoint (e.g., func_A, func_B, main.cpp:150), but all dumping the same variable globalCounter.
  • Result: You will get a series of timestamped files, one for each time the counter was dumped, allowing you to trace its value through the program's execution flow.

11.3 Snapshots of Complex Data

  • Scenario: Your application has a large configuration or state object (ApplicationState appState) and you want to take a complete snapshot of it at a critical point, like just before a long-running task.
  • Profile Setup: An action at longRunningTask.cpp:75 that dumps the appState object.
  • Result: A detailed JSON file like app_state_snapshots/MyProfile_timestamp/longRunningTask.cpp_75_appState_timestamp.json will be created, containing a full, nested representation of your application's state.

11.4 Dumping a Dynamic 2D Matrix of Structs

  • Scenario: You have a C struct ComplexSignal_t signal which contains int n_row;, int n_col;, and a pointer rgk_complex_float* data;. The data pointer points to a flat, row-major memory block. You want to dump this entire matrix to a CSV file for analysis in Python/MATLAB.

  • Profile Setup:

    • Create an action at a breakpoint where signal is in scope.
    • In "Variables to Dump", enter: signal.data@signal.n_row,signal.n_col
    • Set "Output Format" to csv.

  • Result: The application will generate a single, clean CSV file.

    • Metadata Header: The top of the file will contain commented lines with the matrix dimensions, e.g., # original_rows: 1024, # original_cols: 512. This allows your analysis scripts to pre-allocate memory efficiently.
    • Data Body: The rest of the file will be in a "coordinate" (long) format, perfect for analysis: 
      row_idx,col_idx,re,im
0,0,1.23,-0.45
0,1,1.25,-0.48
...
1023,511,3.14,1.59

    This file can be loaded directly into a Pandas DataFrame or other analysis tools.

12. Advanced: The gdb_dumper.py Script

12.1 Role and Interaction with GDB

The gdb_dumper.py script is the core of the data extraction engine. It runs within the GDB process and has access to GDB's Python API.

  • Serialization Logic:

    1. Uses gdb.parse_and_eval() to get a gdb.Value object representing a C++ variable.
    2. Optimized Memory Reading: For large arrays and matrices (specified with @ syntax), it now uses an optimized memory-reading approach. Instead of evaluating each element individually, it reads the entire memory block of the matrix in a single GDB operation (inferior.read_memory). It then uses Python's struct module to unpack the raw bytes into data. This is orders of magnitude faster for large datasets.
    3. It constructs a Python dictionary containing a metadata key (for dimensions, type info, etc.) and a data key (for the actual variable content).
    4. This structured dictionary is serialized to a JSON string.
    5. The dumper saves this full JSON string directly to a specified intermediate file (.gdbdump.json).
    6. It prints a small status JSON payload (indicating success/failure and the path written) to GDB's standard output, bracketed by special delimiters.

  • GUI Processing: The main GUI captures this status payload to understand the outcome of the dump. In Profile Mode, it then processes the intermediate file to create the final user-specified output (saving the full structured JSON, or converting to a metadata-rich CSV).

12.2 Dumper Log File (gdb_dumper_script_internal.log)

This log file, located in the main logs directory, is invaluable for debugging the dumper script itself. It records internal steps, configurations, and errors that occur within the GDB environment, which are not visible in the main application log.

13. Appendix: Filename Placeholders

The following placeholders can be used in the "Filename Pattern" field (in the Action Editor) to construct the base name of your output files. The application automatically sanitizes the content of each placeholder to make it safe for file systems.

  • {profile_name}: The name of the profile.
  • {app_name}: Base name of the target executable.
  • {breakpoint}: The breakpoint location string. For file:line formats, this will be sanitized to something like file_line.
  • {variable}: The variable/expression name being dumped. For expressions with special characters like var@size,dim, this will be sanitized to just var.
  • {timestamp}: A detailed timestamp (YYYYMMDD_HHMMSS_ms).

Example Pattern: dump_{app_name}_{breakpoint}_{variable}_{timestamp} Example Final Output (if JSON): dump_myprogram_main_myVar_20231027_143005_123.json Example Intermediate GDB Dump File: dump_myprogram_main_myVar_20231027_143005_123.gdbdump.json