VALLONGOL/SXXXXXXX_CppPythonDebug
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
aaf358e1e1
SXXXXXXX_CppPythonDebug/doc/Italian-manual.md
VALLONGOL aaf358e1e1 add manual
2025-05-22 14:58:31 +02:00

7.2 KiB
Raw Blame History

Struttura Proposta per il Manuale Utente

  1. Introduzione / Panoramica
    • Scopo del software.
    • A chi è rivolto.
    • Breve descrizione delle funzionalità principali.
  2. Installazione e Requisiti
    • Requisiti di sistema (Python, GDB).
    • Come installare l'applicazione e le sue dipendenze.
  3. Guida Rapida (Quick Start)
    • Passaggi essenziali per avviare una sessione di debug e fare un dump.
  4. Interfaccia Utente Dettagliata
    • Descrizione della Finestra Principale:
      • Sezione Stato Configurazione Critica (GDB, Dumper Script)
      • Sezione Impostazioni Target e Sessione Debug (Target Executable, Parametri, Breakpoint, Variabile)
      • Pulsanti di Controllo Sessione (Start, Set BP, Run/Continue, Dump, Stop)
      • Schede di Output (GDB Raw Output, Parsed JSON Output, Application Log)
      • Sezione Salvataggio Dati
      • Barra di Stato
    • Menu Opzioni:
      • Configure Application...
      • Exit
    • Finestra di Configurazione Applicazione:
      • Scheda Paths (GDB Executable, GDB Dumper Script)
      • Scheda Timeouts
      • Scheda Dumper Options
      • Pulsanti Save, Cancel
  5. Funzionalità Avanzate e Concetti
    • Come funziona il Dump Strutturato (ruolo di gdb_dumper.py).
    • Interpretazione dell'output JSON.
    • Gestione dei Timeout.
    • Logging e Troubleshooting (dove trovare i log, cosa cercare).
  6. Esempi di Casi d'Uso
    • Debug di un std::vector di struct.
    • Analisi di una classe complessa.
    • Esportazione di dati per analisi offline.
  7. Domande Frequenti (FAQ)
    • Problemi comuni e soluzioni.
  8. Contribuire e Segnalazione Bug (Opzionale)
  9. Licenza (Opzionale)

Iniziamo con le prime sezioni:

MANUALE UTENTE (ITALIANO)

Cpp-Python GDB Debug Helper - Manuale Utente

1. Introduzione

Benvenuto in Cpp-Python GDB Debug Helper! Questo software è stato creato per assistere gli sviluppatori C/C++ nel processo di debug dei loro programmi, fornendo un'interfaccia grafica intuitiva per controllare GDB (il Debugger GNU) e, soprattutto, per facilitare l'ispezione e l'esportazione di dati complessi in formati strutturati come JSON e CSV.

Se ti sei mai trovato a dover navigare strutture dati intricate o lunghi array nel terminale di GDB, o se hai desiderato poter salvare lo stato di una variabile per un'analisi più approfondita, questo strumento è pensato per te. Sfrutta la potenza dell'API Python di GDB per "dissezionare" le tue variabili e presentarle in modo chiaro.

Funzionalità Principali a Colpo d'Occhio:

  • Controllo grafico della sessione GDB (avvio, breakpoint, esecuzione).
  • Dump di variabili C/C++ in formato JSON leggibile.
  • Configurazione personalizzabile per GDB e per il processo di dump.
  • Esportazione dei dati dumpati in JSON o CSV.
  • Visualizzazione dell'output di GDB e dei log dell'applicazione.

2. Installazione e Requisiti

Requisiti di Sistema:

  • Python: Versione 3.7 o successiva. Puoi scaricarlo da python.org. Assicurati che Python sia aggiunto al tuo PATH di sistema.
  • GDB (GNU Debugger): Una versione di GDB che includa il supporto per lo scripting Python (la maggior parte delle versioni recenti lo include). Se stai usando MinGW su Windows, GDB è tipicamente incluso. Assicurati che l'eseguibile di GDB sia accessibile.
  • Sistema Operativo: Testato principalmente su Windows, ma dovrebbe funzionare su Linux o macOS con GDB e Python installati (potrebbe richiedere pexpect invece di wexpect su sistemi non Windows, anche se wexpect è un fork che punta alla compatibilità).

Installazione dell'Applicazione:

  1. Clona il Repository (se applicabile) o Scarica i File Sorgente: 
    git clone <URL_DEL_TUO_REPOSITORY_GITEA>
cd <nome_directory_progetto>
  2. Crea un Ambiente Virtuale (Raccomandato): 
    python -m venv venv
# Su Windows
venv\Scripts\activate
# Su Linux/macOS
source venv/bin/activate
  3. Installa le Dipendenze: Il file requirements.txt (se presente) dovrebbe elencare le dipendenze. Le principali sono:
    • wexpect: Per il controllo del processo GDB su Windows.
    • appdirs: Per la gestione dei percorsi di configurazione cross-platform. Puoi installarle con pip:
    pip install wexpect appdirs
    Se hai un file requirements.txt: 
    pip install -r requirements.txt

Verifica dell'Installazione di GDB: Apri un terminale e digita gdb --version. Dovresti vedere le informazioni sulla versione di GDB. Se il comando non viene trovato, GDB non è nel tuo PATH o non è installato.

3. Guida Rapida (Quick Start)

Segui questi passaggi per iniziare rapidamente:

  1. Avvia l'Applicazione: Dalla directory principale del progetto, esegui:

    python -m cpp_python_debug

    Si aprirà la finestra principale dell'applicazione.

  2. Configura GDB (Solo la Prima Volta):

    • Vai su "Options" > "Configure Application...".
    • Nella scheda "Paths", clicca su "Browse..." accanto a "GDB Executable" e seleziona il file gdb.exe sul tuo sistema (es. C:\MinGW\bin\gdb.exe).
    • Lo "GDB Dumper Script" dovrebbe essere auto-rilevato se lo script gdb_dumper.py è nella sua posizione standard (core/gdb_dumper.py relativo al progetto). Altrimenti, puoi specificarlo manualmente.
    • Clicca su "Save".

  3. Imposta il Target e il Breakpoint nella Finestra Principale:

    • Target Executable: Clicca "Browse..." e seleziona l'eseguibile C/C++ compilato con simboli di debug (es. flag -g durante la compilazione con GCC/Clang) che vuoi debuggare.
    • Breakpoint Location: Inserisci dove vuoi che il programma si fermi (es. main, MyClass::myMethod, myfile.cpp:123).
    • Variable/Expression: Inserisci il nome della variabile o l'espressione che vuoi analizzare quando il breakpoint viene raggiunto (es. myVector, *this, global_struct.member).

  4. Avvia il Debug:

    • Clicca su "1. Start GDB Session". La sezione "GDB Raw Output" mostrerà l'avvio di GDB.
    • Se GDB e lo script dumper sono configurati correttamente, lo stato nella parte alta della finestra dovrebbe indicarlo.

  5. Imposta il Breakpoint:

    • Clicca su "2. Set Breakpoint".

  6. Esegui il Programma:

    • Clicca su "3. Run Program" (o "3. Continue" se il programma è già stato avviato).
    • Il programma dovrebbe eseguirsi e fermarsi al breakpoint specificato. L'output di GDB mostrerà il punto di arresto.

  7. Effettua il Dump della Variabile:

    • Clicca su "4. Dump Variable".
    • La scheda "Parsed JSON Output" mostrerà la struttura della variabile in formato JSON.
    • L'output grezzo di GDB mostrerà i delimitatori START_JSON_OUTPUT e END_JSON_OUTPUT attorno al JSON grezzo.

  8. Salva i Dati (Opzionale):

    • Usa i pulsanti "Save as JSON" o "Save as CSV" per salvare i dati dumpati.

  9. Termina la Sessione:

    • Clicca su "Stop GDB Session" per terminare GDB.
    • Chiudi l'applicazione tramite il menu "Options" > "Exit" o il pulsante di chiusura della finestra. Le impostazioni verranno salvate.