VALLONGOL/SXXXXXXX_CppPythonDebug
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
a716ca7e96
SXXXXXXX_CppPythonDebug/doc/Italian-manual.md
VALLONGOL a716ca7e96 update manual
2025-06-11 09:13:25 +02:00

17 KiB
Raw Blame History

Cpp-Python GDB Debug Helper - Manuale Utente

1. Introduzione

1.1 Cos'è Cpp-Python GDB Debug Helper?

Il Cpp-Python GDB Debug Helper è un'Interfaccia Utente Grafica (GUI) progettata per migliorare e semplificare il processo di debugging di applicazioni C/C++ utilizzando il 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.
  • Dumping Avanzato delle Variabili: Utilizza uno script Python personalizzato per GDB per estrarre lo stato delle variabili C/C++, incluse strutture dati complesse come classi, struct, 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 estrarre, formato di output finale (JSON/CSV), directory di output e pattern per i nomi dei file.
  • Analisi dei Simboli: Analizza il tuo eseguibile compilato 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 estratti in formati JSON o CSV con nomi di file personalizzabili utilizzando placeholder per una migliore organizzazione.
  • Logging nella GUI: Visualizza i log dell'applicazione e l'output grezzo di GDB direttamente nell'interfaccia.

2. Requisiti di Sistema e Configurazione

2.1 Sistemi Operativi Supportati

  • Windows (Primario): L'applicazione è sviluppata e testata principalmente su Windows. Utilizza il backend compatibile con Windows di pexpect (PopenSpawn) per un controllo robusto del processo.
  • Linux/macOS (Sperimentale): L'applicazione dovrebbe essere compatibile con sistemi Unix-like poiché pexpect è multipiattaforma.

2.2 Python

  • Python 3.7 o successivo è raccomandato.

2.3 Librerie Python Richieste

Sarà necessario installare le seguenti librerie Python. Puoi installarle usando pip: pip install pexpect appdirs

  • pexpect: Per controllare GDB come processo figlio.
  • appdirs: Utilizzato per determinare directory di configurazione e dati utente indipendenti dalla piattaforma (sebbene la configurazione principale sia ora salvata in modo relativo all'applicazione).
  • Tkinter: Inclusa nelle installazioni standard di Python e utilizzata per la GUI.

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 o fornisci il percorso completo all'eseguibile di GDB nella configurazione dell'applicazione.
  • Versioni di GDB 8.x e successive sono raccomandate per il miglior supporto allo scripting Python.

2.5 Compilazione della Tua Applicazione Target C/C++

  • La tua applicazione C/C++ deve essere compilata con i simboli di debug.
  • Per GCC/G++ o Clang, usa il flag -g: g++ -g -o mioprogramma mioprogramma.cpp.
  • Evita alti livelli di ottimizzazione (es. -O2, -O3) se interferiscono con il debug. Considera l'uso di -Og (ottimizza per l'esperienza di debug).

3. Installazione ed Esecuzione

3.1 Esecuzione da Codice Sorgente

  1. Assicurati che tutti i prerequisiti della Sezione 2 siano soddisfatti.
  2. Scarica o clona il repository del codice sorgente.
  3. Naviga nella directory radice del progetto (cpp_python_debug).
  4. Esegui lo script principale come un modulo: python -m cpp_python_debug

3.2 Esecuzione della Versione Compilata (--onedir)

L'applicazione può essere impacchettata in una cartella di distribuzione usando PyInstaller.

  1. Decomprimi o copia la cartella di distribuzione (es. cpp_python_debug) nella posizione desiderata. Questa cartella è auto-contenuta.
  2. All'interno della cartella, trova ed esegui l'eseguibile principale (es. cpp_python_debug.exe).
  3. Tutti i file generati dall'applicazione (configurazioni, log, dump) verranno creati all'interno di questa cartella, rendendola completamente portabile.

4. Struttura di File e Directory

L'applicazione crea e gestisce diversi file e directory. Comprendere questa struttura è fondamentale per trovare le tue configurazioni e i tuoi output.

  • Esecuzione da sorgente: Tutti i percorsi sono relativi alla directory radice del progetto.
  • Esecuzione da versione compilata: Tutti i percorsi sono relativi alla cartella che contiene l'eseguibile principale.
  • config/
    • gdb_debug_gui_settings.v2.json: Il file di configurazione principale. Memorizza tutte le tue impostazioni, inclusi percorsi, timeout e tutti i tuoi profili di debug. Il file è in formato JSON.
  • logs/
    • cpppythondebughelper_gui.log: Il file di log principale per l'applicazione GUI stessa. Utile per risolvere problemi della GUI.
    • gdb_dumper_script_internal.log: Un file di log dedicato per lo script gdb_dumper.py. È estremamente utile per debuggare problemi che si verificano all'interno di GDB durante un dump di variabili.
    • manual_gdb_dumps/: La directory in cui vengono memorizzati i file di dump temporanei (.gdbdump.json) dalla scheda "Manual Debug" prima che tu li salvi in una posizione finale.
    • gdb_dumper_diagnostics/: (Opzionale) Se abiliti "Enable Diagnostic JSON Dump to File" nelle impostazioni, questa cartella conterrà una copia JSON grezza di ogni singolo dump di variabile, utile per il debug dello script dumper stesso.
  • <Profile Output Directory>: La directory che specifichi nell'azione di un profilo è dove verranno salvati i file di dump finali (JSON o CSV) per l'esecuzione di quel profilo. L'applicazione creerà qui una sottocartella specifica per l'esecuzione (es. MieiDump/MioProfilo_20231027_143000/).

5. Guida Rapida

  1. Avvia l'Applicazione come descritto nella Sezione 3.
  2. Configurazione Iniziale: Al primo avvio, vai su Options > Configure Application....
    • Nella scheda Paths & Directories, vai al tuo eseguibile GDB.
    • (Fortemente Raccomandato) Vai anche allo script gdb_dumper.py situato nella sottodirectory core del codice sorgente (o cpp_python_debug/core nella versione compilata).
    • Clicca Save.
  3. Esegui una Sessione di Debug Manuale:
    • Vai alla scheda Manual Debug.
    • Seleziona il tuo eseguibile C/C++ compilato.
    • Inserisci un breakpoint (es. main).
    • Clicca 1. Start GDB.
    • Clicca 2. Set Breakpoint.
    • Clicca 3. Run Program.
    • Quando il breakpoint viene raggiunto, inserisci un nome di variabile e clicca 4. Dump Variable.
    • Osserva la scheda "Parsed JSON/Status Output". Mostrerà un messaggio di stato che conferma il dump e il percorso di un file temporaneo .gdbdump.json.
    • I pulsanti Save as JSON e Save as CSV diventeranno attivi. Usali per salvare i dati catturati in una posizione permanente.

6. Panoramica dell'Interfaccia Utente

  • Barra dei Menu: Accedi a Options (Configurazione) e Profiles (Gestore Profili).
  • Stato della Configurazione Critica: Mostra se GDB e lo script dumper sono configurati correttamente.
  • Pannello Modalità (Schede): Passa tra Manual Debug e Automated Profile Execution.
  • Area di Output e Log (Schede):
    • GDB Raw Output: Comunicazione testuale grezza con il processo GDB.
    • Parsed JSON/Status Output: Mostra il payload di stato ricevuto dallo script dumper o formatta JSON semplici.
    • Application Log: Messaggi di log relativi alla GUI.
  • Barra di Stato: Brevi messaggi sullo stato corrente dell'applicazione.

7. Finestra di Configurazione (Options > Configure Application...)

Qui puoi impostare le impostazioni globali dell'applicazione.

  • Scheda Paths & Directories: Imposta i percorsi assoluti a gdb.exe e gdb_dumper.py.
  • Scheda Timeouts: Configura i timeout (in secondi) per varie operazioni di GDB per evitare che l'applicazione si blocchi.
  • Scheda Dumper Options: Controlla il comportamento dello script gdb_dumper.py (es. profondità di ricorsione, numero massimo di elementi degli array). Puoi anche abilitare i dump diagnostici qui.

8. Modalità Debug Manuale in Dettaglio

Questa modalità fornisce un'interfaccia passo-passo per una singola sessione di debug. Il flusso di lavoro chiave da notare è:

  • Quando clicchi su 4. Dump Variable, lo script gdb_dumper.py salva lo stato della variabile direttamente in un file temporaneo (es. nella cartella logs/manual_gdb_dumps/).
  • La GUI riceve solo un messaggio di stato che conferma questa azione e il percorso del file temporaneo.
  • Devi quindi usare i pulsanti Save as... per copiare e convertire questi dati temporanei in una posizione permanente.

9. Gestore Profili ed Esecuzione Automatizzata

Questa è la funzionalità principale per l'automazione del debugging.

9.1 Gestore Profili (Profiles > Manage Profiles...)

Questa finestra è il centro per creare e gestire i tuoi scenari di debug automatizzati. Un profilo è composto da:

  1. Dettagli Profilo: Nome, eseguibile target e parametri del programma.
  2. Dati di Analisi Simboli: Puoi eseguire un'analisi sull'eseguibile target. Lo strumento usa GDB per trovare tutte le funzioni, variabili globali, ecc., e memorizza queste informazioni nel profilo. Questo ti aiuta a configurare le azioni in modo accurato.
  3. Azioni: Un elenco di azioni di debug.

9.2 Editor di Azioni

Ogni azione definisce un'attività specifica da eseguire a un breakpoint.

  • Posizione Breakpoint: Dove GDB dovrebbe fermarsi.
  • Variabili da Dumpare: Quali variabili ispezionare a quel breakpoint.
  • Formato Output: Formato finale (JSON o CSV).
  • Directory di Output: La directory di base per i file di output.
  • Pattern Nome File: Un modello per nominare i file di output.
  • Flusso di Esecuzione: Se continuare dopo il dump e se eseguire il dump ad ogni hit o solo al primo.

9.3 Flusso di Esecuzione Automatizzata

  1. Seleziona un profilo dal menu a tendina nella scheda "Automated Profile Execution".
  2. Clicca Run Profile.
  3. Il ProfileExecutor avvia GDB ed esegue il programma.
  4. Quando un breakpoint viene raggiunto, l'azione corrispondente viene attivata.
  5. Viene invocato lo script gdb_dumper.py, che estrae le variabili specificate in file intermedi .gdbdump.json.
  6. L'applicazione principale elabora quindi questi file intermedi:
    • Se il formato desiderato è JSON, rinomina il file secondo il pattern.
    • Se il formato desiderato è CSV, legge il JSON, lo converte, salva il nuovo file .csv ed elimina il JSON intermedio.
  7. Il "Produced Files Log" viene aggiornato in tempo reale con lo stato di ogni file creato.

10. Risoluzione Problemi / FAQ

D: GDB non trovato / Problemi con lo script Dumper / Nessun simbolo di debug. R: Assicurati che i percorsi configurati in Options > Configure Application... siano corretti. Controlla le schede Application Log e GDB Raw Output per messaggi di errore specifici da GDB o dallo script dumper.

D: L'applicazione si blocca o va in timeout. R: Il tuo programma target potrebbe richiedere molto tempo. Prova ad aumentare i timeout nella Finestra di Configurazione.

D: gdb_dumper.py sta fallendo. Come posso debuggarlo? A:

  1. Controlla il file logs/gdb_dumper_script_internal.log. È il primo posto dove cercare errori che si verificano all'interno del dumper.
  2. Per ancora più dettagli, abilita "Enable Diagnostic JSON Dump to File" nelle Opzioni Dumper. Questo salverà una copia JSON grezza di ogni dump nella directory logs/gdb_dumper_diagnostics/, permettendoti di vedere esattamente cosa sta producendo il dumper.

11. Casi d'Uso / Esempi

11.1 Dumpare un std::vector

  • Scenario: Vuoi ispezionare il contenuto di un std::vector<MyObject> myVector ogni volta che viene modificato all'interno di una funzione processVector.
  • Setup Profilo:
    • Azione 1: Breakpoint all'inizio di processVector.
    • Azione 2: Breakpoint alla fine di processVector.
    • Entrambe le azioni estraggono la variabile myVector.
  • Risultato: Durante l'esecuzione del profilo, verranno creati file come dump_vettori/MioProfilo_timestamp/processVector_myVector_timestamp.json (o .csv), permettendoti di vedere lo stato del vettore prima e dopo l'elaborazione.

11.2 Tracciare una variabile globale

  • Scenario: Devi monitorare come una variabile globale globalCounter cambia in punti chiave della tua applicazione.
  • Setup Profilo: Crea più azioni, ognuna con un diverso breakpoint (es. func_A, func_B, main.cpp:150), ma tutte che estraggono la stessa variabile globalCounter.
  • Risultato: Otterrai una serie di file con timestamp, uno per ogni volta che il contatore è stato estratto, permettendoti di tracciare il suo valore attraverso il flusso di esecuzione del programma.

11.3 Snapshot di dati complessi

  • Scenario: La tua applicazione ha un grande oggetto di configurazione o di stato (ApplicationState appState) e vuoi fare uno snapshot completo di esso in un punto critico, come poco prima di un'attività di lunga durata.
  • Setup Profilo: Un'azione a longRunningTask.cpp:75 che estrae l'oggetto appState.
  • Risultato: Verrà creato un file JSON dettagliato come snapshot_stato/MioProfilo_timestamp/longRunningTask.cpp_75_appState_timestamp.json, contenente una rappresentazione completa e annidata dello stato della tua applicazione.

12. Avanzato: Lo Script gdb_dumper.py

12.1 Ruolo e Interazione con GDB

Lo script gdb_dumper.py è il cuore del motore di estrazione dati. Viene eseguito all'interno del processo GDB e ha accesso all'API Python di GDB.

  • Logica di Serializzazione:

    1. Usa gdb.parse_and_eval() per ottenere un oggetto gdb.Value che rappresenta una variabile C++.
    2. Attraversa ricorsivamente questo oggetto, rispettando le "Opzioni Dumper" (profondità massima, ecc.).
    3. Costruisce una rappresentazione Python (dizionario/lista) dei dati C++.
    4. Serializza questo oggetto Python in una stringa JSON.
    5. Salva la stringa JSON completa direttamente in un file intermedio specificato (es. ...nome.gdbdump.json).
    6. Stampa un piccolo payload di stato JSON (che indica successo/fallimento e il percorso scritto) sull'output standard di GDB, racchiuso tra delimitatori speciali.

  • Elaborazione della GUI: La GUI principale cattura questo payload di stato per capire l'esito del dump. In Modalità Profilo, elabora quindi il file intermedio per creare l'output finale specificato dall'utente (rinominando per JSON, convertendo per CSV).

12.2 File di Log del Dumper (gdb_dumper_script_internal.log)

Questo file di log, situato nella directory principale logs, è prezioso per il debug dello script dumper stesso. Registra passaggi interni, configurazioni ed errori che si verificano all'interno dell'ambiente GDB, che non sono visibili nel log principale dell'applicazione.

13. Appendice: Placeholder per 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 finale del file (.json o .csv) è gestita automaticamente.

  • {profile_name}: Il nome del profilo (sanificato per la sicurezza del filesystem).
  • {app_name}: Il nome base dell'eseguibile target.
  • {breakpoint}: La stringa della posizione del breakpoint (sanificata).
  • {variable}: Il nome della variabile/espressione estratta (sanificato).
  • {timestamp}: Un timestamp dettagliato (ANNO MESE GIORNO_ORA MINUTO SECONDO_ms).

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