VALLONGOL/SXXXXXXX_CppPythonDebug
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
914c351c45
SXXXXXXX_CppPythonDebug/doc/English-manual.md
VALLONGOL 914c351c45 change from wexpect to pexpect
2025-06-10 08:36:43 +02:00

20 KiB
Raw 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. Dumped data is saved to a temporary file, with options to save it permanently in JSON or CSV.
  • 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. This JSON is saved directly to a file by the GDB dumper.
  • 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. Dumped data is saved directly to a file by the GDB dumper, with an intermediate JSON file being created and then potentially converted to CSV or renamed based on the profile settings.
  • Symbol Analysis: Analyze your compiled executable (using GDB's Machine Interface) 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, various timeouts for GDB operations, and dumper behavior options.
  • Flexible Output: Save dumped data in JSON or CSV formats with customizable filenames using placeholders for better organization. JSON is always the initial dump format from GDB, which can then be automatically converted to CSV if specified in a profile.
  • GUI Logging: View application logs and raw GDB output directly within the interface.

2. System Requirements & Environment Setup

2.1 Supported Operating Systems

  • Windows: Primary development and testing platform due to the use of the pexpect library for GDB process control.
  • Linux/macOS: GDB itself is cross-platform. The core GDB interaction logic might require adaptation for pexpect on Unix-like systems for full compatibility (this adaptation is not currently part of the provided codebase).

2.2 Python

  • Python 3.7 or newer is recommended (tested with versions up to 3.13).

2.3 Required Python Libraries

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

  • pexpect: For controlling GDB as a child process on Windows.
  • appdirs: Used for determining platform-independent user configuration and data directories.
  • Tkinter: This is usually included with standard Python installations and is used for the GUI. No separate installation is typically needed.

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 window.
  • GDB versions 8.x and newer are generally recommended for better 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 -Og (optimize for debug experience).

2.6 Tool Installation (Cpp-Python GDB Debug Helper)

Currently, the software is designed to be run from its source code:

  1. Ensure all prerequisites are met.
  2. Download or clone the source code.
  3. Navigate to the root directory of the project (e.g., cpp_python_debug).
  4. Run the main script using Python: python -m cpp_python_debug

3. Quick Start Guide

3.1 Launching the Application

  1. Meet "System Requirements & Environment Setup".
  2. Navigate to the project's root directory.
  3. Execute: python -m cpp_python_debug.

3.2 Initial Configuration (GDB Path)

  1. On first launch, or if GDB isn't found, go to Options > Configure Application....
  2. In the Paths & Directories tab, for "GDB Executable Path", click Browse... and select your GDB executable.
  3. Click Save. The status area should show "GDB: ... (OK)".

(Strongly Recommended) Configure Dumper Script Path:

  • The custom Python script (gdb_dumper.py, in the core sub-directory) enables advanced JSON dumping and is essential for the automated profile execution to save data to files effectively.
  • In Options > Configure Application... > Paths & Directories tab, for "GDB Python Dumper Script Path", Browse... to gdb_dumper.py.
  • Click Save.

3.3 Your First Manual Debug Session

  1. Select "Manual Debug" Tab.
  2. Target Executable: Click Browse... and select your compiled C/C++ executable.
  3. Program Parameters (Optional): Enter command-line arguments if needed.
  4. Breakpoint Location: Enter a breakpoint (e.g., main, myfile.cpp:42).
  5. Variable/Expression to Dump: Enter the variable/expression to inspect (e.g., myLocalVar).
  6. Start GDB: Click 1. Start GDB. "GDB Raw Output" shows GDB startup. Status bar indicates "GDB session active."
  7. Set Breakpoint: Click 2. Set Breakpoint. "GDB Raw Output" shows confirmation.
  8. Run Program: Click 3. Run Program. Program runs until breakpoint. Button changes to "3. Continue".
  9. Dump Variable:
    • Action: When at a breakpoint, click 4. Dump Variable. GDB (via the dumper script) evaluates the expression, serializes it to JSON, and saves it to a temporary .gdbdump.json file in a dedicated manual dumps directory. The GUI receives a status message.
    • Output:
      • "GDB Raw Output": Shows communication with the dumper script and the status JSON it returns.
      • "Parsed JSON/Status Output": Displays the status JSON received from the dumper script, showing success/failure, the path to the temporary .gdbdump.json file, etc.
    • Button States: "Save as JSON", "Save as CSV", and "Open Dumps Folder" buttons become active if the temporary dump file was successfully created.
  10. Continue/Stop: Use 3. Continue or Stop GDB.
  11. Saving Data: After a dump, click Save as JSON or Save as CSV. This reads the temporary .gdbdump.json file, converts/saves it to your chosen final location and format, and then typically deletes the temporary file. Click Open Dumps Folder to view the directory where temporary manual dumps are stored.

Congratulations! You've completed your first manual debug session.

4. User Interface Overview (Main Window)

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

4.1 Menu Bar

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

4.2 Critical Configuration Status Area

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

4.3 Mode Panel (Tabs)

  • Manual Debug Tab: (See Section 6) For interactive debugging.
  • Automated Profile Execution Tab: (See Section 9) For running pre-configured debug sequences.

4.4 Output and Log Area (Tabs)

  • GDB Raw Output Tab: Raw text from the GDB process.
  • Parsed JSON/Status Output Tab: Displays pretty-printed JSON (less common now for profiles) or the status JSON payload received from the GDB dumper script (for both Manual and Profile modes).
  • Application Log Tab: Log messages from the GUI application itself.

4.5 Status Bar

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

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

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

Organized into tabs:

5.1 Paths & Directories Tab

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

5.2 Timeouts Tab (seconds)

Configure timeouts for GDB operations (all in seconds):

  • GDB Start: (Default: 30s)
  • GDB Command: (Default: 30s)
  • Program Run/Continue: (Default: 120s)
  • Dump Variable: (Default: 60s)
  • Kill Program: (Default: 20s)
  • GDB Quit: (Default: 10s)

5.3 Dumper Options Tab

Control the behavior of gdb_dumper.py:

  • Max Array Elements: (Default: 100)
  • Max Recursion Depth: (Default: 10)
  • Max String Length: (Default: 2048)
  • Enable Diagnostic JSON Dump to File: (Default: False) If checked, saves an additional raw JSON copy of every dump for dumper script debugging.
  • Diagnostic JSON Output Directory: Folder for these diagnostic dumps. (Default: ~/gdb_dumper_diag_dumps)

5.4 Saving and Cancelling

  • Save Button: Validates, applies, saves all settings to the configuration file, and closes.
  • Cancel Button / Window 'X': Discards changes and closes.

6. Manual Debug Mode

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

6.1 Setting Target Executable and Parameters Fields for "Target Executable" (with Browse...) and "Program Parameters".

6.2 Setting Breakpoint Location Field for breakpoint (e.g., main, file.cpp:123).

6.3 Setting Variable/Expression to Dump Field for the variable or GDB expression.

6.4 Session Control Buttons

  1. 1. Start GDB
  2. 2. Set Breakpoint
  3. 3. Run Program / 3. Continue
  4. 4. Dump Variable: (Key change) Commands GDB to dump the variable and save it to a temporary .gdbdump.json file. The GUI receives a status message.
  5. Stop GDB

6.5 Interpreting GDB Raw Output Shows GDB communication, including the status JSON from the dumper.

6.6 Interpreting Parsed JSON/Status Output Displays the status JSON payload from the dumper script:

  • status: "success" or "error".
  • variable_dumped: The targeted variable.
  • filepath_written: Path to the temporary .gdbdump.json file created.
  • message, details: Confirmation or error information.

6.7 Saving Dumped Data (JSON/CSV) & Managing Dumps After a successful dump (temporary file created):

  • Save as JSON/CSV Buttons: Enabled. Opens a "Save As" dialog. Reads the temporary .gdbdump.json, then converts/saves to the chosen final file. The temporary file is typically deleted after a successful "Save As..." operation.
  • Open Dumps Folder Button: Opens the directory where temporary JSON files from manual dumps are stored (configured via manual_dumps_output_path, usually in the application's config area).

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

(Screenshot of Profile Manager recommended)

7.1 Overview Left pane for profile list & controls (New, Duplicate, Delete). Right pane for selected profile's details, symbol analysis, and debug actions. Bottom buttons to "Save All Changes" and "Close".

7.2 Managing Profiles Select, create new, duplicate, or delete profiles. "Save All Changes" persists everything.

7.3 Editing Profile Details Edit "Profile Name" (must be unique), "Target Executable", and "Program Parameters".

7.4 Symbol Analysis Displays status of stored symbol analysis against the current target in the form (checksums, timestamps).

  • Analyse Target Symbols Button: Triggers a new analysis for the current target, storing results in the selected profile (in memory, requires "Save All Changes" to persist).
  • View... Buttons: View lists of analyzed functions, globals, types, and sources if data is available and relevant.

7.5 Managing Debug Actions List of actions for the profile. "Add...", "Edit...", "Remove" buttons open the Action Editor (Section 8).

8. Action Editor Window (from Profile Manager)

(Screenshot of Action Editor recommended)

Defines a single debug action.

8.1 Breakpoint Location Field and "Funcs..." / "Files..." assistance buttons (using symbol analysis or live GDB query).

8.2 Variables to Dump Scrolled text area (one per line). "Globals..." and "Scope Vars..." buttons assist selection (Scope Vars runs a live GDB inspection).

8.3 Output Format Combobox: "json" or "csv".

8.4 Output Directory Directory for this action's output files. A run-specific subfolder is created here.

8.5 Filename Pattern Pattern for output filenames.

  • Available Placeholders: {profile_name}, {app_name}, {breakpoint}, {variable}, {timestamp}.
  • The final extension (.json or .csv) is appended by the application based on the "Output Format" selection. The GDB dumper itself will first create an intermediate file with a .gdbdump.json extension.
  • Example Pattern: dump_{app_name}_{breakpoint}_{variable}_{timestamp}
  • This pattern defines the base name of the file.

8.6 "Continue execution after dump" Option Checkbox to control GDB's behavior after the action.

8.7 "Dump variables every time breakpoint is hit" Option

  • Checked (Default): Variables are dumped every time this breakpoint is encountered.
  • Unchecked: Variables are dumped only the first time this breakpoint is hit during a profile run for this specific action. Subsequent hits to the same breakpoint for this action will be skipped if the action has already "completed" once.

8.8 Saving/Cancelling "OK" saves the action to the profile in Profile Manager. "Cancel" discards.

9. Automated Profile Execution Mode

(Screenshot of Automated Execution tab recommended)

9.1 Selecting a Profile Dropdown lists available profiles.

9.2 Running the Profile "Run Profile" button starts execution. GUI controls are updated. A ProfileExecutor runs in a separate thread.

  • GDB starts, dumper is sourced, breakpoints are set.
  • On breakpoint hit:
    • Dumper saves raw JSON to an intermediate file (e.g., ...action.gdbdump.json).
    • If final format is JSON, the intermediate file is renamed.
    • If final format is CSV, the intermediate JSON is read, converted to CSV, saved, and the intermediate JSON is usually deleted.
    • "Produced Files Log" is updated.

9.3 Monitoring Status and Progress Bar Status label and progress bar show execution state.

9.4 Stopping a Running Profile "Stop Profile" button gracefully attempts to terminate.

9.5 Interpreting the "Produced Files Log" Tree view with: Time, Breakpoint Spec, Variable, File Produced (final name), Status, Details, and potentially "Raw GDB Dump File" (path to the .gdbdump.json if kept due to an error).

9.6 Opening the Output Folder "Open Profile Output Folder" button opens the main output directory for the last completed profile run.

10. Troubleshooting / FAQ

Q: GDB not found / Dumper script issues / No debugging symbols / _gdb_tool_error in JSON. A: (Same advice as before, emphasizing checking gdb_dumper_debug.log for dumper issues).

Q: Profile execution issues (fails, hangs, BPs not hit). A: (Same advice as before, verify paths, BPs, parameters, timeouts).

Q: GUI unresponsive. A: (Same advice as before, check timeouts, console/Application Log for errors).

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

  1. Check gdb_dumper_debug.log. Location is logged by gdb_dumper.py on startup (see GDB Raw Output or the log file itself, usually in ~ or alongside gdb_dumper.py).
  2. The main GUI application (__main__.py) deletes this log on startup for a clean session log.
  3. To get even more verbose output for dumper script development, you can enable the "Enable Diagnostic JSON Dump to File" option in Options > Configure Application... > Dumper Options. This saves an additional raw JSON copy of every GDB dump to the "Diagnostic JSON Output Directory".

11. Use Cases / Examples

(Content largely the same, but reinforce that output files are now directly created based on profile settings)

11.1 Dumping a std::vector

  • ...When the profile runs, files like vector_dumps/ProfileName_timestamp/processVector_myVector_timestamp.json (or .csv) will be created.

11.2 Tracing a global variable

  • ...Output files for globalCounter will be generated at each breakpoint location.

11.3 Snapshots of complex data

  • ...A series of JSON files like app_state_snapshots/ProfileName_timestamp/longRunningTask.cpp_75_appState_timestamp.json will be created.

12. Advanced: The gdb_dumper.py Script

12.1 Role and Interaction with GDB

  • ...
  • Serialization Logic:
    1. Uses gdb.parse_and_eval() to get the variable.
    2. Traverses the gdb.Value, applying "Dumper Options".
    3. Constructs a Python representation.
    4. Serializes to a JSON string.
    5. If a target_output_filepath is provided by the main application (standard for both Manual and Profile modes), the dumper saves the full JSON string directly to this specified file (typically with a .gdbdump.json extension). It then prints a small status JSON payload (indicating success/failure and the path written) to GDB's standard output, bracketed by delimiters.
  • GUI Processing:
    • The GUI captures GDB's output, extracts the status JSON payload, and parses it. This payload informs the GUI about the success of the GDB-side dump and the location of the raw JSON file created by the dumper.
    • In Manual Mode, this raw JSON file is then used if the user chooses "Save as JSON" or "Save as CSV" (and is deleted after successful save).
    • In Profile Mode, if the profile action specified "csv", the GUI reads this raw JSON file, converts it to CSV, saves it as the final output, and typically deletes the raw JSON. If "json" was specified, the raw JSON file is usually renamed to the final filename.

12.2 Dumper Log File (gdb_dumper_debug.log) (Content mostly the same, emphasizing its role for dumper-internal issues).

13. Appendix (Optional)

13.1 Filename Placeholder Summary

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 appropriate extension (.json or .csv for the final file, and .gdbdump.json for the intermediate GDB dump) will be managed by the application.

  • {profile_name}: The name of the profile (sanitized).
  • {app_name}: Base name of the target executable.
  • {breakpoint}: Breakpoint location string (sanitized).
  • {variable}: Variable/expression name (sanitized).
  • {timestamp}: Timestamp (YYYYMMDD_HHMMSS_fff).

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