## Cpp-Python GDB Debug Helper - Manuale Utente

### 1. Introduzione

**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.

**1.2 A chi è rivolto?**

Questo strumento è principalmente destinato agli sviluppatori C/C++ che usano GDB per il debugging e che trarrebbero beneficio da:

*   Un'interfaccia visuale per le operazioni comuni di GDB.
*   Una più facile ispezione di tipi di dati C++ complessi (strutture, classi, contenitori STL).
*   Automazione di sequenze di debugging attraverso profili configurabili.
*   Output strutturato dei dump delle variabili in formato JSON o CSV.

**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.
*   **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.
*   **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.

---

### 2. Requisiti di Sistema e Configurazione dell'Ambiente

**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).

**2.2 Python**

*   Python 3.7 o successivo è raccomandato (testato con versioni fino a 3.13).

**2.3 Librerie Python Richieste**

Sarà necessario installare le seguenti librerie Python. Tipicamente si possono installare 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.

**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.

**2.5 Compilazione dell'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).

**2.6 Installazione dello Strumento (Cpp-Python GDB Debug Helper)**

Attualmente, il software è progettato per essere eseguito dal suo codice sorgente:

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:
    `python -m cpp_python_debug`

---

### 3. Guida Rapida

**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.

---

### 4. Panoramica dell'Interfaccia Utente (Finestra Principale)

**(Uno screenshot della finestra principale con aree annotate sarebbe ideale qui)**

**4.1 Barra dei Menu**

*   **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.

---

### 5. Finestra di Configurazione (`Options > Configure Application...`)

**(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.

---

### 6. Modalità Debug Manuale

**(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).

---

### 7. Gestore Profili (`Profiles > Manage Profiles...`)

**(Screenshot del Gestore Profili raccomandato)**

**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).

---

### 8. Finestra Editor Azioni (dal Gestore Profili)

**(Screenshot dell'Editor Azioni raccomandato)**

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.

---

### 9. Modalità Esecuzione Automatizzata Profili

**(Screenshot della tab Esecuzione Automatizzata raccomandato)**

**9.1 Selezione di un Profilo**
Dropdown elenca i profili disponibili.

**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.

**9.3 Monitoraggio Stato Esecuzione e Barra di Progresso**
Etichetta di stato e barra di progresso mostrano l'avanzamento.

**9.4 Interruzione di un Profilo in Esecuzione**
Pulsante "Stop Profile" tenta di terminare gradualmente.

**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.6 Apertura della Cartella di Output**
Pulsante "Open Profile Output Folder" apre la directory di output principale per l'ultima esecuzione del profilo completata.

---

### 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: Esecuzione del profilo fallisce, si blocca, o i breakpoint non vengono raggiunti.**
**R:** (Stessi consigli di prima, verificare percorsi, BP, parametri, timeout).

**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".

---

### 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.

**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.

---

### 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).

---

### 13. Appendice (Opzionale)

**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 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`).

**Pattern Esempio:** `dump_{app_name}_{breakpoint}_{variable}_{timestamp}`
**Output Finale Esempio (se JSON):** `dump_mioprogramma_main_miaVar_20231027_143005_123.json`
**File Dump Intermedio GDB Esempio:** `dump_mioprogramma_main_miaVar_20231027_143005_123.gdbdump.json`