diff --git a/README.md b/README.md index 46ba604..f311617 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,143 @@ -# cpp_python_debug +### Versione in Italiano per `README.md` -A brief description of cpp_python_debug. +```markdown +# Cpp-Python GDB Debug Helper -## Features -- Feature 1 -- Feature 2 +## Panoramica -## Getting Started -... +**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. -## Contributing -... +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. -## License -... +## 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. +--- +``` \ No newline at end of file