update manual
This commit is contained in:
VALLONGOL
parent
107eb6749c
commit
a716ca7e96
@ -6,10 +6,10 @@
|
||||
import re
|
||||
|
||||
# --- Version Data (Generated) ---
|
||||
__version__ = "v.0.0.0.28-0-g9035dbc-dirty"
|
||||
GIT_COMMIT_HASH = "9035dbc5286fd8a018822a906a293ce3fd11fe33"
|
||||
__version__ = "v.0.0.0.29-0-g675a032-dirty"
|
||||
GIT_COMMIT_HASH = "675a032af46832124bc4f58a855e5595bbcf0432"
|
||||
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
|
||||
|
||||
# --- Default Values (for comparison or fallback) ---
|
||||
|
||||
Binary file not shown.
@ -17,369 +17,282 @@ This tool is primarily aimed at C/C++ developers who use GDB for debugging and w
|
||||
|
||||
**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.
|
||||
* **Interactive Manual Debugging:** Start GDB, set breakpoints, run your target program, and inspect variables.
|
||||
* **Advanced Variable Dumping:** Utilizes a custom GDB Python script to dump the state of C/C++ variables, including complex data structures like classes, structs, pointers, arrays, and `std::string`, into a structured JSON format.
|
||||
* **Automated Debug Profiles:** Create, manage, and execute debug profiles. Each profile can define:
|
||||
* Target executable and program parameters.
|
||||
* Multiple debug "actions", each specifying a breakpoint, variables to dump, final output format (JSON/CSV), output directory, and filename patterns. 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.
|
||||
* Multiple debug "actions", each specifying a breakpoint, variables to dump, final output format (JSON/CSV), output directory, and filename patterns.
|
||||
* **Symbol Analysis:** Analyze your compiled executable to extract information about functions, global variables, user-defined types, and source files. This data aids in configuring debug actions.
|
||||
* **Live Scope Inspection:** When configuring an action, the tool can query GDB live to list variables (locals and arguments) available at a specified breakpoint, allowing for precise selection.
|
||||
* **Configurable Environment:** Set paths for GDB, the custom Python dumper script, 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.
|
||||
* **Configurable Environment:** Set paths for GDB, the custom Python dumper script, and various timeouts for GDB operations.
|
||||
* **Flexible Output:** Save dumped data in JSON or CSV formats with customizable filenames using placeholders for better organization.
|
||||
* **GUI Logging:** View application logs and raw GDB output directly within the interface.
|
||||
|
||||
---
|
||||
|
||||
### 2. System Requirements & Environment Setup
|
||||
### 2. System Requirements & 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).
|
||||
* **Windows (Primary):** The application is primarily developed and tested on Windows. It uses the `pexpect` library's Windows-compatible backend (`PopenSpawn`) for robust process control.
|
||||
* **Linux/macOS (Experimental):** The application should be compatible with Unix-like systems as `pexpect` is cross-platform.
|
||||
|
||||
**2.2 Python**
|
||||
|
||||
* Python 3.7 or newer is recommended (tested with versions up to 3.13).
|
||||
* Python 3.7 or newer is recommended.
|
||||
|
||||
**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`
|
||||
|
||||
* **`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.
|
||||
* **`pexpect`**: For controlling GDB as a child process.
|
||||
* **`appdirs`**: Used for determining platform-independent user configuration and data directories (though the primary configuration is now stored relative to the application).
|
||||
* **Tkinter**: This is included with standard Python installations and is used for the GUI.
|
||||
|
||||
**2.4 GDB Installation**
|
||||
|
||||
* A working installation of the GNU Debugger (GDB) is required.
|
||||
* Ensure that GDB is either:
|
||||
* Added to your system's `PATH` environment variable.
|
||||
* Or, you provide the full path to the GDB executable in the application's configuration window.
|
||||
* GDB versions 8.x and newer are generally recommended for better Python scripting support.
|
||||
* Ensure that GDB is either added to your system's `PATH` environment variable or you provide the full path to the GDB executable in the application's configuration.
|
||||
* GDB versions 8.x and newer are recommended for the best Python scripting support.
|
||||
|
||||
**2.5 Compiling Your C/C++ Target Application**
|
||||
|
||||
* Your C/C++ application **must be compiled with debugging symbols**.
|
||||
* For GCC/G++ or Clang, use the `-g` flag: `g++ -g -o myprogram myprogram.cpp`.
|
||||
* Avoid high levels of optimization (e.g., `-O2`, `-O3`) if they interfere with debugging. Consider `-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.
|
||||
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:
|
||||
**3.1 Running from Source Code**
|
||||
|
||||
1. Ensure all prerequisites from Section 2 are met.
|
||||
2. Download or clone the source code repository.
|
||||
3. Navigate to the root directory of the project (`cpp_python_debug`).
|
||||
4. Run the main script as a module:
|
||||
`python -m cpp_python_debug`
|
||||
|
||||
**3.2 Running the Compiled (`--onedir`) Version**
|
||||
|
||||
The application can be packaged into a distribution folder using PyInstaller.
|
||||
|
||||
1. Unzip or copy the distribution folder (e.g., `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`).
|
||||
3. All files generated by the application (configurations, logs, dumps) will be created inside this folder, making it fully portable.
|
||||
|
||||
---
|
||||
|
||||
### 3. Quick Start Guide
|
||||
### 4. File and Directory Structure
|
||||
|
||||
**3.1 Launching the Application**
|
||||
The application creates and manages several files and directories. Understanding this structure is key to finding your configurations and output.
|
||||
|
||||
1. Meet "System Requirements & Environment Setup".
|
||||
2. Navigate to the project's root directory.
|
||||
3. Execute: `python -m cpp_python_debug`.
|
||||
* **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.
|
||||
|
||||
**3.2 Initial Configuration (GDB Path)**
|
||||
- **`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/`).
|
||||
|
||||
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:**
|
||||
### 5. Quick Start Guide
|
||||
|
||||
* 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`.
|
||||
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.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.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
### 4. User Interface Overview (Main Window)
|
||||
### 6. User Interface Overview
|
||||
|
||||
**(Screenshot of the main window with areas annotated would be ideal here)**
|
||||
|
||||
**4.1 Menu Bar**
|
||||
**6.1 Menu Bar**
|
||||
|
||||
* **Options:** "Configure Application...", "Exit".
|
||||
* **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.
|
||||
|
||||
**4.3 Mode Panel (Tabs)**
|
||||
**6.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.
|
||||
* **Manual Debug Tab:** For interactive, step-by-step debugging.
|
||||
* **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.
|
||||
* **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).
|
||||
* **GDB Raw Output Tab:** Raw text communication with the GDB process.
|
||||
* **Parsed JSON/Status Output Tab:** Displays the status payload received from the GDB dumper script or pretty-prints simple JSON.
|
||||
* **Application Log Tab:** Log messages from the GUI application itself.
|
||||
|
||||
**4.5 Status Bar**
|
||||
**6.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)**
|
||||
### 7. Configuration Window (`Options > Configure Application...`)
|
||||
|
||||
Organized into tabs:
|
||||
|
||||
**5.1 Paths & Directories Tab**
|
||||
**7.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.*
|
||||
* **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)
|
||||
* **GDB Command:** (Default: 30s)
|
||||
* **Program Run/Continue:** (Default: 120s)
|
||||
* **Dump Variable:** (Default: 60s)
|
||||
* **Kill Program:** (Default: 20s)
|
||||
* **GDB Quit:** (Default: 10s)
|
||||
**7.3 Dumper Options Tab**
|
||||
|
||||
**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.
|
||||
Control the behavior of `gdb_dumper.py`: Max Array Elements, Max Recursion Depth, Max String Length, and options for diagnostic logging.
|
||||
|
||||
---
|
||||
|
||||
### 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**
|
||||
Fields for "Target Executable" (with Browse...) and "Program Parameters".
|
||||
**8.1 Workflow**
|
||||
1. **Set Target & Parameters:** Specify the executable and any command-line arguments.
|
||||
2. **Set Breakpoint & Variable:** Define where to stop and what to inspect.
|
||||
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**
|
||||
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).
|
||||
**8.2 Interpreting Output**
|
||||
* **GDB Raw Output:** Shows all communication with GDB, including the status message from the dumper script.
|
||||
* **Parsed JSON/Status Output:** Displays the status payload from the dumper, confirming the action and providing the path to the temporary file.
|
||||
|
||||
---
|
||||
|
||||
### 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**
|
||||
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".
|
||||
**9.1 Profile Manager (`Profiles > Manage Profiles...`)**
|
||||
|
||||
**7.2 Managing Profiles**
|
||||
Select, create new, duplicate, or delete profiles. "Save All Changes" persists everything.
|
||||
This window is the hub for creating and managing your automated debug scenarios. A profile consists of:
|
||||
1. **Profile Details**: Name, target executable, and program parameters.
|
||||
2. **Symbol Analysis Data**: You can run an analysis on the target executable. The tool uses GDB to find all functions, global variables, etc., and stores this information in the profile. This helps you accurately set up actions.
|
||||
3. **Actions**: A list of debug actions.
|
||||
|
||||
**7.3 Editing Profile Details**
|
||||
Edit "Profile Name" (must be unique), "Target Executable", and "Program Parameters".
|
||||
**9.2 Action Editor**
|
||||
|
||||
**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.
|
||||
Each action defines a specific task to be performed at a breakpoint.
|
||||
* **Breakpoint Location**: Where GDB should stop.
|
||||
* **Variables to Dump**: Which variables to inspect.
|
||||
* **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**
|
||||
List of actions for the profile. "Add...", "Edit...", "Remove" buttons open the Action Editor (Section 8).
|
||||
**9.3 Automated Execution Flow**
|
||||
|
||||
---
|
||||
|
||||
### 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.
|
||||
1. Select a profile from the dropdown on the "Automated Profile Execution" tab.
|
||||
2. Click **Run Profile**.
|
||||
3. The `ProfileExecutor` starts GDB and runs the program.
|
||||
4. When a breakpoint is hit, the corresponding action is triggered.
|
||||
5. The `gdb_dumper.py` script is invoked, which dumps the specified variable(s) to intermediate `.gdbdump.json` files.
|
||||
6. The main application then processes these intermediate files:
|
||||
* 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.
|
||||
7. The "Produced Files Log" is updated in real-time with the status of each file created.
|
||||
|
||||
---
|
||||
|
||||
### 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: GDB not found / Dumper script issues / No debugging symbols.**
|
||||
**A:** Ensure your configured paths in **Options > Configure Application...** are correct. Check the `Application Log` and `GDB Raw Output` tabs for specific error messages from GDB or the dumper script.
|
||||
|
||||
**Q: 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: The application hangs or times out.**
|
||||
**A:** Your target program might be taking a long time. Try increasing the timeouts in the Configuration Window.
|
||||
|
||||
**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".
|
||||
1. Check the `logs/gdb_dumper_script_internal.log` file. This is the first place to look for errors happening inside the dumper.
|
||||
2. For even more detail, enable "**Enable Diagnostic JSON Dump to File**" in the Dumper Options. This saves a raw JSON copy of every dump to the `logs/gdb_dumper_diagnostics/` directory, allowing you to see exactly what the dumper is producing.
|
||||
|
||||
---
|
||||
|
||||
### 11. Use Cases / Examples
|
||||
|
||||
(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.
|
||||
* **Scenario:** You want to inspect the contents of a `std::vector<MyObject> myVector` every time it's modified inside a `processVector` function.
|
||||
* **Profile Setup:**
|
||||
* **Action 1:** Breakpoint at the start of `processVector`.
|
||||
* **Action 2:** Breakpoint at the end of `processVector`.
|
||||
* Both actions dump the `myVector` variable.
|
||||
* **Result:** When the profile runs, files like `vector_dumps/MyProfile_timestamp/processVector_myVector_timestamp.json` (or `.csv`) will be created, allowing you to see the state of the vector before and after processing.
|
||||
|
||||
**11.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.
|
||||
**11.2 Tracing a Global Variable**
|
||||
|
||||
* **Scenario:** You need to track how a global variable `globalCounter` changes at different key points in your application.
|
||||
* **Profile Setup:** Create multiple actions, each with a different breakpoint (e.g., `func_A`, `func_B`, `main.cpp:150`), but all dumping the same variable `globalCounter`.
|
||||
* **Result:** You will get a series of timestamped files, one for each time the counter was dumped, allowing you to trace its value through the program's execution flow.
|
||||
|
||||
**11.3 Snapshots of Complex Data**
|
||||
|
||||
* **Scenario:** Your application has a large configuration or state object (`ApplicationState appState`) and you want to take a complete snapshot of it at a critical point, like just before a long-running task.
|
||||
* **Profile Setup:** An action at `longRunningTask.cpp:75` that dumps the `appState` object.
|
||||
* **Result:** A detailed JSON file like `app_state_snapshots/MyProfile_timestamp/longRunningTask.cpp_75_appState_timestamp.json` will be created, containing a full, nested representation of your application's state.
|
||||
|
||||
---
|
||||
|
||||
### 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).
|
||||
The `gdb_dumper.py` script is the core of the data extraction engine. It runs within the GDB process and has access to GDB's Python API.
|
||||
|
||||
* **Serialization Logic:**
|
||||
1. Uses `gdb.parse_and_eval()` to get a `gdb.Value` object representing a C++ variable.
|
||||
2. 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).
|
||||
* `{profile_name}`: The name of the profile (sanitized for filesystem safety).
|
||||
* `{app_name}`: Base name of the target executable.
|
||||
* `{breakpoint}`: Breakpoint location string (sanitized).
|
||||
* `{variable}`: Variable/expression name (sanitized).
|
||||
* `{timestamp}`: Timestamp (`YYYYMMDD_HHMMSS_fff`).
|
||||
* `{breakpoint}`: The breakpoint location string (sanitized).
|
||||
* `{variable}`: The variable/expression name being dumped (sanitized).
|
||||
* `{timestamp}`: A detailed timestamp (`YYYYMMDD_HHMMSS_ms`).
|
||||
|
||||
**Example Pattern:** `dump_{app_name}_{breakpoint}_{variable}_{timestamp}`
|
||||
**Example Final Output (if JSON):** `dump_myprogram_main_myVar_20231027_143005_123.json`
|
||||
|
||||
Binary file not shown.
Binary file not shown.
@ -4,7 +4,7 @@
|
||||
|
||||
**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?**
|
||||
|
||||
@ -17,369 +17,250 @@ Questo strumento è principalmente destinato agli sviluppatori C/C++ che usano G
|
||||
|
||||
**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.
|
||||
* **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.
|
||||
* **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 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:
|
||||
* 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.
|
||||
* **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.
|
||||
* 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 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.
|
||||
* **Ambiente Configurabile:** Imposta i percorsi per GDB, lo script dumper Python personalizzato, vari timeout per le operazioni GDB e opzioni di comportamento del dumper.
|
||||
* **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.
|
||||
* **Logging GUI:** Visualizza i log dell'applicazione e l'output grezzo di GDB direttamente nell'interfaccia.
|
||||
* **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 estratti in formati JSON o CSV con nomi di file personalizzabili utilizzando placeholder per una migliore organizzazione.
|
||||
* **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**
|
||||
|
||||
* **Windows:** Piattaforma primaria di sviluppo e test grazie all'uso della libreria `pexpect` per il controllo del processo GDB.
|
||||
* **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).
|
||||
* **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 (Sperimentale):** L'applicazione dovrebbe essere compatibile con sistemi Unix-like poiché `pexpect` è multipiattaforma.
|
||||
|
||||
**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**
|
||||
|
||||
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`
|
||||
|
||||
* **`pexpect`**: Per controllare GDB come processo figlio su Windows.
|
||||
* **`appdirs`**: Utilizzato per determinare directory di configurazione e dati utente indipendenti dalla piattaforma.
|
||||
* **Tkinter**: Solitamente inclusa nelle installazioni Python standard e utilizzata per la GUI. Non è tipicamente richiesta un'installazione separata.
|
||||
* **`pexpect`**: Per controllare GDB come processo figlio.
|
||||
* **`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**: Inclusa nelle installazioni standard di Python e utilizzata per la GUI.
|
||||
|
||||
**2.4 Installazione di GDB**
|
||||
|
||||
* È richiesta un'installazione funzionante di GNU Debugger (GDB).
|
||||
* Assicurarsi che GDB sia:
|
||||
* Aggiunto alla variabile d'ambiente `PATH` del sistema.
|
||||
* 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.
|
||||
* 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.
|
||||
* Versioni di GDB 8.x e successive sono raccomandate per il miglior 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**.
|
||||
* Per GCC/G++ o Clang, si 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).
|
||||
* La tua applicazione C/C++ **deve essere compilata con i simboli di debug**.
|
||||
* Per GCC/G++ o Clang, usa il flag `-g`: `g++ -g -o mioprogramma mioprogramma.cpp`.
|
||||
* 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.
|
||||
2. Scaricare o clonare il codice sorgente.
|
||||
3. Navigare nella directory radice del progetto (es., `cpp_python_debug`).
|
||||
4. Eseguire lo script principale usando Python:
|
||||
**3.1 Esecuzione da Codice Sorgente**
|
||||
|
||||
1. Assicurati che tutti i prerequisiti della Sezione 2 siano soddisfatti.
|
||||
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`
|
||||
|
||||
---
|
||||
**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. Soddisfare i "Requisiti di Sistema e Configurazione dell'Ambiente".
|
||||
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.
|
||||
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`).
|
||||
3. Tutti i file generati dall'applicazione (configurazioni, log, dump) verranno creati all'interno di questa cartella, rendendola completamente portabile.
|
||||
|
||||
---
|
||||
|
||||
### 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".
|
||||
* **Profiles:** "Manage Profiles...".
|
||||
|
||||
**4.2 Area Stato Configurazione Critica**
|
||||
|
||||
Mostra lo stato dell'eseguibile GDB e dello Script Dumper. Include un pulsante "Configure...".
|
||||
|
||||
**4.3 Pannello Modalità (Tab)**
|
||||
|
||||
* **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.
|
||||
- **`config/`**
|
||||
- **`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/`**
|
||||
- **`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.
|
||||
- **`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.
|
||||
- **`<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/`).
|
||||
|
||||
---
|
||||
|
||||
### 5. Finestra di Configurazione (`Options > Configure Application...`)
|
||||
### 5. Guida Rapida
|
||||
|
||||
**(Uno screenshot della Finestra di Configurazione con le tab sarebbe utile qui)**
|
||||
|
||||
Organizzata in tab:
|
||||
|
||||
**5.1 Tab Paths & Directories**
|
||||
|
||||
* **GDB Executable Path:** Percorso completo a GDB. *Cruciale.*
|
||||
* **GDB Python Dumper Script Path (Optional):** Percorso completo a `gdb_dumper.py`. *Fortemente raccomandato per la piena funzionalità.*
|
||||
|
||||
**5.2 Tab Timeouts (seconds)**
|
||||
|
||||
Configura i timeout per le operazioni GDB (tutti in secondi):
|
||||
|
||||
* **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 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.
|
||||
1. **Avvia l'Applicazione** come descritto nella Sezione 3.
|
||||
2. **Configurazione Iniziale:** Al primo avvio, vai su **Options > Configure Application...**.
|
||||
* 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).
|
||||
* Clicca **Save**.
|
||||
3. **Esegui una Sessione di Debug Manuale:**
|
||||
* Vai alla scheda **Manual Debug**.
|
||||
* Seleziona il tuo eseguibile C/C++ compilato.
|
||||
* Inserisci un breakpoint (es. `main`).
|
||||
* Clicca **1. Start GDB**.
|
||||
* Clicca **2. Set Breakpoint**.
|
||||
* Clicca **3. Run Program**.
|
||||
* Quando il breakpoint viene raggiunto, inserisci un nome di variabile e clicca **4. Dump Variable**.
|
||||
* 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`.
|
||||
* I pulsanti **Save as JSON** e **Save as CSV** diventeranno attivi. Usali per salvare i dati catturati in una posizione permanente.
|
||||
|
||||
---
|
||||
|
||||
### 6. Modalità Debug Manuale
|
||||
### 6. Panoramica dell'Interfaccia Utente
|
||||
|
||||
**(Uno screenshot della tab Manual Debug sarebbe utile)**
|
||||
|
||||
**6.1 Impostazione Eseguibile Target e Parametri**
|
||||
Campi per "Target Executable" (con Browse...) e "Program Parameters".
|
||||
|
||||
**6.2 Impostazione Posizione Breakpoint**
|
||||
Campo per il breakpoint (es., `main`, `file.cpp:123`).
|
||||
|
||||
**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).
|
||||
* **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.
|
||||
* **Pannello Modalità (Schede)**: Passa tra **Manual Debug** e **Automated Profile Execution**.
|
||||
* **Area di Output e Log (Schede)**:
|
||||
* `GDB Raw Output`: Comunicazione testuale grezza con il processo GDB.
|
||||
* `Parsed JSON/Status Output`: Mostra il payload di stato ricevuto dallo script dumper o formatta JSON semplici.
|
||||
* `Application Log`: Messaggi di log relativi alla GUI.
|
||||
* **Barra di Stato**: Brevi messaggi sullo stato corrente 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**
|
||||
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".
|
||||
|
||||
**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).
|
||||
* **Scheda Paths & Directories**: Imposta i percorsi assoluti a `gdb.exe` e `gdb_dumper.py`.
|
||||
* **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.
|
||||
|
||||
---
|
||||
|
||||
### 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.
|
||||
|
||||
**8.1 Posizione Breakpoint**
|
||||
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.
|
||||
* 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.
|
||||
* Devi quindi usare i pulsanti **Save as...** per copiare e convertire questi dati temporanei in una posizione permanente.
|
||||
|
||||
---
|
||||
|
||||
### 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**
|
||||
Dropdown elenca i profili disponibili.
|
||||
**9.1 Gestore Profili (`Profiles > Manage Profiles...`)**
|
||||
|
||||
**9.2 Esecuzione del Profilo**
|
||||
Pulsante "Run Profile" avvia l'esecuzione. La GUI si aggiorna. Un `ProfileExecutor` viene eseguito in un thread separato.
|
||||
* GDB si avvia, il dumper viene caricato, i breakpoint vengono impostati.
|
||||
* Al raggiungimento di un breakpoint:
|
||||
* 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.
|
||||
Questa finestra è il centro per creare e gestire i tuoi scenari di debug automatizzati. Un profilo è composto da:
|
||||
1. **Dettagli Profilo**: Nome, eseguibile target e parametri del programma.
|
||||
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.
|
||||
3. **Azioni**: Un elenco di azioni di debug.
|
||||
|
||||
**9.3 Monitoraggio Stato Esecuzione e Barra di Progresso**
|
||||
Etichetta di stato e barra di progresso mostrano l'avanzamento.
|
||||
**9.2 Editor di Azioni**
|
||||
|
||||
**9.4 Interruzione di un Profilo in Esecuzione**
|
||||
Pulsante "Stop Profile" tenta di terminare gradualmente.
|
||||
Ogni azione definisce un'attività specifica da eseguire a un breakpoint.
|
||||
* **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"**
|
||||
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.3 Flusso di Esecuzione Automatizzata**
|
||||
|
||||
**9.6 Apertura della Cartella di Output**
|
||||
Pulsante "Open Profile Output Folder" apre la directory di output principale per l'ultima esecuzione del profilo completata.
|
||||
1. Seleziona un profilo dal menu a tendina nella scheda "Automated Profile Execution".
|
||||
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
|
||||
|
||||
**D: GDB non trovato / Problemi con lo script Dumper / Nessun simbolo di debug / `_gdb_tool_error` nell'output JSON.**
|
||||
**R:** (Stessi consigli di prima, enfatizzando il controllo di `gdb_dumper_debug.log` per problemi del dumper).
|
||||
**D: GDB non trovato / Problemi con lo script Dumper / Nessun simbolo di debug.**
|
||||
**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.**
|
||||
**R:** (Stessi consigli di prima, verificare percorsi, BP, parametri, timeout).
|
||||
**D: L'applicazione si blocca o va in timeout.**
|
||||
**R:** Il tuo programma target potrebbe richiedere molto tempo. Prova ad aumentare i timeout nella Finestra di Configurazione.
|
||||
|
||||
**D: La GUI non risponde.**
|
||||
**R:** (Stessi consigli di prima, controllare timeout, console/Application Log per errori).
|
||||
|
||||
**D: Come posso ottenere maggiori informazioni di debug da `gdb_dumper.py`?**
|
||||
**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".
|
||||
**D: `gdb_dumper.py` sta fallendo. Come posso debuggarlo?**
|
||||
**A:**
|
||||
1. Controlla il file `logs/gdb_dumper_script_internal.log`. È il primo posto dove cercare errori che si verificano all'interno del dumper.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
### 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`**
|
||||
* ...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**
|
||||
* ...File di output per `globalCounter` verranno generati per ogni posizione di breakpoint.
|
||||
|
||||
**11.3 Snapshot di strutture dati complesse**
|
||||
* ...Una serie di file JSON come `app_state_snapshots/NomeProfilo_timestamp/longRunningTask.cpp_75_appState_timestamp.json` verrà creata.
|
||||
* **Scenario:** Devi monitorare come una variabile globale `globalCounter` cambia in punti chiave della tua applicazione.
|
||||
* **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.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`)**
|
||||
(Contenuto per lo più invariato, enfatizzando il suo ruolo per problemi interni al dumper).
|
||||
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.
|
||||
|
||||
* **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).
|
||||
* `{app_name}`: Nome base dell'eseguibile target.
|
||||
* `{breakpoint}`: Stringa della posizione del breakpoint (sanificata).
|
||||
* `{variable}`: Nome della variabile/espressione (sanificato).
|
||||
* `{timestamp}`: Timestamp (`ANNO MESE GIORNO_ORA MINUTO SECONDO_MILLISECONDO`).
|
||||
* `{profile_name}`: Il nome del profilo (sanificato per la sicurezza del filesystem).
|
||||
* `{app_name}`: Il nome base dell'eseguibile target.
|
||||
* `{breakpoint}`: La stringa della posizione del breakpoint (sanificata).
|
||||
* `{variable}`: Il nome della variabile/espressione estratta (sanificato).
|
||||
* `{timestamp}`: Un timestamp dettagliato (`ANNO MESE GIORNO_ORA MINUTO SECONDO_ms`).
|
||||
|
||||
**Pattern Esempio:** `dump_{app_name}_{breakpoint}_{variable}_{timestamp}`
|
||||
**Output Finale Esempio (se JSON):** `dump_mioprogramma_main_miaVar_20231027_143005_123.json`
|
||||
|
||||
Binary file not shown.
Loading…
Reference in New Issue
Block a user