VALLONGOL/SXXXXXXX_CppPythonDebug
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
914c351c45
SXXXXXXX_CppPythonDebug/doc/Italian-manual.md
VALLONGOL 914c351c45 change from wexpect to pexpect
2025-06-10 08:36:43 +02:00

22 KiB
Raw Blame History

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