SXXXXXXX_CppPythonDebug/doc/English-manual.md

## 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`