VALLONGOL/SXXXXXXX_CppPythonDebug
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update manual

Browse Source
This commit is contained in:
VALLONGOL 2025-06-11 09:13:25 +02:00
parent 107eb6749c
commit a716ca7e96
7 changed files with 323 additions and 529 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
cpp_python_debug/_version.py
View File

@ -6,10 +6,10 @@
import re import re
# --- Version Data (Generated) --- # --- Version Data (Generated) ---
__version__ = "v.0.0.0.28-0-g9035dbc-dirty" __version__ = "v.0.0.0.29-0-g675a032-dirty"
GIT_COMMIT_HASH = "9035dbc5286fd8a018822a906a293ce3fd11fe33" GIT_COMMIT_HASH = "675a032af46832124bc4f58a855e5595bbcf0432"
GIT_BRANCH = "master" GIT_BRANCH = "master"
BUILD_TIMESTAMP = "2025-06-10T06:53:58.932893+00:00" BUILD_TIMESTAMP = "2025-06-10T07:07:10.120869+00:00"
IS_GIT_REPO = True IS_GIT_REPO = True
# --- Default Values (for comparison or fallback) --- # --- Default Values (for comparison or fallback) ---

BIN
doc/English-manual.docx
View File

Binary file not shown.

417
doc/English-manual.md
View File

@ -17,369 +17,282 @@ This tool is primarily aimed at C/C++ developers who use GDB for debugging and w
**1.3 Key Features** **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. * **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. This JSON is saved directly to a file by the GDB dumper. * **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: * **Automated Debug Profiles:** Create, manage, and execute debug profiles. Each profile can define:
* Target executable and program parameters. * 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. * 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 (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. * **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. * **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. * **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. JSON is always the initial dump format from GDB, which can then be automatically converted to CSV if specified in a profile. * **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. * **GUI Logging:** View application logs and raw GDB output directly within the interface.
--- ---
### 2. System Requirements & Environment Setup ### 2. System Requirements & Setup
**2.1 Supported Operating Systems** **2.1 Supported Operating Systems**
* **Windows:** Primary development and testing platform due to the use of the `pexpect` library for GDB process control. * **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:** 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). * **Linux/macOS (Experimental):** The application should be compatible with Unix-like systems as `pexpect` is cross-platform.
**2.2 Python** **2.2 Python**
* Python 3.7 or newer is recommended (tested with versions up to 3.13). * Python 3.7 or newer is recommended.
**2.3 Required Python Libraries** **2.3 Required Python Libraries**
You will need to install the following Python libraries. You can typically install them using pip: You will need to install the following Python libraries. You can install them using pip:
`pip install pexpect appdirs` `pip install pexpect appdirs`
* **`pexpect`**: For controlling GDB as a child process on Windows. * **`pexpect`**: For controlling GDB as a child process.
* **`appdirs`**: Used for determining platform-independent user configuration and data directories. * **`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 usually included with standard Python installations and is used for the GUI. No separate installation is typically needed. * **Tkinter**: This is included with standard Python installations and is used for the GUI.
**2.4 GDB Installation** **2.4 GDB Installation**
* A working installation of the GNU Debugger (GDB) is required. * A working installation of the GNU Debugger (GDB) is required.
* Ensure that GDB is either: * 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.
* Added to your system's `PATH` environment variable. * GDB versions 8.x and newer are recommended for the best Python scripting support.
* 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** **2.5 Compiling Your C/C++ Target Application**
* Your C/C++ application **must be compiled with debugging symbols**. * 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`. * 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). * Avoid high levels of optimization (e.g., `-O2`, `-O3`) if they interfere with debugging. Consider using `-Og` (optimize for the debug experience).
**2.6 Tool Installation (Cpp-Python GDB Debug Helper)** ---
Currently, the software is designed to be run from its source code: ### 3. Installation and Execution
1. Ensure all prerequisites are met. **3.1 Running from Source Code**
2. Download or clone the source code.
3. Navigate to the root directory of the project (e.g., `cpp_python_debug`). 1. Ensure all prerequisites from Section 2 are met.
4. Run the main script using Python: 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` `python -m cpp_python_debug`
--- **3.2 Running the Compiled (`--onedir`) Version**
### 3. Quick Start Guide The application can be packaged into a distribution folder using PyInstaller.
**3.1 Launching the Application** 1. Unzip or copy the distribution folder (e.g., `cpp_python_debug`) to your desired location. This folder is self-contained.
2. Inside the folder, find and run the main executable (e.g., `cpp_python_debug.exe`).
1. Meet "System Requirements & Environment Setup". 3. All files generated by the application (configurations, logs, dumps) will be created inside this folder, making it fully portable.
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) ### 4. File and Directory Structure
**(Screenshot of the main window with areas annotated would be ideal here)** The application creates and manages several files and directories. Understanding this structure is key to finding your configurations and output.
**4.1 Menu Bar** * **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
**6.1 Menu Bar**
* **Options:** "Configure Application...", "Exit". * **Options:** "Configure Application...", "Exit".
* **Profiles:** "Manage Profiles...". * **Profiles:** "Manage Profiles...".
**4.2 Critical Configuration Status Area** **6.2 Critical Configuration Status Area**
Displays status of GDB executable and Dumper script. Includes a "Configure..." button. Displays status of GDB executable and Dumper script. Includes a "Configure..." button.
**4.3 Mode Panel (Tabs)** **6.3 Mode Panel (Tabs)**
* **Manual Debug Tab:** (See Section 6) For interactive debugging. * **Manual Debug Tab:** For interactive, step-by-step debugging.
* **Automated Profile Execution Tab:** (See Section 9) For running pre-configured debug sequences. * **Automated Profile Execution Tab:** For running pre-configured debug sequences.
**4.4 Output and Log Area (Tabs)** **6.4 Output and Log Area (Tabs)**
* **GDB Raw Output Tab:** Raw text from the GDB process. * **GDB Raw Output Tab:** Raw text communication with 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). * **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. * **Application Log Tab:** Log messages from the GUI application itself.
**4.5 Status Bar** **6.5 Status Bar**
Brief messages about the application's current state or last operation. Brief messages about the application's current state or last operation.
--- ---
### 5. Configuration Window (`Options > Configure Application...`) ### 7. Configuration Window (`Options > Configure Application...`)
**(A screenshot of the Configuration Window with tabs would be beneficial here)**
Organized into tabs: Organized into tabs:
**5.1 Paths & Directories Tab** **7.1 Paths & Directories Tab**
* **GDB Executable Path:** Full path to GDB. *Crucial.* * **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.* * **GDB Python Dumper Script Path:** Full path to `gdb_dumper.py`. *Strongly recommended for full functionality.*
**5.2 Timeouts Tab (seconds)** **7.2 Timeouts Tab (seconds)**
Configure timeouts for GDB operations (all in seconds): Configure timeouts for GDB operations: GDB Start, GDB Command, Program Run/Continue, Dump Variable, Kill Program, GDB Quit.
* **GDB Start:** (Default: 30s) **7.3 Dumper Options Tab**
* **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, Max Recursion Depth, Max String Length, and options for diagnostic logging.
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 ### 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.
**6.1 Setting Target Executable and Parameters** **8.1 Workflow**
Fields for "Target Executable" (with Browse...) and "Program Parameters". 1. **Set Target & Parameters:** Specify the executable and any command-line arguments.
2. **Set Breakpoint & Variable:** Define where to stop and what to inspect.
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 saves the variable's state 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.
**6.2 Setting Breakpoint Location** **8.2 Interpreting Output**
Field for breakpoint (e.g., `main`, `file.cpp:123`). * **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.
**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...`) ### 9. Profile Manager & Automated Execution
**(Screenshot of Profile Manager recommended)** This is the core feature for automating debugging.
**7.1 Overview** **9.1 Profile Manager (`Profiles > Manage Profiles...`)**
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** This window is the hub for creating and managing your automated debug scenarios. A profile consists of:
Select, create new, duplicate, or delete profiles. "Save All Changes" persists everything. 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.
**7.3 Editing Profile Details** **9.2 Action Editor**
Edit "Profile Name" (must be unique), "Target Executable", and "Program Parameters".
**7.4 Symbol Analysis** Each action defines a specific task to be performed at a breakpoint.
Displays status of stored symbol analysis against the current target in the form (checksums, timestamps). * **Breakpoint Location**: Where GDB should stop.
* **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). * **Variables to Dump**: Which variables to inspect.
* **View... Buttons:** View lists of analyzed functions, globals, types, and sources if data is available and relevant. * **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**: Whether to continue after the dump and whether to dump on every hit or just the first.
**7.5 Managing Debug Actions** **9.3 Automated Execution Flow**
List of actions for the profile. "Add...", "Edit...", "Remove" buttons open the Action Editor (Section 8).
--- 1. Select a profile from the dropdown on the "Automated Profile Execution" tab.
2. Click **Run Profile**.
### 8. Action Editor Window (from Profile Manager) 3. The `ProfileExecutor` starts GDB and runs the program.
4. When a breakpoint is hit, the corresponding action is triggered.
**(Screenshot of Action Editor recommended)** 5. The `gdb_dumper.py` script is invoked, which dumps the specified variable(s) to intermediate `.gdbdump.json` files.
6. The main application then processes these intermediate files:
Defines a single debug action. * If the desired format is **JSON**, it renames the file according to the pattern.
* If the desired format is **CSV**, it reads the JSON, converts it, saves the new `.csv` file, and deletes the intermediate JSON.
**8.1 Breakpoint Location** 7. The "Produced Files Log" is updated in real-time with the status of each file created.
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 ### 10. Troubleshooting / FAQ
**Q: GDB not found / Dumper script issues / No debugging symbols / `_gdb_tool_error` in JSON.** **Q: GDB not found / Dumper script issues / No debugging symbols.**
**A:** (Same advice as before, emphasizing checking `gdb_dumper_debug.log` for dumper issues). **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: Profile execution issues (fails, hangs, BPs not hit).** **Q: The application hangs or times out.**
**A:** (Same advice as before, verify paths, BPs, parameters, timeouts). **A:** Your target program might be taking a long time. Try increasing the timeouts in the Configuration Window.
**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`?** **Q: How can I get more debug information from `gdb_dumper.py`?**
**A:** **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`). 1. Check the `logs/gdb_dumper_script_internal.log` file. This is the first place to look for errors happening inside the dumper.
2. The main GUI application (`__main__.py`) deletes this log on startup for a clean session log. 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.
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 ### 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`** **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** * **Scenario:** You want to inspect the contents of a `std::vector<MyObject> myVector` every time it's modified inside a `processVector` function.
* ...Output files for `globalCounter` will be generated at each breakpoint location. * **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.3 Snapshots of complex data** **11.2 Tracing a Global Variable**
* ...A series of JSON files like `app_state_snapshots/ProfileName_timestamp/longRunningTask.cpp_75_appState_timestamp.json` will be created.
* **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.
--- ---
### 12. Advanced: The `gdb_dumper.py` Script ### 12. Advanced: The `gdb_dumper.py` Script
**12.1 Role and Interaction with GDB** **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`)** 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.
(Content mostly the same, emphasizing its role for dumper-internal issues).
* **Serialization Logic:**
1. Uses `gdb.parse_and_eval()` to get a `gdb.Value` object representing a C++ variable.
2. Recursively traverses this object, respecting the "Dumper Options" (max depth, etc.).
3. Constructs a Python dictionary/list representation of the C++ data.
4. Serializes this Python object into a JSON string.
5. Saves the full JSON string directly to a specified intermediate file (e.g., `...name.gdbdump.json`).
6. 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 (renaming for JSON, converting for 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 (Optional) ### 13. Appendix: Filename Placeholders
**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 final file extension (`.json` or `.csv`) is managed automatically.
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 for filesystem safety).
* `{profile_name}`: The name of the profile (sanitized).
* `{app_name}`: Base name of the target executable. * `{app_name}`: Base name of the target executable.
* `{breakpoint}`: Breakpoint location string (sanitized). * `{breakpoint}`: The breakpoint location string (sanitized).
* `{variable}`: Variable/expression name (sanitized). * `{variable}`: The variable/expression name being dumped (sanitized).
* `{timestamp}`: Timestamp (`YYYYMMDD_HHMMSS_fff`). * `{timestamp}`: A detailed timestamp (`YYYYMMDD_HHMMSS_ms`).
**Example Pattern:** `dump_{app_name}_{breakpoint}_{variable}_{timestamp}` **Example Pattern:** `dump_{app_name}_{breakpoint}_{variable}_{timestamp}`
**Example Final Output (if JSON):** `dump_myprogram_main_myVar_20231027_143005_123.json` **Example Final Output (if JSON):** `dump_myprogram_main_myVar_20231027_143005_123.json`

BIN
doc/English-manual.pdf
View File

Binary file not shown.

BIN
doc/Italian-manual.docx
View File

Binary file not shown.

425
doc/Italian-manual.md
View File

@ -4,7 +4,7 @@
**1.1 Cos'è Cpp-Python GDB Debug Helper?** **1.1 Cos'è Cpp-Python GDB Debug Helper?**
Cpp-Python GDB Debug Helper è un'Interfaccia Utente Grafica (GUI) progettata per migliorare e semplificare il processo di debugging di applicazioni C/C++ utilizzando GNU Debugger (GDB). Mira a fornire un'esperienza più intuitiva rispetto all'interfaccia a riga di comando di GDB, specialmente per attività come l'ispezione di strutture dati complesse e l'automazione di scenari di debugging ripetitivi. Il Cpp-Python GDB Debug Helper è un'Interfaccia Utente Grafica (GUI) progettata per migliorare e semplificare il processo di debugging di applicazioni C/C++ utilizzando il GNU Debugger (GDB). Mira a fornire un'esperienza più intuitiva rispetto all'interfaccia a riga di comando di GDB, specialmente per attività come l'ispezione di strutture dati complesse e l'automazione di scenari di debugging ripetitivi.
**1.2 A chi è rivolto?** **1.2 A chi è rivolto?**
@ -17,369 +17,250 @@ Questo strumento è principalmente destinato agli sviluppatori C/C++ che usano G
**1.3 Caratteristiche Principali** **1.3 Caratteristiche Principali**
* **Debugging Manuale Interattivo:** Avvia GDB, imposta breakpoint, esegui il tuo programma target e ispeziona le variabili. I dati dumpati vengono salvati in un file temporaneo, con opzioni per salvarli permanentemente in JSON o CSV. * **Debugging Manuale Interattivo:** Avvia GDB, imposta breakpoint, esegui il tuo programma target e ispeziona le variabili.
* **Dumping Avanzato delle Variabili:** Utilizza uno script Python personalizzato per GDB per dumpare lo stato delle variabili C/C++, incluse strutture dati complesse come classi, struct, puntatori, array e `std::string`, in un formato JSON strutturato. Questo JSON viene salvato direttamente su file dallo script dumper di GDB. * **Dumping Avanzato delle Variabili:** Utilizza uno script Python personalizzato per GDB per estrarre lo stato delle variabili C/C++, incluse strutture dati complesse come classi, struct, puntatori, array e `std::string`, in un formato JSON strutturato.
* **Profili di Debug Automatizzati:** Crea, gestisci ed esegui profili di debug. Ogni profilo può definire: * **Profili di Debug Automatizzati:** Crea, gestisci ed esegui profili di debug. Ogni profilo può definire:
* Eseguibile target e parametri del programma. * Eseguibile target e parametri del programma.
* Molteplici "azioni" di debug, ognuna specificando un breakpoint, variabili da dumpare, formato di output finale (JSON/CSV), directory di output e pattern per i nomi dei file. I dati dumpati vengono salvati direttamente su file dal dumper GDB, con la creazione di un file JSON intermedio che viene poi potenzialmente convertito in CSV o rinominato in base alle impostazioni del profilo. * Molteplici "azioni" di debug, ognuna specificando un breakpoint, variabili da estrarre, formato di output finale (JSON/CSV), directory di output e pattern per i nomi dei file.
* **Analisi dei Simboli:** Analizza il tuo eseguibile compilato (usando l'Interfaccia Macchina di GDB) per estrarre informazioni su funzioni, variabili globali, tipi definiti dall'utente e file sorgente. Questi dati aiutano nella configurazione delle azioni di debug. * **Analisi dei Simboli:** Analizza il tuo eseguibile compilato per estrarre informazioni su funzioni, variabili globali, tipi definiti dall'utente e file sorgente. Questi dati aiutano nella configurazione delle azioni di debug.
* **Ispezione Live dello Scope:** Durante la configurazione di un'azione, lo strumento può interrogare GDB in tempo reale per elencare le variabili (locali e argomenti) disponibili a un breakpoint specificato, consentendo una selezione precisa. * **Ispezione Live dello Scope:** Durante la configurazione di un'azione, lo strumento può interrogare GDB in tempo reale per elencare le variabili (locali e argomenti) disponibili a un breakpoint specificato, consentendo una selezione precisa.
* **Ambiente Configurabile:** Imposta i percorsi per GDB, lo script dumper Python personalizzato, vari timeout per le operazioni GDB e opzioni di comportamento del dumper. * **Ambiente Configurabile:** Imposta i percorsi per GDB, lo script dumper Python personalizzato e vari timeout per le operazioni di GDB.
* **Output Flessibile:** Salva i dati dumpati in formati JSON o CSV con nomi di file personalizzabili utilizzando placeholder per una migliore organizzazione. JSON è sempre il formato di dump iniziale da GDB, che può poi essere automaticamente convertito in CSV se specificato in un profilo. * **Output Flessibile:** Salva i dati estratti in formati JSON o CSV con nomi di file personalizzabili utilizzando placeholder per una migliore organizzazione.
* **Logging GUI:** Visualizza i log dell'applicazione e l'output grezzo di GDB direttamente nell'interfaccia. * **Logging nella GUI:** Visualizza i log dell'applicazione e l'output grezzo di GDB direttamente nell'interfaccia.
--- ---
### 2. Requisiti di Sistema e Configurazione dell'Ambiente ### 2. Requisiti di Sistema e Configurazione
**2.1 Sistemi Operativi Supportati** **2.1 Sistemi Operativi Supportati**
* **Windows:** Piattaforma primaria di sviluppo e test grazie all'uso della libreria `pexpect` per il controllo del processo GDB. * **Windows (Primario):** L'applicazione è sviluppata e testata principalmente su Windows. Utilizza il backend compatibile con Windows di `pexpect` (`PopenSpawn`) per un controllo robusto del processo.
* **Linux/macOS:** GDB stesso è multipiattaforma. La logica di interazione con GDB potrebbe richiedere un adattamento per `pexpect` su sistemi Unix-like per una piena compatibilità (questo adattamento non è attualmente parte del codice fornito). * **Linux/macOS (Sperimentale):** L'applicazione dovrebbe essere compatibile con sistemi Unix-like poiché `pexpect` è multipiattaforma.
**2.2 Python** **2.2 Python**
* Python 3.7 o successivo è raccomandato (testato con versioni fino a 3.13). * Python 3.7 o successivo è raccomandato.
**2.3 Librerie Python Richieste** **2.3 Librerie Python Richieste**
Sarà necessario installare le seguenti librerie Python. Tipicamente si possono installare usando pip: Sarà necessario installare le seguenti librerie Python. Puoi installarle usando pip:
`pip install pexpect appdirs` `pip install pexpect appdirs`
* **`pexpect`**: Per controllare GDB come processo figlio su Windows. * **`pexpect`**: Per controllare GDB come processo figlio.
* **`appdirs`**: Utilizzato per determinare directory di configurazione e dati utente indipendenti dalla piattaforma. * **`appdirs`**: Utilizzato per determinare directory di configurazione e dati utente indipendenti dalla piattaforma (sebbene la configurazione principale sia ora salvata in modo relativo all'applicazione).
* **Tkinter**: Solitamente inclusa nelle installazioni Python standard e utilizzata per la GUI. Non è tipicamente richiesta un'installazione separata. * **Tkinter**: Inclusa nelle installazioni standard di Python e utilizzata per la GUI.
**2.4 Installazione di GDB** **2.4 Installazione di GDB**
* È richiesta un'installazione funzionante di GNU Debugger (GDB). * È richiesta un'installazione funzionante di GNU Debugger (GDB).
* Assicurarsi che GDB sia: * Assicurati che GDB sia aggiunto alla variabile d'ambiente `PATH` del tuo sistema o fornisci il percorso completo all'eseguibile di GDB nella configurazione dell'applicazione.
* Aggiunto alla variabile d'ambiente `PATH` del sistema. * Versioni di GDB 8.x e successive sono raccomandate per il miglior supporto allo scripting Python.
* Oppure, fornire il percorso completo all'eseguibile di GDB nella finestra di configurazione dell'applicazione.
* Versioni di GDB 8.x e successive sono generalmente raccomandate per un migliore supporto allo scripting Python.
**2.5 Compilazione dell'Applicazione Target C/C++** **2.5 Compilazione della Tua Applicazione Target C/C++**
* L'applicazione C/C++ **deve essere compilata con i simboli di debug**. * La tua applicazione C/C++ **deve essere compilata con i simboli di debug**.
* Per GCC/G++ o Clang, si usa il flag `-g`: `g++ -g -o mioprogramma mioprogramma.cpp`. * Per GCC/G++ o Clang, usa il flag `-g`: `g++ -g -o mioprogramma mioprogramma.cpp`.
* Evitare livelli di ottimizzazione elevati (es., `-O2`, `-O3`) se interferiscono con il debug. Considerare `-Og` (ottimizza per l'esperienza di debug). * Evita alti livelli di ottimizzazione (es. `-O2`, `-O3`) se interferiscono con il debug. Considera l'uso di `-Og` (ottimizza per l'esperienza di debug).
**2.6 Installazione dello Strumento (Cpp-Python GDB Debug Helper)** ---
Attualmente, il software è progettato per essere eseguito dal suo codice sorgente: ### 3. Installazione ed Esecuzione
1. Assicurarsi che tutti i prerequisiti siano soddisfatti. **3.1 Esecuzione da Codice Sorgente**
2. Scaricare o clonare il codice sorgente.
3. Navigare nella directory radice del progetto (es., `cpp_python_debug`). 1. Assicurati che tutti i prerequisiti della Sezione 2 siano soddisfatti.
4. Eseguire lo script principale usando Python: 2. Scarica o clona il repository del codice sorgente.
3. Naviga nella directory radice del progetto (`cpp_python_debug`).
4. Esegui lo script principale come un modulo:
`python -m cpp_python_debug` `python -m cpp_python_debug`
--- **3.2 Esecuzione della Versione Compilata (`--onedir`)**
### 3. Guida Rapida L'applicazione può essere impacchettata in una cartella di distribuzione usando PyInstaller.
**3.1 Avvio dell'Applicazione** 1. Decomprimi o copia la cartella di distribuzione (es. `cpp_python_debug`) nella posizione desiderata. Questa cartella è auto-contenuta.
2. All'interno della cartella, trova ed esegui l'eseguibile principale (es. `cpp_python_debug.exe`).
1. Soddisfare i "Requisiti di Sistema e Configurazione dell'Ambiente". 3. Tutti i file generati dall'applicazione (configurazioni, log, dump) verranno creati all'interno di questa cartella, rendendola completamente portabile.
2. Navigare nella directory radice del codice sorgente.
3. Eseguire: `python -m cpp_python_debug`.
**3.2 Configurazione Iniziale (Percorso GDB)**
1. Al primo avvio, o se GDB non viene trovato, andare su **Options > Configure Application...**.
2. Nella tab **Paths & Directories**, per "GDB Executable Path", cliccare **Browse...** e selezionare l'eseguibile di GDB.
3. Cliccare **Save**. L'area "Critical Configuration Status" dovrebbe mostrare "GDB: ... (OK)".
**(Fortemente Raccomandato) Configurare il Percorso dello Script Dumper:**
* Lo script Python personalizzato (`gdb_dumper.py`, nella sottodirectory `core`) abilita il dumping JSON avanzato ed è essenziale affinché l'esecuzione automatizzata dei profili salvi i dati su file in modo efficace.
* In **Options > Configure Application... > Paths & Directories**, per "GDB Python Dumper Script Path", cliccare **Browse...** e navigare a questo file `gdb_dumper.py`.
* Cliccare **Save**.
**3.3 La Tua Prima Sessione di Debug Manuale**
1. **Seleziona la Tab "Manual Debug".**
2. **Target Executable:** Clicca **Browse...** e seleziona il tuo eseguibile C/C++ compilato con simboli di debug.
3. **Program Parameters (Opzionale):** Inserisci gli argomenti da riga di comando se necessari.
4. **Breakpoint Location:** Inserisci un breakpoint (es., `main`, `miofile.cpp:42`).
5. **Variable/Expression to Dump:** Inserisci la variabile/espressione da ispezionare (es., `miaVarLocale`).
6. **Start GDB:** Clicca **1. Start GDB**. "GDB Raw Output" mostra i messaggi di avvio. La Status Bar indica "GDB session active."
7. **Set Breakpoint:** Clicca **2. Set Breakpoint**. "GDB Raw Output" mostra la conferma.
8. **Run Program:** Clicca **3. Run Program**. Il programma si esegue fino al breakpoint. Il pulsante cambia in "3. Continue".
9. **Dump Variable:**
* **Azione:** A un breakpoint, clicca **4. Dump Variable**. GDB (tramite lo script dumper) valuta l'espressione, la serializza in JSON e **la salva in un file `.gdbdump.json` temporaneo** in una directory dedicata ai dump manuali. La GUI riceve un messaggio di stato dal dumper.
* **Output:**
* "GDB Raw Output": Mostra la comunicazione con lo script dumper e lo stato JSON che restituisce.
* "Parsed JSON/Status Output": Mostra lo **stato JSON ricevuto dallo script dumper**, che include informazioni come successo/fallimento, il percorso del file JSON temporaneo creato, ed eventuali messaggi di errore.
* **Stato Pulsanti:** I pulsanti "Save as JSON", "Save as CSV", e "Open Dumps Folder" diventano attivi se il file di dump temporaneo è stato creato con successo.
10. **Continue/Stop:** Usa **3. Continue** o **Stop GDB**.
11. **Salvataggio Dati:** Dopo un dump, clicca **Save as JSON** o **Save as CSV**. Questo legge il file `.gdbdump.json` temporaneo, lo converte/salva nella posizione e formato finali scelti, e tipicamente elimina il file temporaneo dopo un'operazione "Save As..." riuscita. Clicca **Open Dumps Folder** per visualizzare la directory dove sono memorizzati i dump manuali temporanei.
Congratulazioni! Hai completato la tua prima sessione di debug manuale.
--- ---
### 4. Panoramica dell'Interfaccia Utente (Finestra Principale) ### 4. Struttura di File e Directory
**(Uno screenshot della finestra principale con aree annotate sarebbe ideale qui)** L'applicazione crea e gestisce diversi file e directory. Comprendere questa struttura è fondamentale per trovare le tue configurazioni e i tuoi output.
**4.1 Barra dei Menu** * **Esecuzione da sorgente:** Tutti i percorsi sono relativi alla directory radice del progetto.
* **Esecuzione da versione compilata:** Tutti i percorsi sono relativi alla cartella che contiene l'eseguibile principale.
* **Options:** "Configure Application...", "Exit". - **`config/`**
* **Profiles:** "Manage Profiles...". - **`gdb_debug_gui_settings.v2.json`**: Il file di configurazione principale. Memorizza tutte le tue impostazioni, inclusi percorsi, timeout e tutti i tuoi profili di debug. Il file è in formato JSON.
- **`logs/`**
**4.2 Area Stato Configurazione Critica** - **`cpppythondebughelper_gui.log`**: Il file di log principale per l'applicazione GUI stessa. Utile per risolvere problemi della GUI.
- **`gdb_dumper_script_internal.log`**: Un file di log dedicato per lo script `gdb_dumper.py`. È estremamente utile per debuggare problemi che si verificano *all'interno* di GDB durante un dump di variabili.
Mostra lo stato dell'eseguibile GDB e dello Script Dumper. Include un pulsante "Configure...". - **`manual_gdb_dumps/`**: La directory in cui vengono memorizzati i file di dump temporanei (`.gdbdump.json`) dalla scheda "Manual Debug" prima che tu li salvi in una posizione finale.
- **`gdb_dumper_diagnostics/`**: (Opzionale) Se abiliti "Enable Diagnostic JSON Dump to File" nelle impostazioni, questa cartella conterrà una copia JSON grezza di ogni singolo dump di variabile, utile per il debug dello script dumper stesso.
**4.3 Pannello Modalità (Tab)** - **`<Profile Output Directory>`**: La directory che specifichi nell'azione di un profilo è dove verranno salvati i file di dump finali (JSON o CSV) per l'esecuzione di quel profilo. L'applicazione creerà qui una sottocartella specifica per l'esecuzione (es. `MieiDump/MioProfilo_20231027_143000/`).
* **Tab Manual Debug:** (Vedi Sezione 6) Per il debugging interattivo.
* **Tab Automated Profile Execution:** (Vedi Sezione 9) Per eseguire sequenze di debug preconfigurate.
**4.4 Area Output e Log (Tab)**
* **Tab GDB Raw Output:** Output testuale grezzo dal processo GDB.
* **Tab Parsed JSON/Status Output:** Mostra JSON formattato (meno comune ora per i profili) o il **payload di stato JSON** ricevuto dallo script dumper GDB (per entrambe le modalità Manuale e Profilo).
* **Tab Application Log:** Messaggi di log dall'applicazione GUI stessa.
**4.5 Barra di Stato**
Brevi messaggi sullo stato corrente dell'applicazione o sull'ultima operazione.
--- ---
### 5. Finestra di Configurazione (`Options > Configure Application...`) ### 5. Guida Rapida
**(Uno screenshot della Finestra di Configurazione con le tab sarebbe utile qui)** 1. **Avvia l'Applicazione** come descritto nella Sezione 3.
2. **Configurazione Iniziale:** Al primo avvio, vai su **Options > Configure Application...**.
Organizzata in tab: * Nella scheda **Paths & Directories**, vai al tuo eseguibile GDB.
* (Fortemente Raccomandato) Vai anche allo script `gdb_dumper.py` situato nella sottodirectory `core` del codice sorgente (o `cpp_python_debug/core` nella versione compilata).
**5.1 Tab Paths & Directories** * Clicca **Save**.
3. **Esegui una Sessione di Debug Manuale:**
* **GDB Executable Path:** Percorso completo a GDB. *Cruciale.* * Vai alla scheda **Manual Debug**.
* **GDB Python Dumper Script Path (Optional):** Percorso completo a `gdb_dumper.py`. *Fortemente raccomandato per la piena funzionalità.* * Seleziona il tuo eseguibile C/C++ compilato.
* Inserisci un breakpoint (es. `main`).
**5.2 Tab Timeouts (seconds)** * Clicca **1. Start GDB**.
* Clicca **2. Set Breakpoint**.
Configura i timeout per le operazioni GDB (tutti in secondi): * Clicca **3. Run Program**.
* Quando il breakpoint viene raggiunto, inserisci un nome di variabile e clicca **4. Dump Variable**.
* **GDB Start:** (Default: 30s) * Osserva la scheda "Parsed JSON/Status Output". Mostrerà un messaggio di stato che conferma il dump e il percorso di un file temporaneo `.gdbdump.json`.
* **GDB Command:** (Default: 30s) * I pulsanti **Save as JSON** e **Save as CSV** diventeranno attivi. Usali per salvare i dati catturati in una posizione permanente.
* **Program Run/Continue:** (Default: 120s)
* **Dump Variable:** (Default: 60s)
* **Kill Program:** (Default: 20s)
* **GDB Quit:** (Default: 10s)
**5.3 Tab Dumper Options**
Controlla il comportamento di `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) Se spuntato, salva una copia JSON grezza *aggiuntiva* di ogni dump per il debug dello script dumper.
* **Diagnostic JSON Output Directory:** Cartella per questi dump diagnostici. (Default: una sottocartella `gdb_dumper_diag_dumps` nella home dell'utente).
**5.4 Salvataggio e Annullamento**
* **Save Button:** Valida, applica, salva tutte le impostazioni nel file di configurazione e chiude.
* **Cancel Button / 'X' della Finestra:** Scarta le modifiche e chiude.
--- ---
### 6. Modalità Debug Manuale ### 6. Panoramica dell'Interfaccia Utente
**(Uno screenshot della tab Manual Debug sarebbe utile)** * **Barra dei Menu**: Accedi a **Options** (Configurazione) e **Profiles** (Gestore Profili).
* **Stato della Configurazione Critica**: Mostra se GDB e lo script dumper sono configurati correttamente.
**6.1 Impostazione Eseguibile Target e Parametri** * **Pannello Modalità (Schede)**: Passa tra **Manual Debug** e **Automated Profile Execution**.
Campi per "Target Executable" (con Browse...) e "Program Parameters". * **Area di Output e Log (Schede)**:
* `GDB Raw Output`: Comunicazione testuale grezza con il processo GDB.
**6.2 Impostazione Posizione Breakpoint** * `Parsed JSON/Status Output`: Mostra il payload di stato ricevuto dallo script dumper o formatta JSON semplici.
Campo per il breakpoint (es., `main`, `file.cpp:123`). * `Application Log`: Messaggi di log relativi alla GUI.
* **Barra di Stato**: Brevi messaggi sullo stato corrente dell'applicazione.
**6.3 Impostazione Variabile/Espressione da Dumpare**
Campo per la variabile o espressione GDB.
**6.4 Pulsanti di Controllo Sessione**
1. **1. Start GDB**
2. **2. Set Breakpoint**
3. **3. Run Program / 3. Continue**
4. **4. Dump Variable:** (Cambiamento chiave) Comanda a GDB di dumpare la variabile e **salvarla in un file `.gdbdump.json` temporaneo**. La GUI riceve un messaggio di stato.
5. **Stop GDB**
**6.5 Interpretazione GDB Raw Output**
Mostra la comunicazione con GDB, incluso lo stato JSON dal dumper.
**6.6 Interpretazione Parsed JSON/Status Output**
Mostra il **payload di stato JSON** dallo script dumper:
* `status`: "success" o "error".
* `variable_dumped`: La variabile target.
* `filepath_written`: Percorso al file `.gdbdump.json` temporaneo creato.
* `message`, `details`: Conferma o informazioni sull'errore.
**6.7 Salvataggio Dati Dumpati (JSON/CSV) & Gestione Dump**
Dopo un dump riuscito (file temporaneo creato):
* **Pulsanti Save as JSON/CSV:** Abilitati. Aprono una finestra "Salva con nome". Leggono il file `.gdbdump.json` temporaneo, quindi lo convertono/salvano nel file finale scelto. Il file temporaneo viene tipicamente eliminato dopo un'operazione "Salva con nome" riuscita.
* **Pulsante Open Dumps Folder:** Apre la directory dove sono memorizzati i file JSON temporanei dei dump manuali (configurata tramite `manual_dumps_output_path`, solitamente nell'area di configurazione dell'applicazione).
--- ---
### 7. Gestore Profili (`Profiles > Manage Profiles...`) ### 7. Finestra di Configurazione (`Options > Configure Application...`)
**(Screenshot del Gestore Profili raccomandato)** Qui puoi impostare le impostazioni globali dell'applicazione.
**7.1 Panoramica Finestra Gestore Profili** * **Scheda Paths & Directories**: Imposta i percorsi assoluti a `gdb.exe` e `gdb_dumper.py`.
Riquadro sinistro per la lista dei profili e controlli (New, Duplicate, Delete). Riquadro destro per i dettagli del profilo selezionato, analisi dei simboli e lista delle azioni. Pulsanti in basso per "Save All Changes" e "Close". * **Scheda Timeouts**: Configura i timeout (in secondi) per varie operazioni di GDB per evitare che l'applicazione si blocchi.
* **Scheda Dumper Options**: Controlla il comportamento dello script `gdb_dumper.py` (es. profondità di ricorsione, numero massimo di elementi degli array). Puoi anche abilitare i dump diagnostici qui.
**7.2 Gestione Profili**
Seleziona, crea nuovi, duplica o elimina profili. "Save All Changes" persiste tutto.
**7.3 Modifica Dettagli Profilo**
Modifica "Profile Name" (univoco), "Target Executable", e "Program Parameters".
**7.4 Analisi dei Simboli**
Mostra lo stato dell'analisi dei simboli memorizzata rispetto al target corrente nel form (checksum, timestamp).
* **Pulsante Analyse Target Symbols:** Avvia una nuova analisi per l'eseguibile corrente, memorizzando i risultati nel profilo selezionato (in memoria; richiede "Save All Changes" per persistere).
* **Pulsanti View...:** Sfoglia liste di funzioni, globali, tipi e sorgenti analizzati.
**7.5 Gestione Azioni di Debug**
Lista delle azioni per il profilo. Pulsanti "Add...", "Edit...", "Remove" aprono l'Editor Azioni (Sezione 8).
--- ---
### 8. Finestra Editor Azioni (dal Gestore Profili) ### 8. Modalità Debug Manuale in Dettaglio
**(Screenshot dell'Editor Azioni raccomandato)** Questa modalità fornisce un'interfaccia passo-passo per una singola sessione di debug. Il flusso di lavoro chiave da notare è:
Definisce una singola azione di debug. * Quando clicchi su **4. Dump Variable**, lo script `gdb_dumper.py` salva lo stato della variabile direttamente in un file temporaneo (es. nella cartella `logs/manual_gdb_dumps/`).
* La GUI riceve solo un **messaggio di stato** che conferma questa azione e il percorso del file temporaneo.
**8.1 Posizione Breakpoint** * Devi quindi usare i pulsanti **Save as...** per copiare e convertire questi dati temporanei in una posizione permanente.
Campo e pulsanti di assistenza "Funcs..." / "Files..." (usano analisi simboli o query GDB live).
**8.2 Variabili da Dumpare**
Area di testo scrollabile (una per riga). Pulsanti "Globals..." e "Scope Vars..." assistono la selezione (Scope Vars esegue un'ispezione GDB live).
**8.3 Formato Output**
Combobox: "json" o "csv".
**8.4 Directory di Output**
Directory per i file di output di questa azione. Una sottocartella specifica per l'esecuzione viene creata qui.
**8.5 Pattern Nome File**
Pattern per i nomi dei file di output.
* Placeholder Disponibili: `{profile_name}`, `{app_name}`, `{breakpoint}`, `{variable}`, `{timestamp}`.
* L'estensione finale (`.json` o `.csv`) viene aggiunta dall'applicazione in base alla selezione "Output Format". Lo script dumper GDB creerà prima un file intermedio con estensione `.gdbdump.json`.
* Pattern Esempio: `dump_{app_name}_{breakpoint}_{variable}_{timestamp}`
* Questo pattern definisce il nome **base** del file.
**8.6 Opzione "Continue execution after dump"**
Checkbox per controllare il comportamento di GDB dopo l'azione.
**8.7 Opzione "Dump variables every time breakpoint is hit"**
* **Spuntato (Default):** Le variabili vengono dumpate ogni volta che questo breakpoint viene incontrato.
* **Non Spuntato:** Le variabili vengono dumpate solo la prima volta che questo breakpoint viene raggiunto durante un'esecuzione del profilo per questa specifica azione.
**8.8 Salvataggio/Annullamento Azione**
"OK" salva l'azione nel profilo. "Cancel" scarta le modifiche.
--- ---
### 9. Modalità Esecuzione Automatizzata Profili ### 9. Gestore Profili ed Esecuzione Automatizzata
**(Screenshot della tab Esecuzione Automatizzata raccomandato)** Questa è la funzionalità principale per l'automazione del debugging.
**9.1 Selezione di un Profilo** **9.1 Gestore Profili (`Profiles > Manage Profiles...`)**
Dropdown elenca i profili disponibili.
**9.2 Esecuzione del Profilo** Questa finestra è il centro per creare e gestire i tuoi scenari di debug automatizzati. Un profilo è composto da:
Pulsante "Run Profile" avvia l'esecuzione. La GUI si aggiorna. Un `ProfileExecutor` viene eseguito in un thread separato. 1. **Dettagli Profilo**: Nome, eseguibile target e parametri del programma.
* GDB si avvia, il dumper viene caricato, i breakpoint vengono impostati. 2. **Dati di Analisi Simboli**: Puoi eseguire un'analisi sull'eseguibile target. Lo strumento usa GDB per trovare tutte le funzioni, variabili globali, ecc., e memorizza queste informazioni nel profilo. Questo ti aiuta a configurare le azioni in modo accurato.
* Al raggiungimento di un breakpoint: 3. **Azioni**: Un elenco di azioni di debug.
* Il Dumper salva JSON grezzo in un file intermedio (es., `...azione.gdbdump.json`).
* Se il formato finale è JSON, il file intermedio viene rinominato.
* Se il formato finale è CSV, il JSON intermedio viene letto, convertito in CSV, salvato, e il JSON intermedio viene solitamente eliminato.
* "Produced Files Log" viene aggiornato.
**9.3 Monitoraggio Stato Esecuzione e Barra di Progresso** **9.2 Editor di Azioni**
Etichetta di stato e barra di progresso mostrano l'avanzamento.
**9.4 Interruzione di un Profilo in Esecuzione** Ogni azione definisce un'attività specifica da eseguire a un breakpoint.
Pulsante "Stop Profile" tenta di terminare gradualmente. * **Posizione Breakpoint**: Dove GDB dovrebbe fermarsi.
* **Variabili da Dumpare**: Quali variabili ispezionare a quel breakpoint.
* **Formato Output**: Formato finale (JSON o CSV).
* **Directory di Output**: La directory di base per i file di output.
* **Pattern Nome File**: Un modello per nominare i file di output.
* **Flusso di Esecuzione**: Se continuare dopo il dump e se eseguire il dump ad ogni hit o solo al primo.
**9.5 Interpretazione del "Produced Files Log"** **9.3 Flusso di Esecuzione Automatizzata**
Vista ad albero con: Time, Breakpoint Spec, Variable, File Produced (nome finale), Status, Details, e potenzialmente "Raw GDB Dump File" (percorso al `.gdbdump.json` se conservato a causa di un errore).
**9.6 Apertura della Cartella di Output** 1. Seleziona un profilo dal menu a tendina nella scheda "Automated Profile Execution".
Pulsante "Open Profile Output Folder" apre la directory di output principale per l'ultima esecuzione del profilo completata. 2. Clicca **Run Profile**.
3. Il `ProfileExecutor` avvia GDB ed esegue il programma.
4. Quando un breakpoint viene raggiunto, l'azione corrispondente viene attivata.
5. Viene invocato lo script `gdb_dumper.py`, che estrae le variabili specificate in file intermedi `.gdbdump.json`.
6. L'applicazione principale elabora quindi questi file intermedi:
* Se il formato desiderato è **JSON**, rinomina il file secondo il pattern.
* Se il formato desiderato è **CSV**, legge il JSON, lo converte, salva il nuovo file `.csv` ed elimina il JSON intermedio.
7. Il "Produced Files Log" viene aggiornato in tempo reale con lo stato di ogni file creato.
--- ---
### 10. Risoluzione Problemi / FAQ ### 10. Risoluzione Problemi / FAQ
**D: GDB non trovato / Problemi con lo script Dumper / Nessun simbolo di debug / `_gdb_tool_error` nell'output JSON.** **D: GDB non trovato / Problemi con lo script Dumper / Nessun simbolo di debug.**
**R:** (Stessi consigli di prima, enfatizzando il controllo di `gdb_dumper_debug.log` per problemi del dumper). **R:** Assicurati che i percorsi configurati in **Options > Configure Application...** siano corretti. Controlla le schede `Application Log` e `GDB Raw Output` per messaggi di errore specifici da GDB o dallo script dumper.
**D: Esecuzione del profilo fallisce, si blocca, o i breakpoint non vengono raggiunti.** **D: L'applicazione si blocca o va in timeout.**
**R:** (Stessi consigli di prima, verificare percorsi, BP, parametri, timeout). **R:** Il tuo programma target potrebbe richiedere molto tempo. Prova ad aumentare i timeout nella Finestra di Configurazione.
**D: La GUI non risponde.** **D: `gdb_dumper.py` sta fallendo. Come posso debuggarlo?**
**R:** (Stessi consigli di prima, controllare timeout, console/Application Log per errori). **A:**
1. Controlla il file `logs/gdb_dumper_script_internal.log`. È il primo posto dove cercare errori che si verificano all'interno del dumper.
**D: Come posso ottenere maggiori informazioni di debug da `gdb_dumper.py`?** 2. Per ancora più dettagli, abilita "**Enable Diagnostic JSON Dump to File**" nelle Opzioni Dumper. Questo salverà una copia JSON grezza di ogni dump nella directory `logs/gdb_dumper_diagnostics/`, permettendoti di vedere esattamente cosa sta producendo il dumper.
**R:**
1. Controlla `gdb_dumper_debug.log`. La sua posizione è loggata da `gdb_dumper.py` all'avvio (vedi GDB Raw Output o il file di log stesso, solitamente in `~` o accanto a `gdb_dumper.py`).
2. L'applicazione GUI principale (`__main__.py`) elimina questo log all'avvio per un log di sessione pulito.
3. Per output ancora più verboso per lo sviluppo dello script dumper, puoi abilitare l'opzione "**Enable Diagnostic JSON Dump to File**" in **Options > Configure Application... > Dumper Options**. Questo salva una copia JSON grezza *aggiuntiva* di ogni dump GDB nella "Diagnostic JSON Output Directory".
--- ---
### 11. Casi d'Uso / Esempi ### 11. Casi d'Uso / Esempi
(Contenuto sostanzialmente invariato, ma rinforzare che i file di output sono ora creati direttamente in base alle impostazioni del profilo)
**11.1 Dumpare un `std::vector`** **11.1 Dumpare un `std::vector`**
* ...Quando il profilo viene eseguito, file come `vector_dumps/NomeProfilo_timestamp/processVector_myVector_timestamp.json` (o `.csv`) verranno creati.
* **Scenario:** Vuoi ispezionare il contenuto di un `std::vector<MyObject> myVector` ogni volta che viene modificato all'interno di una funzione `processVector`.
* **Setup Profilo:**
* **Azione 1:** Breakpoint all'inizio di `processVector`.
* **Azione 2:** Breakpoint alla fine di `processVector`.
* Entrambe le azioni estraggono la variabile `myVector`.
* **Risultato:** Durante l'esecuzione del profilo, verranno creati file come `dump_vettori/MioProfilo_timestamp/processVector_myVector_timestamp.json` (o `.csv`), permettendoti di vedere lo stato del vettore prima e dopo l'elaborazione.
**11.2 Tracciare una variabile globale** **11.2 Tracciare una variabile globale**
* ...File di output per `globalCounter` verranno generati per ogni posizione di breakpoint.
**11.3 Snapshot di strutture dati complesse** * **Scenario:** Devi monitorare come una variabile globale `globalCounter` cambia in punti chiave della tua applicazione.
* ...Una serie di file JSON come `app_state_snapshots/NomeProfilo_timestamp/longRunningTask.cpp_75_appState_timestamp.json` verrà creata. * **Setup Profilo:** Crea più azioni, ognuna con un diverso breakpoint (es. `func_A`, `func_B`, `main.cpp:150`), ma tutte che estraggono la stessa variabile `globalCounter`.
* **Risultato:** Otterrai una serie di file con timestamp, uno per ogni volta che il contatore è stato estratto, permettendoti di tracciare il suo valore attraverso il flusso di esecuzione del programma.
**11.3 Snapshot di dati complessi**
* **Scenario:** La tua applicazione ha un grande oggetto di configurazione o di stato (`ApplicationState appState`) e vuoi fare uno snapshot completo di esso in un punto critico, come poco prima di un'attività di lunga durata.
* **Setup Profilo:** Un'azione a `longRunningTask.cpp:75` che estrae l'oggetto `appState`.
* **Risultato:** Verrà creato un file JSON dettagliato come `snapshot_stato/MioProfilo_timestamp/longRunningTask.cpp_75_appState_timestamp.json`, contenente una rappresentazione completa e annidata dello stato della tua applicazione.
--- ---
### 12. Avanzato: Lo Script `gdb_dumper.py` ### 12. Avanzato: Lo Script `gdb_dumper.py`
**12.1 Ruolo e Interazione con GDB** **12.1 Ruolo e Interazione con GDB**
* ...
* **Logica di Serializzazione:**
1. Usa `gdb.parse_and_eval()` per ottenere la variabile.
2. Attraversa il `gdb.Value`, applicando le "Dumper Options".
3. Costruisce una rappresentazione Python.
4. Serializza in una stringa JSON.
5. **Se un `target_output_filepath` è fornito dall'applicazione principale (standard per entrambe le modalità Manuale e Profilo), il dumper salva la stringa JSON completa direttamente in questo file specificato (tipicamente con estensione `.gdbdump.json`). Quindi stampa un piccolo payload di stato JSON (indicante successo/fallimento e il percorso scritto) sull'output standard di GDB, racchiuso tra delimitatori.**
* **Elaborazione GUI:**
* La GUI cattura l'output di GDB, estrae il **payload di stato JSON** tra i delimitatori e lo analizza. Questo payload informa la GUI sul successo del dump lato GDB e sulla posizione del file JSON grezzo creato dal dumper.
* In **Modalità Manuale**, questo file JSON grezzo viene quindi utilizzato se l'utente sceglie "Save as JSON" o "Save as CSV" (e viene eliminato dopo un salvataggio riuscito).
* In **Modalità Profilo**, se l'azione del profilo specificava il formato "csv", la GUI legge questo file JSON grezzo, lo converte in CSV, lo salva come output finale e tipicamente elimina il JSON grezzo. Se era specificato "json", il file JSON grezzo viene solitamente rinominato nel nome file finale.
**12.2 File di Log del Dumper (`gdb_dumper_debug.log`)** Lo script `gdb_dumper.py` è il cuore del motore di estrazione dati. Viene eseguito all'interno del processo GDB e ha accesso all'API Python di GDB.
(Contenuto per lo più invariato, enfatizzando il suo ruolo per problemi interni al dumper).
* **Logica di Serializzazione:**
1. Usa `gdb.parse_and_eval()` per ottenere un oggetto `gdb.Value` che rappresenta una variabile C++.
2. Attraversa ricorsivamente questo oggetto, rispettando le "Opzioni Dumper" (profondità massima, ecc.).
3. Costruisce una rappresentazione Python (dizionario/lista) dei dati C++.
4. Serializza questo oggetto Python in una stringa JSON.
5. Salva la stringa JSON completa direttamente in un file intermedio specificato (es. `...nome.gdbdump.json`).
6. Stampa un piccolo **payload di stato JSON** (che indica successo/fallimento e il percorso scritto) sull'output standard di GDB, racchiuso tra delimitatori speciali.
* **Elaborazione della GUI:** La GUI principale cattura questo payload di stato per capire l'esito del dump. In **Modalità Profilo**, elabora quindi il file intermedio per creare l'output finale specificato dall'utente (rinominando per JSON, convertendo per CSV).
**12.2 File di Log del Dumper (`gdb_dumper_script_internal.log`)**
Questo file di log, situato nella directory principale `logs`, è prezioso per il debug dello script dumper stesso. Registra passaggi interni, configurazioni ed errori che si verificano all'interno dell'ambiente GDB, che non sono visibili nel log principale dell'applicazione.
--- ---
### 13. Appendice (Opzionale) ### 13. Appendice: Placeholder per Nomi File
**13.1 Riepilogo Placeholder Nomi File** I seguenti placeholder possono essere usati nel campo "Filename Pattern" (nell'Editor Azioni) per costruire il nome base dei tuoi file di output. L'estensione finale del file (`.json` o `.csv`) è gestita automaticamente.
I seguenti placeholder possono essere usati nel campo "Filename Pattern" (nell'Editor Azioni) per costruire il **nome base** dei tuoi file di output. L'estensione appropriata (`.json` o `.csv` per il file finale, e `.gdbdump.json` per il dump intermedio di GDB) sarà gestita dall'applicazione. * `{profile_name}`: Il nome del profilo (sanificato per la sicurezza del filesystem).
* `{app_name}`: Il nome base dell'eseguibile target.
* `{profile_name}`: Il nome del profilo (sanificato). * `{breakpoint}`: La stringa della posizione del breakpoint (sanificata).
* `{app_name}`: Nome base dell'eseguibile target. * `{variable}`: Il nome della variabile/espressione estratta (sanificato).
* `{breakpoint}`: Stringa della posizione del breakpoint (sanificata). * `{timestamp}`: Un timestamp dettagliato (`ANNO MESE GIORNO_ORA MINUTO SECONDO_ms`).
* `{variable}`: Nome della variabile/espressione (sanificato).
* `{timestamp}`: Timestamp (`ANNO MESE GIORNO_ORA MINUTO SECONDO_MILLISECONDO`).
**Pattern Esempio:** `dump_{app_name}_{breakpoint}_{variable}_{timestamp}` **Pattern Esempio:** `dump_{app_name}_{breakpoint}_{variable}_{timestamp}`
**Output Finale Esempio (se JSON):** `dump_mioprogramma_main_miaVar_20231027_143005_123.json` **Output Finale Esempio (se JSON):** `dump_mioprogramma_main_miaVar_20231027_143005_123.json`

BIN
doc/Italian-manual.pdf
View File

Binary file not shown.