151 lines
7.2 KiB
Markdown
151 lines
7.2 KiB
Markdown
## Struttura Proposta per il Manuale Utente
|
|
|
|
1. **Introduzione / Panoramica**
|
|
* Scopo del software.
|
|
* A chi è rivolto.
|
|
* Breve descrizione delle funzionalità principali.
|
|
2. **Installazione e Requisiti**
|
|
* Requisiti di sistema (Python, GDB).
|
|
* Come installare l'applicazione e le sue dipendenze.
|
|
3. **Guida Rapida (Quick Start)**
|
|
* Passaggi essenziali per avviare una sessione di debug e fare un dump.
|
|
4. **Interfaccia Utente Dettagliata**
|
|
* Descrizione della Finestra Principale:
|
|
* Sezione Stato Configurazione Critica (GDB, Dumper Script)
|
|
* Sezione Impostazioni Target e Sessione Debug (Target Executable, Parametri, Breakpoint, Variabile)
|
|
* Pulsanti di Controllo Sessione (Start, Set BP, Run/Continue, Dump, Stop)
|
|
* Schede di Output (GDB Raw Output, Parsed JSON Output, Application Log)
|
|
* Sezione Salvataggio Dati
|
|
* Barra di Stato
|
|
* Menu Opzioni:
|
|
* Configure Application...
|
|
* Exit
|
|
* Finestra di Configurazione Applicazione:
|
|
* Scheda Paths (GDB Executable, GDB Dumper Script)
|
|
* Scheda Timeouts
|
|
* Scheda Dumper Options
|
|
* Pulsanti Save, Cancel
|
|
5. **Funzionalità Avanzate e Concetti**
|
|
* Come funziona il Dump Strutturato (ruolo di `gdb_dumper.py`).
|
|
* Interpretazione dell'output JSON.
|
|
* Gestione dei Timeout.
|
|
* Logging e Troubleshooting (dove trovare i log, cosa cercare).
|
|
6. **Esempi di Casi d'Uso**
|
|
* Debug di un `std::vector` di struct.
|
|
* Analisi di una classe complessa.
|
|
* Esportazione di dati per analisi offline.
|
|
7. **Domande Frequenti (FAQ)**
|
|
* Problemi comuni e soluzioni.
|
|
8. **Contribuire e Segnalazione Bug** (Opzionale)
|
|
9. **Licenza** (Opzionale)
|
|
|
|
---
|
|
|
|
### Iniziamo con le prime sezioni:
|
|
|
|
---
|
|
|
|
### **MANUALE UTENTE (ITALIANO)**
|
|
|
|
---
|
|
|
|
## **Cpp-Python GDB Debug Helper - Manuale Utente**
|
|
|
|
### 1. Introduzione
|
|
|
|
Benvenuto in **Cpp-Python GDB Debug Helper**! Questo software è stato creato per assistere gli sviluppatori C/C++ nel processo di debug dei loro programmi, fornendo un'interfaccia grafica intuitiva per controllare GDB (il Debugger GNU) e, soprattutto, per facilitare l'ispezione e l'esportazione di dati complessi in formati strutturati come JSON e CSV.
|
|
|
|
Se ti sei mai trovato a dover navigare strutture dati intricate o lunghi array nel terminale di GDB, o se hai desiderato poter salvare lo stato di una variabile per un'analisi più approfondita, questo strumento è pensato per te. Sfrutta la potenza dell'API Python di GDB per "dissezionare" le tue variabili e presentarle in modo chiaro.
|
|
|
|
**Funzionalità Principali a Colpo d'Occhio:**
|
|
|
|
* Controllo grafico della sessione GDB (avvio, breakpoint, esecuzione).
|
|
* Dump di variabili C/C++ in formato JSON leggibile.
|
|
* Configurazione personalizzabile per GDB e per il processo di dump.
|
|
* Esportazione dei dati dumpati in JSON o CSV.
|
|
* Visualizzazione dell'output di GDB e dei log dell'applicazione.
|
|
|
|
### 2. Installazione e Requisiti
|
|
|
|
**Requisiti di Sistema:**
|
|
|
|
* **Python**: Versione 3.7 o successiva. Puoi scaricarlo da [python.org](https://www.python.org/). Assicurati che Python sia aggiunto al tuo PATH di sistema.
|
|
* **GDB (GNU Debugger)**: Una versione di GDB che includa il supporto per lo scripting Python (la maggior parte delle versioni recenti lo include). Se stai usando MinGW su Windows, GDB è tipicamente incluso. Assicurati che l'eseguibile di GDB sia accessibile.
|
|
* **Sistema Operativo**: Testato principalmente su Windows, ma dovrebbe funzionare su Linux o macOS con GDB e Python installati (potrebbe richiedere `pexpect` invece di `wexpect` su sistemi non Windows, anche se `wexpect` è un fork che punta alla compatibilità).
|
|
|
|
**Installazione dell'Applicazione:**
|
|
|
|
1. **Clona il Repository (se applicabile) o Scarica i File Sorgente:**
|
|
```bash
|
|
git clone <URL_DEL_TUO_REPOSITORY_GITEA>
|
|
cd <nome_directory_progetto>
|
|
```
|
|
2. **Crea un Ambiente Virtuale (Raccomandato):**
|
|
```bash
|
|
python -m venv venv
|
|
# Su Windows
|
|
venv\Scripts\activate
|
|
# Su Linux/macOS
|
|
source venv/bin/activate
|
|
```
|
|
3. **Installa le Dipendenze:**
|
|
Il file `requirements.txt` (se presente) dovrebbe elencare le dipendenze. Le principali sono:
|
|
* `wexpect`: Per il controllo del processo GDB su Windows.
|
|
* `appdirs`: Per la gestione dei percorsi di configurazione cross-platform.
|
|
Puoi installarle con pip:
|
|
```bash
|
|
pip install wexpect appdirs
|
|
```
|
|
Se hai un file `requirements.txt`:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
**Verifica dell'Installazione di GDB:**
|
|
Apri un terminale e digita `gdb --version`. Dovresti vedere le informazioni sulla versione di GDB. Se il comando non viene trovato, GDB non è nel tuo PATH o non è installato.
|
|
|
|
### 3. Guida Rapida (Quick Start)
|
|
|
|
Segui questi passaggi per iniziare rapidamente:
|
|
|
|
1. **Avvia l'Applicazione:**
|
|
Dalla directory principale del progetto, esegui:
|
|
```bash
|
|
python -m cpp_python_debug
|
|
```
|
|
Si aprirà la finestra principale dell'applicazione.
|
|
|
|
2. **Configura GDB (Solo la Prima Volta):**
|
|
* Vai su "Options" > "Configure Application...".
|
|
* Nella scheda "Paths", clicca su "Browse..." accanto a "GDB Executable" e seleziona il file `gdb.exe` sul tuo sistema (es. `C:\MinGW\bin\gdb.exe`).
|
|
* Lo "GDB Dumper Script" dovrebbe essere auto-rilevato se lo script `gdb_dumper.py` è nella sua posizione standard (`core/gdb_dumper.py` relativo al progetto). Altrimenti, puoi specificarlo manualmente.
|
|
* Clicca su "Save".
|
|
|
|
3. **Imposta il Target e il Breakpoint nella Finestra Principale:**
|
|
* **Target Executable**: Clicca "Browse..." e seleziona l'eseguibile C/C++ compilato con simboli di debug (es. flag `-g` durante la compilazione con GCC/Clang) che vuoi debuggare.
|
|
* **Breakpoint Location**: Inserisci dove vuoi che il programma si fermi (es. `main`, `MyClass::myMethod`, `myfile.cpp:123`).
|
|
* **Variable/Expression**: Inserisci il nome della variabile o l'espressione che vuoi analizzare quando il breakpoint viene raggiunto (es. `myVector`, `*this`, `global_struct.member`).
|
|
|
|
4. **Avvia il Debug:**
|
|
* Clicca su **"1. Start GDB Session"**. La sezione "GDB Raw Output" mostrerà l'avvio di GDB.
|
|
* Se GDB e lo script dumper sono configurati correttamente, lo stato nella parte alta della finestra dovrebbe indicarlo.
|
|
|
|
5. **Imposta il Breakpoint:**
|
|
* Clicca su **"2. Set Breakpoint"**.
|
|
|
|
6. **Esegui il Programma:**
|
|
* Clicca su **"3. Run Program"** (o "3. Continue" se il programma è già stato avviato).
|
|
* Il programma dovrebbe eseguirsi e fermarsi al breakpoint specificato. L'output di GDB mostrerà il punto di arresto.
|
|
|
|
7. **Effettua il Dump della Variabile:**
|
|
* Clicca su **"4. Dump Variable"**.
|
|
* La scheda "Parsed JSON Output" mostrerà la struttura della variabile in formato JSON.
|
|
* L'output grezzo di GDB mostrerà i delimitatori `START_JSON_OUTPUT` e `END_JSON_OUTPUT` attorno al JSON grezzo.
|
|
|
|
8. **Salva i Dati (Opzionale):**
|
|
* Usa i pulsanti "Save as JSON" o "Save as CSV" per salvare i dati dumpati.
|
|
|
|
9. **Termina la Sessione:**
|
|
* Clicca su **"Stop GDB Session"** per terminare GDB.
|
|
* Chiudi l'applicazione tramite il menu "Options" > "Exit" o il pulsante di chiusura della finestra. Le impostazioni verranno salvate.
|