143 lines
8.0 KiB
Markdown
143 lines
8.0 KiB
Markdown
### Versione in Italiano per `README.md`
|
|
|
|
```markdown
|
|
# Cpp-Python GDB Debug Helper
|
|
|
|
## Panoramica
|
|
|
|
**Cpp-Python GDB Debug Helper** è un'applicazione desktop progettata per semplificare il processo di debug di eseguibili C/C++ utilizzando GDB (GNU Debugger), con un focus particolare sull'ispezione e l'esportazione strutturata (JSON/CSV) di variabili complesse. L'interfaccia grafica è costruita con Tkinter e l'interazione con GDB avviene tramite uno script Python personalizzato eseguito all'interno della sessione di GDB.
|
|
|
|
Questo strumento è particolarmente utile per sviluppatori che necessitano di analizzare lo stato di strutture dati complesse, array, o oggetti durante una sessione di debug C/C++ e desiderano esportare queste informazioni in un formato facilmente processabile per analisi successive o documentazione.
|
|
|
|
## Funzionalità Principali
|
|
|
|
* **Interfaccia Grafica Semplice**: Una GUI basata su Tkinter per controllare la sessione di GDB.
|
|
* **Configurazione Centralizzata**:
|
|
* Percorso dell'eseguibile GDB.
|
|
* Timeout personalizzabili per varie operazioni di GDB.
|
|
* Opzioni configurabili per lo script dumper Python (es. massima profondità di ricorsione, numero massimo di elementi per array, lunghezza massima delle stringhe).
|
|
* Le impostazioni vengono salvate in un file JSON per persistere tra le sessioni.
|
|
* **Controllo Sessione GDB**:
|
|
* Avvio e arresto della sessione GDB.
|
|
* Impostazione di breakpoint.
|
|
* Esecuzione e continuazione del programma target con parametri.
|
|
* **Dump Strutturato di Variabili**:
|
|
* Utilizza uno script Python personalizzato (`gdb_dumper.py`) eseguito all'interno di GDB per analizzare una variabile o espressione C/C++.
|
|
* Serializza la struttura della variabile in formato JSON, gestendo tipi complessi, puntatori, riferimenti, cicli e membri di classi/struct.
|
|
* Le opzioni del dumper (come la profondità massima) vengono passate dinamicamente allo script Python tramite variabili GDB.
|
|
* **Visualizzazione ed Esportazione dell'Output**:
|
|
* Visualizzazione dell'output grezzo di GDB.
|
|
* Visualizzazione del JSON formattato prodotto dal dumper.
|
|
* Esportazione dei dati dumpati in formato JSON o CSV.
|
|
* **Logging Dettagliato**: Logging sia per l'applicazione Python principale che per lo script dumper Python eseguito da GDB, utile per il troubleshooting.
|
|
|
|
## Stack Tecnologico
|
|
|
|
* **Linguaggi**: Python, C++ (per l'eseguibile target da debuggare)
|
|
* **GUI**: Tkinter (libreria standard Python)
|
|
* **Interazione GDB**: `wexpect` (un fork di Pexpect per Windows, per controllare processi da console), comandi GDB standard.
|
|
* **Scripting GDB**: API Python di GDB.
|
|
* **Formato Dati**: JSON, CSV.
|
|
* **Gestione Configurazione**: `appdirs` (per percorsi di configurazione cross-platform).
|
|
|
|
## Struttura del Progetto (Principale)
|
|
|
|
* `cpp_python_debug/`: Pacchetto principale dell'applicazione.
|
|
* `__main__.py`: Entry point, avvio GUI, logging globale.
|
|
* `core/`: Moduli backend.
|
|
* `config_manager.py`: Gestione delle impostazioni dell'applicazione.
|
|
* `gdb_controller.py`: Classe per gestire e interagire con il processo GDB.
|
|
* `gdb_dumper.py`: Script Python eseguito da GDB per serializzare le variabili.
|
|
* `output_formatter.py`: Utility per salvare i dati in JSON/CSV.
|
|
* `gui/`: Moduli per l'interfaccia grafica.
|
|
* `main_window.py`: Finestra principale dell'applicazione.
|
|
* `config_window.py`: Finestra per la configurazione delle impostazioni.
|
|
|
|
## Come Usare
|
|
|
|
1. Assicurarsi di avere Python 3.x e GDB installati.
|
|
2. Installare le dipendenze necessarie (es. `wexpect`, `appdirs`).
|
|
3. Eseguire l'applicazione: `python -m cpp_python_debug`.
|
|
4. Configurare il percorso dell'eseguibile GDB tramite il menu "Options" > "Configure Application...".
|
|
5. Nella finestra principale, specificare il percorso dell'eseguibile C/C++ da debuggare.
|
|
6. Impostare un breakpoint e una variabile/espressione da analizzare.
|
|
7. Avviare la sessione GDB, eseguire il programma fino al breakpoint.
|
|
8. Eseguire il dump della variabile per visualizzarla in formato JSON e salvarla se necessario.
|
|
|
|
---
|
|
Questo README mira a fornire una buona base. Potresti voler aggiungere sezioni come "Installazione", "Contribuire", "Licenza", o screenshot dell'applicazione.
|
|
---
|
|
```
|
|
|
|
---
|
|
|
|
### English Version for `README.md`
|
|
|
|
```markdown
|
|
# Cpp-Python GDB Debug Helper
|
|
|
|
## Overview
|
|
|
|
**Cpp-Python GDB Debug Helper** is a desktop application designed to simplify the process of debugging C/C++ executables using GDB (the GNU Debugger), with a particular focus on inspecting and exporting complex variables in a structured format (JSON/CSV). The graphical user interface is built with Tkinter, and interaction with GDB is managed via a custom Python script executed within the GDB session.
|
|
|
|
This tool is especially useful for developers who need to analyze the state of complex data structures, arrays, or objects during a C/C++ debugging session and wish to export this information into an easily processable format for later analysis or documentation.
|
|
|
|
## Key Features
|
|
|
|
* **Simple Graphical Interface**: A Tkinter-based GUI to control the GDB session.
|
|
* **Centralized Configuration**:
|
|
* Path to the GDB executable.
|
|
* Customizable timeouts for various GDB operations.
|
|
* Configurable options for the Python dumper script (e.g., max recursion depth, max array elements, max string length).
|
|
* Settings are saved to a JSON file to persist across sessions.
|
|
* **GDB Session Control**:
|
|
* Start and stop GDB sessions.
|
|
* Set breakpoints.
|
|
* Run and continue the target program with parameters.
|
|
* **Structured Variable Dumping**:
|
|
* Utilizes a custom Python script (`gdb_dumper.py`) executed within GDB to inspect a C/C++ variable or expression.
|
|
* Serializes the variable's structure into JSON format, handling complex types, pointers, references, cycles, and class/struct members.
|
|
* Dumper options (like maximum depth) are dynamically passed to the Python script via GDB variables.
|
|
* **Output Display and Export**:
|
|
* View raw GDB output.
|
|
* View the formatted JSON output produced by the dumper.
|
|
* Export dumped data to JSON or CSV formats.
|
|
* **Detailed Logging**: Logging for both the main Python application and the GDB dumper Python script, useful for troubleshooting.
|
|
|
|
## Technology Stack
|
|
|
|
* **Languages**: Python, C++ (for the target executable to be debugged)
|
|
* **GUI**: Tkinter (Python standard library)
|
|
* **GDB Interaction**: `wexpect` (a Pexpect fork for Windows, for controlling console processes), standard GDB commands.
|
|
* **GDB Scripting**: GDB's Python API.
|
|
* **Data Format**: JSON, CSV.
|
|
* **Configuration Management**: `appdirs` (for cross-platform configuration paths).
|
|
|
|
## Project Structure (Core)
|
|
|
|
* `cpp_python_debug/`: Main application package.
|
|
* `__main__.py`: Entry point, GUI startup, global logging.
|
|
* `core/`: Backend modules.
|
|
* `config_manager.py`: Manages application settings.
|
|
* `gdb_controller.py`: Class for managing and interacting with the GDB process.
|
|
* `gdb_dumper.py`: Python script run by GDB to serialize variables.
|
|
* `output_formatter.py`: Utilities for saving data to JSON/CSV.
|
|
* `gui/`: Modules for the graphical interface.
|
|
* `main_window.py`: Main application window.
|
|
* `config_window.py`: Window for configuring settings.
|
|
|
|
## How to Use
|
|
|
|
1. Ensure Python 3.x and GDB are installed.
|
|
2. Install necessary dependencies (e.g., `wexpect`, `appdirs`).
|
|
3. Run the application: `python -m cpp_python_debug`.
|
|
4. Configure the GDB executable path via the "Options" > "Configure Application..." menu.
|
|
5. In the main window, specify the path to the C/C++ executable to debug.
|
|
6. Set a breakpoint and the variable/expression to inspect.
|
|
7. Start the GDB session, run the program to the breakpoint.
|
|
8. Dump the variable to view its JSON representation and save it if needed.
|
|
|
|
---
|
|
This README aims to provide a good foundation. You might want to add sections like "Installation," "Contributing," "License," or screenshots of the application.
|
|
---
|
|
``` |