## 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 potenziare e semplificare il processo di debug 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 debug ripetitivi.

**1.2 A chi è rivolto?**

Questo strumento è principalmente rivolto agli sviluppatori C/C++ che utilizzano GDB per il debug e che trarrebbero vantaggio da:

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

**1.3 Caratteristiche Principali**

*   **Debug Manuale Interattivo:** Avvia GDB, imposta breakpoint, esegui il programma target, naviga nel codice (implicitamente tramite run/continue) e ispeziona variabili.
*   **Dump Avanzato delle Variabili:** Esegui il dump dello stato delle variabili C/C++, incluse strutture dati complesse come classi, strutture, 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 (JSON/CSV), directory di output e pattern per i nomi dei file.
*   **Analisi dei Simboli:** Analizza il tuo eseguibile compilato (utilizzando 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 e vari timeout per le operazioni di GDB.
*   **Output Flessibile:** Salva i dati dumpati nei formati JSON o CSV con nomi di file personalizzabili utilizzando placeholder per una migliore organizzazione.
*   **Logging GUI:** Visualizza i log dell'applicazione e l'output raw di GDB direttamente nell'interfaccia.

---

### 2. Requisiti di Sistema e Configurazione Ambiente

**2.1 Sistemi Operativi Supportati**

*   **Windows:** Piattaforma di sviluppo e test principale grazie all'uso della libreria `wexpect` per il controllo del processo GDB.
*   **Linux/macOS:** GDB stesso è multipiattaforma. Sebbene `wexpect` sia specifico per Windows, la logica di interazione principale con GDB potrebbe essere adattata per `pexpect` su sistemi Unix-like (questo adattamento non fa attualmente parte del codebase fornito ma è una potenziale estensione).

**2.2 Python**

*   È raccomandato Python 3.7 o versioni successive.

**2.3 Librerie Python Richieste**

Sarà necessario installare le seguenti librerie Python. Tipicamente, puoi installarle usando pip:
`pip install wexpect appdirs`

*   **`wexpect`**: Per controllare GDB come processo figlio su Windows.
    *   *Nota: Per Linux/macOS, `pexpect` sarebbe l'equivalente.*
*   **`appdirs`**: Utilizzato per determinare directory di configurazione e dati utente indipendenti dalla piattaforma.
*   **Tkinter**: Solitamente incluso nelle installazioni standard di Python e utilizzato per la GUI. Generalmente non è necessaria un'installazione separata.

**2.4 Installazione di GDB**

*   È richiesta un'installazione funzionante di GNU Debugger (GDB).
*   Assicurati che GDB sia:
    *   Aggiunto alla variabile d'ambiente `PATH` del tuo sistema, in modo che possa essere invocato come `gdb`.
    *   Oppure, fornisci il percorso completo all'eseguibile `gdb.exe` (o `gdb` su Linux/macOS) nella finestra di configurazione dell'applicazione.
*   Le versioni GDB 8.x e successive sono generalmente raccomandate per un migliore supporto allo scripting Python.

**2.5 Compilazione dell'Applicazione C/C++ Target**

*   Per sfruttare al meglio GDB e questo strumento, la tua applicazione C/C++ **deve essere compilata con i simboli di debug**.
*   Per GCC/G++ o Clang, ciò si ottiene tipicamente aggiungendo il flag `-g` durante la compilazione. Ad esempio:
    `g++ -g -o mioprogramma mioprogramma.cpp`
*   Evita livelli elevati di ottimizzazione (es. `-O2`, `-O3`) se rimuovono troppe informazioni di debug o rendono difficile il debug a causa del riordinamento del codice. Compilare con `-Og` (ottimizza per l'esperienza di debug) può essere un buon compromesso se è necessaria una certa ottimizzazione.

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

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

1.  Assicurati che tutti i prerequisiti (Python, librerie, GDB) siano soddisfatti.
2.  Scarica o clona il codice sorgente di Cpp-Python GDB Debug Helper.
3.  Naviga nella directory principale del progetto (es. `cpp_python_debug`).
4.  Esegui lo script principale usando Python:
    `python -m cpp_python_debug`
    (Questo presuppone che `__main__.py` sia in una struttura di package. Se è uno script semplice, `python __main__.py` o `python main_window.py` potrebbero essere usati direttamente dalla loro directory).

---

### 3. Guida Rapida (Quick Start)

Questa guida ti accompagnerà nei passaggi base per avviare Cpp-Python GDB Debug Helper per una sessione di debug manuale.

**3.1 Avvio dell'Applicazione**

1.  Assicurati di aver soddisfatto tutti i "Requisiti di Sistema e Configurazione Ambiente" (Sezione 2).
2.  Naviga nella directory principale del codice sorgente di Cpp-Python GDB Debug Helper.
3.  Esegui lo script principale:
    `python -m cpp_python_debug`
    Dovrebbe apparire la finestra principale dell'applicazione.

**3.2 Configurazione Iniziale (Percorso GDB)**

1.  Al primo avvio, o se GDB non viene trovato, probabilmente dovrai configurare il percorso del tuo eseguibile GDB.
2.  Nella finestra principale, vai su **Options > Configure Application...**.
3.  Nella finestra "Configuration", seleziona la scheda **Paths**.
4.  Sotto "GDB Executable", clicca **Browse...** e naviga fino al tuo file eseguibile GDB (es. `gdb.exe` su Windows, `gdb` su Linux/macOS).
5.  Clicca **Save**.
6.  L'area "Critical Configuration Status" nella finestra principale dovrebbe ora mostrare "GDB: ... (OK)".

**(Opzionale) Configura Percorso Script Dumper:**

*   Lo strumento include uno script Python personalizzato (`gdb_dumper.py`) situato nella sottodirectory `core` dell'applicazione. Questo script abilita il dump JSON avanzato delle variabili.
*   Nella scheda **Paths** della finestra di Configurazione, sotto "GDB Dumper Script", clicca **Browse...** e naviga fino a questo file `gdb_dumper.py`.
*   Clicca **Save**. L'area di stato dovrebbe aggiornarsi per mostrare lo script dumper come "(OK)" o "(Loaded)".

**3.3 La Tua Prima Sessione di Debug Manuale**

1.  **Seleziona la Scheda "Manual Debug":** Questa è tipicamente la scheda predefinita.
2.  **Target Executable:**
    *   Clicca il pulsante **Browse...** accanto a "Target Executable".
    *   Naviga e seleziona il tuo eseguibile C/C++ compilato con simboli di debug (es. `mioprogramma.exe`).
3.  **Program Parameters (Opzionale):**
    *   Se il tuo programma richiede argomenti da riga di comando, inseriscili nel campo "Program Parameters".
4.  **Breakpoint Location:**
    *   Inserisci una locazione di breakpoint nel campo "Breakpoint Location". Esempi comuni:
        *   `main` (per interrompere all'inizio della funzione `main`)
        *   `miafunzione` (per interrompere all'inizio di `miafunzione`)
        *   `miofile.cpp:42` (per interrompere alla linea 42 di `miofile.cpp`)
        *   `MiaClasse::mioMetodo` (per interrompere al metodo C++)
5.  **Variable/Expression to Dump:**
    *   Inserisci il nome di una variabile o un'espressione C/C++ che vuoi ispezionare quando il breakpoint viene raggiunto (es. `miaVarLocale`, `*mioPuntatore`, `mioOggetto.membro`).
6.  **Avvia GDB:**
    *   Clicca il pulsante **1. Start GDB**.
    *   L'area "GDB Raw Output" mostrerà i messaggi di avvio di GDB. La "Status Bar" in basso dovrebbe indicare "GDB session active."
7.  **Imposta Breakpoint:**
    *   Clicca il pulsante **2. Set Breakpoint**.
    *   La risposta di GDB al comando di breakpoint apparirà in "GDB Raw Output". Il testo del pulsante dovrebbe aggiornarsi (es. "BP: main (Set)") se l'operazione ha successo.
8.  **Esegui Programma:**
    *   Clicca il pulsante **3. Run Program**.
    *   Il programma verrà eseguito fino a raggiungere il breakpoint (o fino alla sua terminazione/crash).
    *   L'"GDB Raw Output" mostrerà l'output del programma e i messaggi di GDB. Se il breakpoint viene raggiunto, la barra di stato si aggiornerà. Il pulsante "3. Run Program" cambierà in "3. Continue".
9.  **Dump Variabile:**
    *   Una volta raggiunto il breakpoint, clicca il pulsante **4. Dump Variable**.
    *   L'"GDB Raw Output" mostrerà i comandi inviati dallo script dumper (se configurato) e il suo output.
    *   L'area "Parsed JSON Output" visualizzerà la rappresentazione JSON strutturata della variabile dumpata.
    *   I pulsanti "Save as JSON" e "Save as CSV" diventeranno attivi.
10. **Continua/Ferma:**
    *   Clicca **3. Continue** per riprendere l'esecuzione del programma.
    *   Clicca **Stop GDB** per terminare la sessione GDB e il programma.
11. **Salvataggio Dati:**
    *   Dopo aver dumpato una variabile, clicca **Save as JSON** o **Save as CSV** per salvare i dati visualizzati su un file.

Congratulazioni! Hai completato la tua prima sessione di debug manuale.

---

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

La finestra principale è l'hub centrale per interagire con Cpp-Python GDB Debug Helper.

**(Uno screenshot della finestra principale con le aree annotate sarebbe ideale qui se questo fosse un documento ricco)**

**4.1 Barra dei Menu**

*   **Options:**
    *   **Configure Application...:** Apre la Finestra di Configurazione (vedi Sezione 5).
    *   **Exit:** Chiude l'applicazione.
*   **Profiles:**
    *   **Manage Profiles...:** Apre la Finestra Gestore Profili (vedi Sezione 7).

**4.2 Area Stato Configurazione Critica**

Situata in alto, quest'area visualizza lo stato di:

*   **GDB Executable:** Mostra il percorso dell'eseguibile GDB e se è stato trovato ("OK") o meno.
*   **Dumper Script:** Mostra il percorso dello script `gdb_dumper.py` e il suo stato di caricamento ("OK", "Loaded", "Not Found", "Load Failed", o "Not Configured").
*   **Pulsante Configure...:** Una scorciatoia per aprire la Finestra di Configurazione.

**4.3 Pannello Modalità (Schede)**

Questa sezione utilizza un'interfaccia a schede per passare tra diverse modalità operative:

*   **Scheda Manual Debug:** (Vedi Sezione 6)
    *   Campi per impostare l'eseguibile target, i parametri del programma, la locazione del breakpoint e la variabile da dumpare.
    *   Pulsanti di controllo per avviare GDB, impostare breakpoint, eseguire/continuare, dumpare variabili e fermare GDB.
    *   Pulsanti per salvare i dati dumpati.
*   **Scheda Automated Profile Execution:** (Vedi Sezione 9)
    *   Dropdown per selezionare un profilo di debug preconfigurato.
    *   Pulsanti per eseguire o fermare il profilo selezionato.
    *   Visualizzazione dello stato e barra di progresso per l'esecuzione del profilo.
    *   Una vista ad albero che elenca i file prodotti durante l'esecuzione del profilo.
    *   Pulsante per aprire la cartella di output dell'ultima esecuzione.

**4.4 Area Output e Log (Schede)**

Quest'area in basso visualizza vari output:

*   **Scheda GDB Raw Output:** Mostra l'output testuale grezzo, non filtrato, dal processo GDB. Utile per diagnostica e per comprendere il comportamento di GDB.
*   **Scheda Parsed JSON Output:** Visualizza i dati JSON formattati (pretty-printed) risultanti da un'azione "Dump Variable" (in modalità Debug Manuale) o da azioni durante un'Esecuzione Profilo. Se si verifica un errore durante il dump, potrebbe mostrare una struttura di errore.
*   **Scheda Application Log:** Visualizza i messaggi di log generati dall'applicazione Cpp-Python GDB Debug Helper stessa (es. aggiornamenti di stato, avvisi, errori).

**4.5 Barra di Stato**

Situata nella parte inferiore della finestra, la barra di stato fornisce brevi messaggi sullo stato corrente dell'applicazione o sull'ultima operazione eseguita (es. "Ready", "GDB session active", "Breakpoint hit", "Error...").

---

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

La Finestra di Configurazione ti permette di personalizzare varie impostazioni per Cpp-Python GDB Debug Helper. Le modifiche apportate qui vengono salvate in un file di configurazione JSON e persistono tra le sessioni.

**(Uno screenshot della Finestra di Configurazione con le schede sarebbe utile qui)**

La finestra è organizzata in diverse schede:

**5.1 Scheda Paths (Percorsi)**

Questa scheda serve per impostare percorsi di file essenziali.

*   **GDB Executable:**
    *   **Campo:** Specifica il percorso completo dell'eseguibile GDB (es. `C:\MinGW\bin\gdb.exe` o `/usr/bin/gdb`).
    *   **Pulsante Browse...:** Apre una finestra di dialogo per aiutarti a localizzare e selezionare l'eseguibile GDB.
    *   *Questo percorso è cruciale per il funzionamento dell'applicazione.*
*   **GDB Dumper Script:**
    *   **Campo:** Specifica il percorso completo dello script `gdb_dumper.py`. Questo script fa parte della distribuzione di Cpp-Python GDB Debug Helper e si trova tipicamente nella sua sottodirectory `core`.
    *   **Pulsante Browse...:** Apre una finestra di dialogo per selezionare lo script `gdb_dumper.py`.
    *   *Questo script è necessario per la funzionalità avanzata di dump JSON. Se non configurato, o se lo script non riesce a caricarsi, la funzionalità "Dump Variable" (e il dump dei profili automatizzati) sarà limitata o potrebbe riportare errori.*

**5.2 Scheda Timeouts (secondi)**

Questa scheda ti permette di configurare i timeout per varie operazioni di GDB. Impostare timeout appropriati è importante per prevenire che l'applicazione si blocchi indefinitamente se GDB non risponde o un'operazione richiede più tempo del previsto. Tutti i valori sono in secondi.

*   **GDB Start:** Timeout per l'avvio del processo GDB e la sua risposta ai comandi. (Predefinito: 30s)
*   **GDB Command:** Timeout predefinito per comandi GDB generici (es. impostazione di un breakpoint, comandi GDB interni). (Predefinito: 30s)
*   **Program Run/Continue:** Timeout per i comandi GDB `run` o `continue`. Questo dovrebbe generalmente essere più lungo, poiché dipende da quanto tempo impiega il tuo programma a raggiungere un breakpoint o a completarsi. (Predefinito: 120s)
*   **Dump Variable:** Timeout specifico per l'operazione `dump_json`, che coinvolge GDB nell'esecuzione dello script dumper Python. (Predefinito: 60s)
*   **Kill Program:** Timeout affinché GDB confermi la terminazione del programma tramite il comando `kill`. (Predefinito: 20s)
*   **GDB Quit:** Timeout affinché GDB termini correttamente dopo un comando `quit`. (Predefinito: 10s)

*L'input per questi campi avviene tipicamente tramite Spinbox, che permettono un facile incremento/decremento di valori interi.*

**5.3 Scheda Dumper Options (Opzioni Dumper)**

Queste impostazioni controllano il comportamento dello script `gdb_dumper.py` quando serializza strutture dati C/C++ in JSON. Queste opzioni aiutano a gestire le prestazioni e la dimensione dell'output per variabili molto grandi o complesse.

*   **Max Array Elements:** Il numero massimo di elementi da dumpare da array, `std::vector`, o altri contenitori simili a liste. (Predefinito: 100)
*   **Max Recursion Depth:** La profondità massima che il dumper attraverserà durante la serializzazione di strutture annidate o puntatori (es. liste concatenate, alberi). Aiuta a prevenire loop infiniti con strutture dati cicliche. (Predefinito: 10)
*   **Max String Length:** Il numero massimo di caratteri da dumpare da una stringa C-style o `std::string`. Le stringhe più lunghe verranno troncate. (Predefinito: 2048)

*Anche l'input per questi campi avviene tipicamente tramite Spinbox.*

**5.4 Salvataggio e Annullamento**

*   **Pulsante Save:**
    *   Valida le impostazioni correnti in tutte le schede.
    *   Se valide, applica le modifiche al gestore interno delle impostazioni dell'applicazione.
    *   Salva tutte le impostazioni nel file di configurazione JSON.
    *   Chiude la Finestra di Configurazione.
*   **Pulsante Cancel:**
    *   Scarta qualsiasi modifica apportata nella Finestra di Configurazione.
    *   Chiude la Finestra di Configurazione.
*   **Pulsante 'X' della Finestra (Chiudi):** Tipicamente si comporta come il pulsante "Cancel".

---

### 6. Modalità Debug Manuale

La scheda "Manual Debug" fornisce un modo interattivo per controllare una sessione GDB per il debug della tua applicazione C/C++.

**(Uno screenshot della scheda Manual Debug con gli elementi chiave evidenziati sarebbe utile)**

**6.1 Impostare Eseguibile Target e Parametri**

*   **Campo Target Executable:**
    *   Inserisci il percorso completo dell'eseguibile C/C++ che vuoi debuggare.
    *   In alternativa, clicca il pulsante **Browse...** per aprire una finestra di dialogo e selezionare l'eseguibile.
    *   L'applicazione ricorderà l'ultimo percorso eseguibile utilizzato.
*   **Campo Program Parameters:**
    *   Se il tuo programma target richiede argomenti da riga di comando, inseriscili qui.
    *   Questi parametri verranno passati al tuo programma quando viene eseguito il comando `run` di GDB.

**6.2 Impostare Locazione Breakpoint**

*   **Campo Breakpoint Location:**
    *   Specifica dove GDB dovrebbe interrompere l'esecuzione del tuo programma. Esempi:
        *   `main` (nome funzione)
        *   `MiaClasse::mioMetodo` (metodo di classe C++)
        *   `nomefile.cpp:123` (file e numero di linea)
        *   `0x4005A0` (indirizzo di memoria, se noto)
    *   Un piccolo testo di aiuto sotto il campo fornisce esempi comuni.

**6.3 Impostare Variabile/Espressione da Dumpare**

*   **Campo Variable/Expression:**
    *   Inserisci il nome della variabile C/C++ o un'espressione GDB valida il cui valore vuoi ispezionare quando un breakpoint viene raggiunto. Esempi:
        *   `miaVariabileLocale`
        *   `var_globale`
        *   `*puntatore_a_struttura`
        *   `mio_oggetto.membro_dati`
        *   `mio_vettore`
        *   `(char*)qualche_indirizzo` (casting di un indirizzo per visualizzare la memoria)

**6.4 Pulsanti di Controllo Sessione**

Questi pulsanti controllano il flusso della sessione di debug GDB:

1.  **Pulsante 1. Start GDB:**
    *   **Azione:** Inizializza e avvia una sessione GDB, caricando il "Target Executable" specificato. Tenta anche di eseguire lo "GDB Dumper Script" se configurato.
    *   **Stato:** Abilitato se GDB è configurato e nessuna sessione è attiva. Diventa disabilitato una volta avviata una sessione.
    *   **Output:** I messaggi di avvio di GDB, lo stato di sourcing dello script dumper e le informazioni sul caricamento dei simboli appaiono nell'area "GDB Raw Output".
2.  **Pulsante 2. Set Breakpoint:**
    *   **Azione:** Invia un comando a GDB per impostare un breakpoint alla "Breakpoint Location" specificata.
    *   **Stato:** Abilitato dopo che GDB è stato avviato con successo. Il testo del pulsante si aggiorna per riflettere il breakpoint impostato (es. "BP: main (Set)").
    *   **Output:** La conferma o il messaggio di errore di GDB riguardante il breakpoint viene mostrato in "GDB Raw Output".
3.  **Pulsante 3. Run Program / 3. Continue:**
    *   **Azione (Run Program):** Se il programma non è ancora stato avviato nella sessione corrente, questo pulsante invia il comando `run` a GDB (insieme a eventuali "Program Parameters").
    *   **Azione (Continue):** Se il programma è attualmente fermo (es. a un breakpoint), questo pulsante invia il comando `continue` a GDB.
    *   **Stato:** Abilitato dopo che un breakpoint è stato impostato con successo (o se GDB è in uno stato in cui l'esecuzione è possibile).
    *   **Output:** L'output del programma e i messaggi di GDB (come raggiungimento di breakpoint o stato di uscita del programma) appaiono in "GDB Raw Output".
4.  **Pulsante 4. Dump Variable:**
    *   **Azione:** Quando il programma è in pausa a un breakpoint, questo pulsante comanda a GDB (tramite lo script dumper) di valutare la "Variable/Expression" e serializzare il suo stato in JSON.
    *   **Stato:** Abilitato quando il programma è fermo a un breakpoint e lo script dumper è stato caricato con successo.
    *   **Output:**
        *   "GDB Raw Output": Mostra la comunicazione con lo script dumper.
        *   "Parsed JSON Output": Visualizza il risultato JSON strutturato del dump.
5.  **Pulsante Stop GDB:**
    *   **Azione:** Termina la sessione GDB corrente. Se il programma target è in esecuzione, tenta prima di `kill`-arlo, poi invia il comando `quit` a GDB.
    *   **Stato:** Abilitato quando una sessione GDB è attiva.
    *   **Output:** Le risposte di GDB ai comandi `kill` e `quit` appaiono in "GDB Raw Output". I controlli della GUI vengono resettati al loro stato pre-sessione.

**6.5 Interpretare l'Output Raw GDB**

La scheda "GDB Raw Output" visualizza tutta la comunicazione testuale con il sottoprocesso GDB. Questo include:

*   Messaggi di benvenuto e prompt di GDB `(gdb)`.
*   Risposte ai comandi (es. conferme di breakpoint, messaggi di errore).
*   Output dal programma target (il suo `stdout` e `stderr`).
*   Messaggi dallo script GDB Python dumper durante la sua esecuzione (questi sono prefissati con `GDB_DUMPER_SCRIPT:` o loggati su `gdb_dumper_debug.log`).
*   Messaggi di stato come `*stopped,reason="breakpoint-hit",...` quando in modalità MI (meno rilevanti per questa scheda, ma potrebbero apparire se GDB invia output misto).

**6.6 Interpretare l'Output JSON Parsato**

La scheda "Parsed JSON Output" mostra il risultato dell'azione "Dump Variable", formattato per la leggibilità.

*   **Dump Riuscito:** Vedrai una rappresentazione JSON della struttura e dei valori della variabile.
    *   Tipi semplici (int, float, bool) appaiono come i loro equivalenti JSON.
    *   I puntatori potrebbero essere mostrati come il loro indirizzo, o se dereferenziati dal dumper, il contenuto a cui puntano (entro i limiti di ricorsione). I puntatori nulli sono spesso `null`.
    *   Array/Vettori mostrano i loro elementi (fino a `Max Array Elements`).
    *   Strutture/Classi mostrano i loro membri.
    *   Viene mostrato il contenuto di `std::string`.
    *   Stringhe speciali come `<optimized_out>`, `<max_recursion_depth_reached>`, `<cyclic_or_shared_ref_to_type_...>` indicano limitazioni o condizioni specifiche incontrate dal dumper.
*   **Errore Script Dumper:** Se lo script `gdb_dumper.py` stesso incontra un problema o GDB non può valutare l'espressione, questa scheda mostrerà spesso un oggetto JSON con una chiave `"_gdb_tool_error"` o `"gdb_script_error"`, fornendo dettagli sul problema. Esempio:
    ```json
    {
      "_gdb_tool_error": "GDB evaluation error: No symbol \"variabile_inesistente\" in current context.",
      "expression": "variabile_inesistente",
      "details": "The expression could not be evaluated by GDB..."
    }
    ```

**6.7 Salvare i Dati Dumpati (JSON/CSV)**

Dopo un dump di variabile riuscito, `last_dumped_data` viene memorizzato internamente.

*   **Pulsante Save as JSON:**
    *   Abilitato se `last_dumped_data` è valido.
    *   Apre una finestra di dialogo "Salva con nome", permettendoti di salvare i dati JSON grezzi (come visualizzati nella scheda "Parsed JSON Output") in un file `.json`.
*   **Pulsante Save as CSV:**
    *   Abilitato se `last_dumped_data` è valido.
    *   Apre una finestra di dialogo "Salva con nome". Lo strumento tenta di convertire `last_dumped_data` in un formato CSV tabellare.
        *   Se i dati sono una lista di dizionari, le chiavi del primo dizionario diventano le intestazioni CSV.
        *   Se è un singolo dizionario, viene trattato come un CSV a una riga.
        *   Se è una lista di valori primitivi o un singolo primitivo, viene salvato sotto una colonna "value".
    *   Questo è più utile per dumpare array di strutture semplici o dati omogenei. JSON annidati complessi potrebbero non tradursi perfettamente in un CSV piatto.

---

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

La finestra Gestore Profili è dove crei, configuri e organizzi i profili di debug automatizzati. Ogni profilo incapsula le impostazioni per il debug di un specifico eseguibile target con un insieme definito di azioni.

**(Uno screenshot della finestra Gestore Profili, evidenziando la lista dei profili, il form dei dettagli, la sezione di analisi e la lista delle azioni, sarebbe molto utile qui.)**

**7.1 Panoramica della Finestra Gestore Profili**

La finestra è generalmente divisa in alcune aree chiave:

*   **Pannello Sinistro (Lista Profili):**
    *   **Listbox Profili:** Visualizza tutti i profili di debug salvati per nome. Selezionando un profilo qui si caricano i suoi dettagli nel pannello destro.
    *   **Pulsanti di Controllo (New, Duplicate, Delete):** Per gestire la lista dei profili.
*   **Pannello Destro (Configurazione Profilo):**
    *   **Form Dettagli Profilo:** Campi per modificare il nome del profilo selezionato, il percorso dell'eseguibile target e i parametri del programma.
    *   **Stato e Controllo Analisi Simboli:** Visualizza informazioni sull'ultima analisi dei simboli eseguita per l'eseguibile target corrente (se presente) e permette di avviare una nuova analisi.
    *   **Riepilogo Simboli Analizzati:** Mostra i conteggi di funzioni, variabili globali, tipi e file sorgente trovati nell'ultima analisi, con pulsanti "View..." per ispezionarli.
    *   **Area Azioni di Debug:** Una listbox che mostra la sequenza di azioni di debug definite per il profilo selezionato, con pulsanti per aggiungere, modificare o rimuovere azioni.
*   **Pulsanti Inferiori (Save All Changes, Close):**
    *   **Save All Changes:** Salva tutte le modifiche apportate a qualsiasi profilo e alla lista dei profili stessa nel file di impostazioni dell'applicazione.
    *   **Close:** Chiude la finestra Gestore Profili. Chiede di salvare se ci sono modifiche non salvate.

**7.2 Gestione dei Profili**

*   **Selezione di un Profilo:** Clicca sul nome di un profilo nella "Listbox Profili" a sinistra. I suoi dettagli e le sue azioni verranno caricati nel pannello destro per la visualizzazione e la modifica.
*   **Pulsante New:**
    *   Crea un nuovo profilo vuoto con impostazioni predefinite (es. "New Profile", azioni vuote).
    *   Il nuovo profilo viene aggiunto alla lista, selezionato, e il suo campo nome riceve il focus per la modifica immediata.
*   **Pulsante Duplicate:**
    *   Abilitato quando un profilo è selezionato.
    *   Crea una copia del profilo attualmente selezionato. Il profilo duplicato avrà un nome come "NomeOriginale_copy".
    *   Il nuovo duplicato viene aggiunto alla lista e selezionato.
*   **Pulsante Delete:**
    *   Abilitato quando un profilo è selezionato.
    *   Chiede conferma, quindi rimuove il profilo selezionato dalla lista.
*   **Pulsante Save All Changes:**
    *   Questo è il modo principale per persistere il tuo lavoro all'interno del Gestore Profili.
    *   Valida tutti i profili (es. per nomi univoci) e poi scrive l'intera lista di profili (e le loro configurazioni) nel file di impostazioni JSON dell'applicazione.
    *   *Si raccomanda di salvare frequentemente, specialmente dopo modifiche significative.*

**7.3 Modifica Dettagli Profilo**

Quando un profilo è selezionato, i suoi dettagli base possono essere modificati nel form "Profile Details":

*   **Profile Name:**
    *   Un nome univoco per il profilo (es. "Debug MiaLibreria FeatureX", "ReleaseMode SanityCheck").
    *   Questo campo è modificabile. Assicurati che i nomi siano univoci tra tutti i profili.
*   **Target Executable:**
    *   Il percorso completo dell'eseguibile C/C++ che questo profilo debuggherà.
    *   Usa il pulsante **Browse...** per selezionare il file.
    *   Modificare questo percorso potrebbe invalidare un'analisi dei simboli precedente per questo profilo.
*   **Program Parameters:**
    *   Argomenti da riga di comando da passare all'eseguibile target quando viene eseguito con questo profilo.

*Qualsiasi modifica a questi campi segna il form del profilo corrente come modificato. Queste modifiche sono temporaneamente mantenute nella finestra e vengono scritte nella struttura dati interna del profilo solo quando cambi profilo (dopo una richiesta) o salvi esplicitamente lo stato del form corrente prima di certe operazioni (es. duplicazione, eliminazione, o avvio dell'analisi dei simboli).*

**7.4 Analisi dei Simboli**

Questa sezione ti aiuta a comprendere e gestire le informazioni sui simboli associate all'eseguibile target del profilo. Lo strumento usa l'Interfaccia Macchina (MI) di GDB per un'estrazione efficiente dei simboli.

*   **Area Stato e Controllo Analisi Simboli:**
    *   **Target in Form:** Visualizza il nome dell'eseguibile attualmente specificato nel campo "Target Executable".
    *   **Last Analysis on File:** Mostra il nome dell'eseguibile per il quale è stata eseguita l'analisi dei simboli *memorizzata*.
    *   **File Timestamp (at analysis):** Il timestamp di modifica dell'eseguibile quando è stato analizzato l'ultima volta.
    *   **Analysis Date:** Quando è stata eseguita l'analisi memorizzata.
    *   **Saved Checksum:** Il checksum MD5 dell'eseguibile al momento dell'ultima analisi.
    *   **Current Form Exe Checksum:** Il checksum MD5 dell'eseguibile attualmente specificato nel campo "Target Executable".
    *   **Etichetta di Stato (es. "Up-to-date", "TARGET CHANGED", "EXECUTABLE CHANGED", "Not performed"):** Fornisce una valutazione rapida della rilevanza dell'analisi memorizzata rispetto all'eseguibile target corrente nel form.
        *   **Up-to-date:** L'analisi memorizzata corrisponde all'eseguibile corrente.
        *   **TARGET CHANGED:** Il percorso dell'eseguibile nel form è diverso da quello che è stato analizzato. Una nuova analisi è altamente raccomandata.
        *   **EXECUTABLE CHANGED:** Il percorso dell'eseguibile è lo stesso, ma il suo contenuto (checksum) è cambiato. Una nuova analisi è richiesta.
        *   **Not performed:** Nessun dato di analisi dei simboli è memorizzato per questo profilo.
    *   **Pulsante Analyse Target Symbols:**
        *   Abilitato se un eseguibile target valido è specificato nel form e GDB è configurato.
        *   Avvia una nuova analisi dei simboli per l'eseguibile attualmente specificato nel campo "Target Executable".
        *   Apparirà una finestra di dialogo di progresso che mostra i passaggi dell'analisi.
        *   Al completamento con successo, i dati dei simboli estratti (funzioni, globali, tipi, sorgenti, checksum, timestamp) vengono memorizzati all'interno dei *dati del profilo attualmente selezionato in memoria*.
        *   *Devi cliccare "Save All Changes" per persistere questi nuovi dati di analisi nel file di impostazioni.*

*   **Area Riepilogo Simboli Analizzati:**
    *   Visualizza i conteggi di **Funzioni**, **Globali**, **Tipi**, e **File Sorgente** trovati nell'analisi *memorizzata* per il profilo selezionato.
    *   **Pulsanti View...:** Accanto a ogni conteggio, questi pulsanti (abilitati se i conteggi > 0 e l'analisi è considerata rilevante) aprono una `SymbolListViewerDialog` che ti permette di sfogliare la lista dettagliata dei rispettivi simboli.

**7.5 Gestione Azioni di Debug**

Per un profilo selezionato, puoi definire una sequenza di azioni di debug. Queste azioni vengono eseguite dal `ProfileExecutor` quando il profilo viene eseguito.

*   **Listbox Azioni di Debug:**
    *   Visualizza un riepilogo di ogni azione definita per il profilo corrente (es. "BP: main (Vars:1,Fmt:json,Cont:Yes)").
    *   Selezionare un'azione in questa listbox abilita i pulsanti "Edit..." e "Remove".
*   **Pulsante Add...:**
    *   Abilitato se un profilo è selezionato.
    *   Apre la **Finestra Editor Azioni** (vedi Sezione 8) per definire una nuova azione di debug. La nuova azione viene aggiunta alla lista per il profilo corrente.
*   **Pulsante Edit...:**
    *   Abilitato se un'azione è selezionata nella "Listbox Azioni di Debug".
    *   Apre la **Finestra Editor Azioni** precompilata con i dati dell'azione selezionata, permettendoti di modificarla.
*   **Pulsante Remove:**
    *   Abilitato se un'azione è selezionata.
    *   Chiede conferma e quindi rimuove l'azione selezionata dal profilo corrente.

*Le modifiche alle azioni (aggiunta, modifica, rimozione) segnano il profilo come modificato e richiedono l'uso di "Save All Changes" per essere persistite.*

---

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

La Finestra Editor Azioni è una finestra di dialogo utilizzata per definire o modificare i dettagli di una singola azione di debug all'interno di un profilo.

**(Uno screenshot della Finestra Editor Azioni sarebbe molto utile qui.)**

**8.1 Locazione Breakpoint**

*   **Campo:** Inserisci la locazione dove GDB dovrebbe impostare un breakpoint per questa azione (es. `main`, `file.cpp:123`, `MiaClasse::mioMetodo`).
*   **Pulsanti di Assistenza:**
    *   **Pulsante Funcs...:**
        *   Apre una `SymbolListViewerDialog` (o `FunctionSelectorDialog`).
        *   Se i dati dell'analisi dei simboli sono disponibili per il target del profilo, elenca le funzioni da quell'analisi.
        *   Altrimenti, tenta una *query GDB live* per elencare le funzioni dall'eseguibile target corrente (ciò richiede che GDB e il target siano validi).
        *   Selezionando una funzione si popola il campo "Breakpoint Location".
    *   **Pulsante Files...:**
        *   Abilitato se sono disponibili dati di analisi dei simboli contenenti informazioni sui file sorgente.
        *   Apre una `SymbolListViewerDialog` che elenca i file sorgente noti a GDB.
        *   Selezionando un file si popola il campo "Breakpoint Location" con il percorso del file, pronto per aggiungere un numero di linea (es. `percorso/a/file.cpp:`).

**8.2 Variabili da Dumpare**

*   **Area di Testo Scrolled:** Inserisci le variabili C/C++ o le espressioni GDB da dumpare quando il breakpoint di questa azione viene raggiunto.
    *   **Inserisci una variabile/espressione per riga.**
*   **Pulsanti di Assistenza:**
    *   **Pulsante Globals...:**
        *   Abilitato se sono disponibili dati di analisi dei simboli contenenti informazioni sulle variabili globali.
        *   Apre una `SymbolListViewerDialog` che permette la selezione multipla di variabili globali.
        *   Le globali selezionate vengono aggiunte all'area di testo.
    *   **Pulsante Scope Vars...:**
        *   Abilitato se una "Breakpoint Location" è impostata, GDB è configurato, e un eseguibile target valido è specificato per il profilo.
        *   **Azione:** Questa è una funzionalità potente. Avvia temporaneamente una sessione GDB, imposta il breakpoint specificato, esegue il programma (usando i "Program Parameters" del profilo) finché il breakpoint non viene raggiunto, e quindi elenca le variabili locali e gli argomenti attualmente nello scope.
        *   Una finestra di dialogo di progresso mostra lo stato di questa ispezione live.
        *   Una volta completata, appare una `SymbolListViewerDialog`, che permette la selezione multipla di queste variabili di scope.
        *   Le variabili di scope selezionate vengono aggiunte all'area di testo.
        *   I risultati dell'ispezione dello scope vengono cachati per la sessione per velocizzare richieste successive per lo stesso breakpoint e parametri.
    *   **Pulsante Test Action...:** (Attualmente un placeholder, segnato come disabilitato) Inteso per implementazione futura per validare l'azione direttamente con GDB.

**8.3 Formato Output**

*   **Combobox (Dropdown):** Scegli il formato per i dati dumpati.
    *   **json:** Salva i dati in un formato JSON strutturato e leggibile dall'uomo. Questo è il predefinito e generalmente raccomandato per dati complessi.
    *   **csv:** Tenta di salvare i dati in formato CSV (Comma Separated Values). Ideale per liste di strutture semplici o dati primitivi.

**8.4 Directory Output**

*   **Campo:** Specifica la directory dove verranno salvati i file di output per questa azione.
*   **Pulsante Browse...:** Apre una finestra di dialogo per la selezione della directory.
*   *Quando un profilo viene eseguito, una sottodirectory con timestamp (es. `NomeProfilo_AAAAMMGG_HHMMSS`) viene creata all'interno di questa directory specificata per memorizzare tutti i file prodotti da quella particolare esecuzione.*

**8.5 Pattern Nome File**

*   **Campo:** Definisci un pattern per generare i nomi dei file di output.
*   **Placeholder Disponibili:**
    *   `{profile_name}`: Il nome del profilo in esecuzione (sanificato per l'uso nei nomi dei file).
    *   `{app_name}`: Il nome base dell'eseguibile target (es. `mioprogramma` da `/percorso/a/mioprogramma.exe`).
    *   `{breakpoint}`: La stringa "Breakpoint Location" per questa azione (sanificata).
    *   `{variable}`: Il nome della variabile o espressione dumpata (sanificata).
    *   `{timestamp}`: Un timestamp dettagliato (es. `AAAAMMGG_HHMMSS_mmm`).
    *   `{format}`: Il formato di output selezionato (es. `json`, `csv`).
*   **Esempio:** `{profile_name}_{breakpoint}_{variable}_{timestamp}.{format}`
*   L'estensione del file (`.json` o `.csv`) viene aggiunta automaticamente se non inclusa tramite il placeholder `{format}` o manualmente.

**8.6 Opzione "Continue execution after dump"**

*   **Checkbox:**
    *   **Selezionata (Predefinito):** Dopo che il breakpoint di questa azione è stato raggiunto e tutte le variabili specificate sono state dumpate, GDB eseguirà automaticamente un comando `continue`, e il programma riprenderà l'esecuzione fino al prossimo breakpoint (o fino alla sua terminazione/crash).
    *   **Non Selezionata:** Dopo che il breakpoint di questa azione è stato raggiunto e le variabili sono state dumpate, il programma rimarrà in pausa in GDB. L'esecuzione del profilo si fermerà effettivamente a questo punto per questo specifico percorso di esecuzione. Utile se vuoi ispezionare GDB manualmente dopo un dump specifico o se questo è l'ultimo punto di interesse.

**8.7 Salvataggio e Annullamento dell'Azione**

*   **Pulsante OK:** Valida i dati dell'azione. Se validi, restituisce i dati di configurazione dell'azione alla finestra Gestore Profili, che quindi aggiorna la sua lista interna di azioni per il profilo.
*   **Pulsante Cancel (o 'X' della Finestra):** Scarta le modifiche e chiude la Finestra Editor Azioni senza restituire alcun dato.

---

### 9. Modalità Esecuzione Profilo Automatizzato

La scheda "Automated Profile Execution" nella finestra principale ti permette di eseguire i profili di debug che hai configurato nel Gestore Profili. Questo automatizza il processo di impostazione dei breakpoint, esecuzione del programma e dump delle variabili specificate.

**(Uno screenshot della scheda Automated Profile Execution, che mostra la selezione del profilo, i pulsanti run/stop, lo stato, la barra di progresso e il log dei file prodotti, sarebbe molto illustrativo qui.)**

**9.1 Selezione di un Profilo**

*   **Dropdown Selezione Profilo (Combobox):**
    *   Questo dropdown elenca tutti i profili attualmente salvati nelle impostazioni dell'applicazione (come configurato tramite il Gestore Profili).
    *   Scegli il profilo che desideri eseguire da questa lista.
    *   Il pulsante "Run Profile" sarà abilitato se un profilo è selezionato e nessuna sessione GDB (manuale o altro profilo) è attualmente attiva.

**9.2 Esecuzione del Profilo**

*   **Pulsante Run Profile:**
    *   Una volta selezionato un profilo, clicca questo pulsante per avviare la sua esecuzione.
    *   **Pre-controlli:**
        *   Assicura che nessun'altra sessione GDB (manuale o altro profilo) sia attualmente in esecuzione.
        *   Verifica che il percorso dell'eseguibile GDB sia valido.
        *   Verifica che l'eseguibile target specificato nel profilo selezionato esista.
    *   **Azioni durante l'esecuzione:**
        *   La GUI passerà a uno stato di "esecuzione":
            *   Il pulsante "Run Profile" e il dropdown di selezione del profilo diventano disabilitati.
            *   Il pulsante "Stop Profile" diventa abilitato.
            *   Le voci di menu ("Options", "Profiles") e i controlli di debug manuale diventano disabilitati per prevenire conflitti.
            *   La "Visualizzazione Stato" (es. `AVVIO PROFILO 'NomeProfilo' IN CORSO...`) si aggiorna per mostrare la fase corrente.
            *   La "Barra di Progresso" (se visibile) diventa attiva (modalità indeterminata).
            *   Il "Log File Prodotti" viene cancellato.
        *   Un'istanza di `ProfileExecutor` viene creata in un thread separato per gestire l'interazione con GDB senza bloccare la GUI.
        *   L'esecutore:
            *   Avvierà GDB con l'eseguibile target del profilo.
            *   Eseguirà lo script dumper (se configurato nelle impostazioni generali).
            *   Imposterà tutti i breakpoint definiti nelle azioni del profilo.
            *   Eseguirà il programma con i parametri specificati dal profilo.
            *   Quando un breakpoint viene raggiunto:
                *   Identificherà quale/i azione/i corrisponde/ono a quel breakpoint.
                *   Per ogni azione rilevante, dumperà le variabili specificate nel formato e nella directory di output specificati, usando il pattern per il nome del file.
                *   Registrerà ogni evento di produzione file nella vista ad albero "Log File Prodotti".
                *   Deciderà se continuare (`continue`) l'esecuzione in base all'impostazione "Continue after dump" dell'azione.
            *   Aggiornerà le schede "GDB Raw Output" e "Parsed JSON Output" in tempo reale.
            *   Fornirà aggiornamenti di stato all'etichetta "Visualizzazione Stato".

**9.3 Monitoraggio Stato Esecuzione e Barra di Progresso**

*   **Etichetta Visualizzazione Stato (es. "AVVIO PROFILO 'NomeProfilo' IN CORSO..."):**
    *   Questa grande etichetta in cima all'area "Log File Prodotti" fornisce aggiornamenti testuali sul progresso dell'esecuzione del profilo (es. "Avvio GDB...", "Impostazione breakpoint...", "Esecuzione programma...", "Breakpoint 'main' raggiunto, dump di 'var1'...", "Programma terminato.").
*   **Barra di Progresso:**
    *   Situata sotto l'etichetta di visualizzazione stato.
    *   Funziona in modalità indeterminata mentre il profilo è attivo, indicando che è in corso un'elaborazione in background. Si ferma una volta che l'esecuzione del profilo termina o viene interrotta.

**9.4 Interruzione di un Profilo in Esecuzione**

*   **Pulsante Stop Profile:**
    *   Diventa abilitato quando un profilo è in esecuzione.
    *   Cliccando questo pulsante si segnala al `ProfileExecutor` di tentare di fermare graziosamente la sessione GDB corrente e terminare l'esecuzione del profilo.
    *   L'esecutore cercherà di `kill`-are il programma target e poi di `quit`-are GDB.
    *   La visualizzazione stato si aggiornerà a "Richiesta interruzione profilo...".
    *   Il pulsante diventa nuovamente disabilitato dopo che la richiesta di interruzione è stata elaborata.
    *   L'esecuzione del profilo si concluderà quindi, e la GUI tornerà a uno stato di inattività.

**9.5 Interpretare il "Log File Prodotti"**

Questa vista ad albero si aggiorna dinamicamente mentre il profilo viene eseguito, elencando ogni dump di variabile che risulta in un file. Ogni riga fornisce:

*   **Time:** Timestamp di quando il file di dump è stato prodotto.
*   **Breakpoint Spec:** La stringa di locazione del breakpoint come definita nell'azione (es. `main`, `file.cpp:10`).
*   **Variable:** Il nome della variabile o espressione che è stata dumpata.
*   **File Produced:** Il nome base del file di output creato (es. `ProfiloX_main_varA_timestamp.json`).
*   **Status:** "Success" se il dump e il salvataggio sono andati a buon fine, o un indicatore di errore (es. "Failed", "GDB Tool Error", "Save Error").
*   **Details:** Informazioni aggiuntive, specialmente in caso di errori (es. il messaggio di errore specifico da GDB o dallo script dumper).

**9.6 Aprire la Cartella di Output**

*   **Pulsante Open Output Folder:**
    *   Diventa abilitato dopo che l'esecuzione di un profilo è completata e se una directory di output è stata creata e utilizzata con successo durante quella esecuzione.
    *   Cliccando questo pulsante si tenta di aprire la directory di output principale per l'ultima esecuzione del profilo completata* nell'esplora file predefinito del sistema. Questa directory di solito contiene una sottodirectory con timestamp specifica per quella esecuzione.

---

### 10. Risoluzione Problemi / FAQ

**D: GDB non trovato, o "Critical Configuration Status" mostra errori sul percorso GDB.**
**R:**
1.  Assicurati che GDB sia installato sul tuo sistema.
2.  Vai su **Options > Configure Application... > Scheda Paths**.
3.  Usa il pulsante "Browse..." per impostare il percorso completo corretto del tuo eseguibile `gdb.exe` (o `gdb`).
4.  Clicca "Save".

**D: Lo stato dello script dumper è "Not Found" o "Load Failed".**
**R:**
1.  Lo script `gdb_dumper.py` dovrebbe trovarsi nella sottodirectory `core` da dove stai eseguendo Cpp-Python GDB Debug Helper.
2.  Vai su **Options > Configure Application... > Scheda Paths**.
3.  Imposta il percorso "GDB Dumper Script" a questo file `gdb_dumper.py`.
4.  Se è "Load Failed" anche con un percorso corretto:
    *   Controlla l'"GDB Raw Output" quando avvii una sessione GDB (manuale o profilo) per eventuali traceback Python o errori GDB relativi al sourcing dello script.
    *   Esamina il file `gdb_dumper_debug.log`. Questo log è creato da `gdb_dumper.py` stesso. La sua posizione è loggata da `gdb_dumper.py` all'avvio (solitamente nella directory home dell'utente o accanto a `gdb_dumper.py`). Questo log contiene diagnostica dettagliata dall'interno dell'ambiente Python di GDB.

**D: L'output di GDB mostra "No debugging symbols found."**
**R:**
1.  Ciò significa che la tua applicazione C/C++ target non è stata compilata con informazioni di debug, o i simboli sono stati rimossi (stripped).
2.  Ricompila la tua applicazione usando il flag `-g` (per GCC/G++ o Clang). Esempio: `g++ -g -o mioprogramma mioprogramma.cpp`.
3.  Evita ottimizzazioni aggressive (`-O2`, `-O3`) che potrebbero interferire con il debug. Considera `-Og`.
4.  Se i simboli non vengono ancora trovati, assicurati di stare debuggando l'eseguibile corretto e appena compilato.
5.  Cpp-Python GDB Debug Helper tipicamente interromperà una sessione GDB se non vengono trovati simboli, poiché le capacità di debug sono severamente limitate.

**D: Il dump di variabili risulta in `"_gdb_tool_error"` o `"gdb_script_error"` nell'output JSON.**
**R:**
1.  Questo indica che si è verificato un errore o all'interno di GDB mentre cercava di valutare l'espressione, o all'interno dello script `gdb_dumper.py`.
2.  Controlla il campo "details" all'interno dell'errore JSON per un messaggio più specifico (es. "No symbol 'nome_variabile' in current context", "Cannot access memory at address...").
3.  Verifica che la variabile/espressione sia scritta correttamente e sia effettivamente nello scope e accessibile quando il breakpoint viene raggiunto.
4.  Per errori interni dello script dumper, controlla il file `gdb_dumper_debug.log` per traceback Python da dentro GDB.

**D: L'esecuzione del profilo fallisce, si blocca, o i breakpoint non vengono raggiunti.**
**R:**
1.  **Target Executable:** Assicurati che il percorso dell'eseguibile target nel profilo sia corretto e che il file esista.
2.  **Permessi:** Assicurati che GDB abbia il permesso di eseguire il target e leggere i suoi simboli.
3.  **Locazioni Breakpoint:** Ricontrolla che le locazioni dei breakpoint nelle azioni del profilo siano corrette (nomi di funzioni, file:numeri di linea). Usa la funzione di analisi dei simboli o l'ispezione live dello scope per verificare.
4.  **Logica del Programma:** Il programma potrebbe terminare prima che i tuoi breakpoint vengano raggiunti, o il percorso del codice verso il breakpoint non viene intrapreso con i "Program Parameters" forniti.
5.  **Timeouts:** Se le operazioni richiedono effettivamente molto tempo (es. su un progetto molto grande o una macchina lenta), considera di aumentare i timeout rilevanti in **Options > Configure Application... > Timeouts**.
6.  **GDB Raw Output:** Esamina questa scheda per eventuali messaggi di errore da GDB.
7.  **Application Log:** Controlla per errori riportati da Cpp-Python GDB Debug Helper stesso.

**D: La GUI non risponde.**
**R:**
1.  Se ciò accade durante un'operazione GDB (specialmente "Start GDB", "Run Program", "Dump Variable"), un comando GDB potrebbe richiedere troppo tempo o GDB potrebbe essere bloccato. Controlla se i timeout configurati sono adeguati.
2.  Se è un problema persistente, potrebbe indicare un bug nella logica di interazione della GUI o un'eccezione non gestita. Controlla la console da cui hai lanciato l'applicazione Python e la scheda "Application Log" per messaggi di errore o traceback.

**D: Come posso ottenere più informazioni di debug da `gdb_dumper.py`?**
**R:**
1.  Lo script `gdb_dumper.py` logga le sue operazioni in un file chiamato `gdb_dumper_debug.log`.
2.  Il percorso esatto di questo file di log è determinato dallo script:
    *   Se `__file__` è un percorso assoluto affidabile all'interno dell'ambiente Python di GDB, il log viene posizionato nella stessa directory di `gdb_dumper.py`.
    *   Come fallback (es. se `__file__` non è ben definito), viene posizionato nella directory home dell'utente (`~`).
    *   Quando `gdb_dumper.py` viene eseguito da GDB (sourcing), tenterà di scrivere il percorso del log determinato nel suo stesso log e cercherà anche di stampare un messaggio sulla console di GDB indicando dove *intende* loggare. Controlla l'"GDB Raw Output" per righe come "GDB_DUMPER_SCRIPT: File logger setup attempted." e messaggi da `_dumper_log_write`.
3.  Questo file di log contiene messaggi dettagliati passo-passo dal dumper, inclusi i valori di configurazione letti, i tipi incontrati e gli errori durante la serializzazione. È prezioso per il debug dello script dumper stesso.
4.  L'applicazione principale (`__main__.py`) tenta di eliminare questo file di log all'avvio per garantire un log pulito per ogni esecuzione dello strumento GUI.

---

### 11. Casi d'Uso / Esempi

**11.1 Caso d'Uso: Dumpare un `std::vector` all'ingresso di una funzione.**

*   **Obiettivo:** Ispezionare il contenuto di un `std::vector<MioOggetto> mioVettore;` non appena viene chiamata una funzione `processaVettore`.
*   **Passi:**
    1.  **Modalità Debug Manuale:**
        *   Target Executable: Il tuo programma.
        *   Breakpoint Location: `processaVettore` (o `NomeFile.cpp:numeroLinea` dell'ingresso della funzione).
        *   Variable/Expression: `mioVettore`.
        *   Avvia GDB, Imposta BP, Esegui Programma.
        *   Quando `processaVettore` viene raggiunto, clicca "Dump Variable". L'output JSON mostrerà gli elementi del vettore.
    2.  **Profilo Automatizzato:**
        *   Crea un nuovo profilo nel Gestore Profili.
        *   Imposta Target Executable.
        *   Aggiungi un'Azione:
            *   Breakpoint Location: `processaVettore`.
            *   Variables to Dump: Aggiungi `mioVettore`.
            *   Output Format: `json`.
            *   Output Directory: es. `./dump_vettori`.
            *   Filename Pattern: `{breakpoint}_{variable}_{timestamp}.json`.
            *   Continue after dump: `Sì` (se vuoi che venga raggiunto più volte) o `No`.
        *   Salva il profilo.
        *   Esegui il profilo dalla scheda "Automated Profile Execution". I file verranno generati in `./dump_vettori/NomeProfilo_timestamp/`.

**11.2 Caso d'Uso: Tracciare il valore di una variabile globale attraverso multipli breakpoint.**

*   **Obiettivo:** Vedere come una variabile globale `int contatoreGlobale;` cambia in tre punti diversi del programma: `funcA`, `funcB`, e `main.cpp:150`.
*   **Passi (Profilo Automatizzato):**
    1.  Crea un profilo.
    2.  Aggiungi Azione 1:
        *   Breakpoint: `funcA`
        *   Variables: `contatoreGlobale`
        *   Continue: `Sì`
    3.  Aggiungi Azione 2:
        *   Breakpoint: `funcB`
        *   Variables: `contatoreGlobale`
        *   Continue: `Sì`
    4.  Aggiungi Azione 3:
        *   Breakpoint: `main.cpp:150`
        *   Variables: `contatoreGlobale`
        *   Continue: `Sì` (o `No` se questo è l'ultimo punto di interesse per questa esecuzione)
    5.  Esegui il profilo. Il "Log File Prodotti" mostrerà file di dump separati per `contatoreGlobale` a ogni breakpoint, permettendoti di confrontare i suoi valori.

**11.3 Caso d'Uso: Salvare automaticamente snapshot di una struttura dati complessa durante un'esecuzione lunga.**

*   **Obiettivo:** Dumpare periodicamente una struttura dati complessa `MioOggettoStato appState;` che viene modificata all'interno di un loop nella funzione `taskLungo`.
*   **Passi (Profilo Automatizzato):**
    1.  Identifica un numero di linea adatto all'interno del loop in `taskLungo` (es. `taskLungo.cpp:75`).
    2.  Crea un profilo.
    3.  Aggiungi un'Azione:
        *   Breakpoint: `taskLungo.cpp:75`
        *   Variables: `appState`
        *   Output Format: `json`
        *   Output Directory: `./snapshot_stato_app`
        *   Continue after dump: `Sì`
    4.  Esegui il profilo. Ogni volta che l'iterazione del loop raggiunge la linea 75, un nuovo file JSON che cattura lo stato di `appState` verrà salvato, creando una serie temporale della sua evoluzione.

---

### 12. Avanzato: Lo Script `gdb_dumper.py`

Lo script `gdb_dumper.py` è un componente cruciale di Cpp-Python GDB Debug Helper, che abilita l'ispezione dettagliata e la serializzazione JSON di variabili C/C++ dall'interno di una sessione GDB attiva.

**12.1 Ruolo e Interazione con GDB**

*   **Python dentro GDB:** Le versioni moderne di GDB hanno un interprete Python integrato, che permette scripting potente e automazione dei task del debugger.
*   **Sourcing:** Quando avvii una sessione GDB tramite questa GUI (e il percorso "GDB Dumper Script" è correttamente configurato in **Options > Configure Application...**), la GUI istruisce GDB a eseguire (`source`) lo script `gdb_dumper.py`.
*   **Comando GDB Personalizzato:** Lo script `gdb_dumper.py` definisce un nuovo comando GDB personalizzato chiamato `dump_json <expression>`.
*   **Logica di Serializzazione:** Quando la GUI ha bisogno di dumpare una variabile (sia in modalità Debug Manuale sia tramite un'Azione di Profilo Automatizzato), invia questo comando `dump_json nome_tua_variabile` a GDB. Il codice Python all'interno di `gdb_dumper.py` quindi:
    1.  Usa l'API Python di GDB (`gdb.parse_and_eval()`) per ottenere un oggetto Python che rappresenta la variabile C/C++.
    2.  Attraversa questo oggetto `gdb.Value`, ispezionando il suo tipo, i campi, gli elementi (per array/puntatori), ecc.
    3.  Applica le "Dumper Options" configurate (Max Array Elements, Max Recursion Depth, Max String Length) per gestire il processo di serializzazione.
    4.  Gestisce tipi C++ comuni come `std::string`, puntatori, struct, classi e array.
    5.  Rileva e marca riferimenti ciclici o puntatori condivisi per prevenire ricorsione infinita.
    6.  Costruisce una rappresentazione Python dizionario/lista della variabile.
    7.  Serializza questa struttura Python in una stringa JSON.
    8.  Stampa questa stringa JSON sull'output standard di GDB, racchiusa da stringhe delimitatore speciali (`START_JSON_OUTPUT` e `END_JSON_OUTPUT`).
*   **Elaborazione GUI:** L'applicazione principale Cpp-Python GDB Debug Helper cattura quindi l'output di GDB, estrae la stringa JSON tra i delimitatori, la parsifica e la visualizza nella scheda "Parsed JSON Output".

**12.2 File di Log del Dumper (`gdb_dumper_debug.log`)**

*   **Scopo:** Lo script `gdb_dumper.py` mantiene il suo file di log dettagliato per scopi diagnostici. Questo log è separato dall'"Application Log" visibile nella GUI.
*   **Contenuto:** Registra:
    *   Messaggi di inizializzazione.
    *   Le opzioni di configurazione del dumper effettivamente utilizzate.
    *   Passi dettagliati durante la serializzazione di una variabile (tipi incontrati, campi accessi, decisioni prese).
    *   Eventuali errori o eccezioni Python che si verificano *all'interno dell'ambiente Python di GDB* mentre lo script dumper è in esecuzione.
*   **Posizione:**
    *   Lo script tenta di creare `gdb_dumper_debug.log` nella stessa directory in cui si trova `gdb_dumper.py` stesso.
    *   Se ciò non è possibile (es. a causa di permessi o di come GDB risolve i percorsi quando viene eseguito il sourcing), ricade sulla creazione del log nella directory home dell'utente (`~`).
    *   Quando GDB esegue lo script, `gdb_dumper.py` tenterà di stampare un messaggio nel suo stesso log e sulla console GDB indicando il percorso del log determinato. Cerca questi messaggi nell'Output Raw di GDB o nel file di log stesso.
*   **Cancellazione all'Avvio:** L'applicazione principale Cpp-Python GDB Debug Helper (`__main__.py`) tenta di eliminare qualsiasi file `gdb_dumper_debug.log` esistente all'avvio della GUI. Ciò garantisce che il log contenga informazioni rilevanti solo per la sessione GUI corrente, facilitando la risoluzione di problemi recenti.
*   **Quando Controllarlo:** Questo log è prezioso se:
    *   I dump JSON falliscono inaspettatamente.
    *   L'output JSON è malformato o mancano dati attesi.
    *   Sospetti un errore all'interno dello script `gdb_dumper.py` stesso.

---

### 13. Appendice (Opzionale)

**13.1 Riepilogo Placeholder Nomi File**

I seguenti placeholder possono essere usati nel campo "Filename Pattern" quando si definisce un'azione di debug nel Gestore Profili:

*   `{profile_name}`: Il nome del profilo in esecuzione (sanificato per l'uso nei nomi dei file).
*   `{app_name}`: Il nome base dell'eseguibile target (es. `mioprogramma` da `/percorso/a/mioprogramma.exe`).
*   `{breakpoint}`: La stringa "Breakpoint Location" specificata per l'azione (sanificata).
*   `{variable}`: Il nome della variabile o espressione dumpata (sanificata).
*   `{timestamp}`: Un timestamp dettagliato nel formato `AAAAMMGG_HHMMSS_fff` (AnnoMeseGiorno\_OraMinutoSecondo\_Millisecondo).
*   `{format}`: Il formato di output selezionato in minuscolo (es. `json`, `csv`).

**Pattern Esempio:** `dump_{app_name}_{breakpoint}_{variable}_{timestamp}.{format}`
**Output Esempio:** `dump_mioprogramma_main_miaVar_20231027_143005_123.json`