VALLONGOL/SXXXXXXX_PyInstallerGUIWrapper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
742ae5cf28
SXXXXXXX_PyInstallerGUIWrapper/doc/Italian-manual.md
VALLONGOL 742ae5cf28 add manual
2025-05-06 15:00:01 +02:00

11 KiB
Raw Blame History

Italiano

1. Introduzione

PyInstaller GUI Wrapper è un'applicazione desktop che fornisce un'interfaccia grafica utente (GUI) per PyInstaller, un popolare strumento per convertire script Python in applicazioni eseguibili standalone. Questo wrapper mira a semplificare il processo di build, specialmente per progetti che aderiscono a una specifica struttura di directory, e offre funzionalità come l'iniezione automatica delle informazioni di versione.

2. Prerequisiti

Prima di utilizzare PyInstaller GUI Wrapper, assicurati di avere installato quanto segue:

  • Python 3.x: Il wrapper è esso stesso un'applicazione Python.
  • PyInstaller: Questo è lo strumento principale utilizzato per la compilazione degli eseguibili. Installalo tramite pip: 
    pip install pyinstaller
  • Git (Raccomandato): Sebbene opzionale, Git è necessario se desideri che il wrapper estragga automaticamente le informazioni sulla versione (tag, hash dei commit, nomi dei branch) dal repository Git del tuo progetto e le inietti nella tua build.

3. Avvio dell'Applicazione

Se disponi del codice sorgente, puoi eseguire PyInstaller GUI Wrapper dal tuo terminale navigando nella sua directory principale ed eseguendo:

python -m pyinstallerguiwrapper

Se disponi di un eseguibile compilato del wrapper, esegui semplicemente tale eseguibile.

4. Panoramica dell'Interfaccia Principale

La finestra principale di PyInstaller GUI Wrapper è suddivisa in diverse sezioni:

  • Directory Progetto:
    • Directory Principale Progetto: Un campo di immissione (sola lettura) che mostra il percorso del progetto selezionato.
    • Sfoglia...: Un pulsante per aprire una finestra di dialogo per selezionare la directory principale del progetto Python che desideri compilare.
  • Percorsi Derivati (Automatici):
    • Questa sezione mostra i percorsi che il wrapper tenta automaticamente di trovare in base alla selezione della directory del progetto e alle convenzioni standard. Aiuta a verificare se la struttura del tuo progetto è riconosciuta correttamente.
    • Script Trovato: Mostra il percorso al file __main__.py rilevato.
    • File Spec Trovato: Mostra il percorso al file nomeprogetto.spec rilevato.
    • Icona Trovata: Mostra il percorso al file nomeprogetto.ico (o equivalente per la piattaforma) rilevato.
    • Messaggi di stato come "N/A" o "NON TROVATO!" indicheranno se un file non è presente o non è stato possibile localizzarlo.
  • Schede Opzioni:
    • Opzioni Base (da Spec/GUI):
      • Nome App: Il nome della tua applicazione. Può essere derivato dal nome del progetto, caricato da un file .spec esistente o inserito manualmente.
      • File Icona: Percorso dell'icona dell'applicazione. Può essere rilevato automaticamente, caricato da uno spec o selezionato manualmente usando "Sfoglia...". Il pulsante "Pulisci" rimuove la selezione.
      • File Singolo (Unico eseguibile): Casella di controllo corrispondente all'opzione --onefile di PyInstaller. Crea un singolo file eseguibile.
      • Finestra (Nessuna console): Casella di controllo corrispondente all'opzione --windowed (o --noconsole) di PyInstaller. Per applicazioni GUI che non dovrebbero aprire una finestra di console.
    • File Aggiuntivi (da Spec/GUI):
      • File/Cartelle da includere: Una listbox che mostra file o cartelle da aggiungere al bundle della tua applicazione.
      • Aggiungi File...: Apre una finestra di dialogo per selezionare un singolo file da includere.
      • Aggiungi Cartella...: Apre una finestra di dialogo per selezionare un'intera cartella da includere.
      • Rimuovi Selezionato: Rimuove l'elemento evidenziato dalla lista.
      • Quando aggiungi file/cartelle, ti verrà chiesto il percorso di destinazione all'interno del bundle (ad es. . per la root, data/ per una sottocartella). I percorsi sorgente sono memorizzati relativamente alla root del progetto.
  • Log di Build: Un'area di testo che mostra l'output in tempo reale e i messaggi di log dal processo di build di PyInstaller e dal wrapper stesso.
  • Crea Eseguibile: Il pulsante di azione principale per avviare il processo di build. È disabilitato fino a quando non viene selezionata una directory di progetto valida con i file essenziali.

5. Flusso di Lavoro: Compilare il Tuo Progetto Python

5.1. Selezionare il Tuo Progetto

  1. Clicca il pulsante "Sfoglia..." nella sezione "Directory Progetto".
  2. Naviga e seleziona la directory principale del progetto Python che desideri impacchettare.
    • Struttura Progetto Attesa: Il wrapper funziona al meglio con progetti strutturati come segue: 
      RootDelTuoProgetto/
├── nomedeltuoprogetto/   # Sottocartella codice sorgente (nome progetto in minuscolo)
│   ├── __init__.py
│   ├── __main__.py     # Entry point principale per la tua applicazione
│   └── ... (altri file .py e sotto-package)
├── nomedeltuoprogetto.spec  # File spec PyInstaller (opzionale, verrà generato/sovrascritto)
└── nomedeltuoprogetto.ico   # Icona applicazione (opzionale, estensioni variano per piattaforma)
  3. Una volta selezionata, la sezione "Percorsi Derivati" si aggiornerà, mostrando quali dei file attesi sono stati trovati. Se file essenziali come __main__.py o il file .spec (se intendi usarne uno esistente che viene poi modificato dalla GUI) non vengono trovati, il pulsante "Crea Eseguibile" potrebbe rimanere disabilitato.

5.2. Generazione Automatica File di Versione (_version.py)

Se la directory del progetto selezionata (RootDelTuoProgetto) è un repository Git:

  1. Il wrapper tenterà di estrarre le informazioni sulla versione (ultimo tag, hash del commit, branch corrente e stato "dirty" se ci sono modifiche non committate).
  2. Creerà o sovrascriverà automaticamente un file chiamato _version.py all'interno della sottocartella sorgente del tuo progetto (ad es. RootDelTuoProgetto/nomedeltuoprogetto/_version.py).
  3. Questo file _version.py conterrà:
    • Variabili come __version__, GIT_COMMIT_HASH, GIT_BRANCH, BUILD_TIMESTAMP e IS_GIT_REPO.
    • Una funzione di supporto get_version_string(format_string=None) che puoi chiamare dal codice della tua applicazione per ottenere una stringa formattata di queste informazioni sulla versione.
    • Esempio di segnaposto per format_string: {{version}}, {{tag}}, {{commit_short}}, {{branch}}, {{dirty}}, {{timestamp}}.
  4. Se la directory del progetto non è un repository Git, o se i comandi Git falliscono, _version.py verrà comunque creato ma conterrà valori predefiniti "unknown".

Per utilizzare questo nella tua applicazione, importa _version e chiama _version.get_version_string() o accedi direttamente alle variabili. Vedi il README.md per un esempio.

5.3. Configurare le Opzioni di Build

  1. Opzioni Base:
    • Rivedi e imposta il Nome App.
    • Seleziona un File Icona se desiderato (questo sovrascrive qualsiasi icona rilevata automaticamente o icona da uno spec caricato).
    • Scegli tra File Singolo (build one-file) o una build in directory (one-dir, deselezionando "File Singolo"). La modalità One-dir è spesso più stabile per applicazioni GUI.
    • Seleziona Finestra (Nessuna console) per applicazioni GUI. Deselezionalo per applicazioni basate su console.
  2. File Aggiuntivi:
    • Usa "Aggiungi File..." o "Aggiungi Cartella..." per includere eventuali file di dati necessari, asset o dipendenze non Python.
    • Ti verrà richiesto il percorso di destinazione all'interno del bundle dell'applicazione. Ad esempio, se aggiungi assets/image.png e specifichi la destinazione come images, sarà disponibile nella tua app compilata in images/image.png.
    • I percorsi sono relativi al file .spec (che si trova nella root del tuo progetto).

Nota: Se è stato trovato un file .spec nella root del tuo progetto, le sue opzioni vengono caricate nella GUI. Qualsiasi modifica apportata nella GUI verrà utilizzata per rigenerare e sovrascrivere questo file .spec prima dell'inizio della build.

5.4. Avviare la Build

  1. Una volta selezionato il progetto e configurato le opzioni, clicca il pulsante "Crea Eseguibile".
  2. Il wrapper:
    • Genererà/aggiornerà il file _version.py nella cartella sorgente del tuo progetto target.
    • Genererà/aggiornerà il file .spec nella root del tuo progetto in base alle impostazioni correnti della GUI.
    • Eseguirà PyInstaller in un thread separato.
  3. Il Log di Build mostrerà l'output in tempo reale da PyInstaller.
  4. Al completamento (o fallimento), apparirà una finestra di messaggio e il log di build conterrà lo stato finale.

5.5. Individuare l'Eseguibile

  • Se la build ha successo, l'applicazione impacchettata si troverà in una sottocartella chiamata _dist (per impostazione predefinita) all'interno della directory del progetto selezionata (ad es. RootDelTuoProgetto/_dist/NomeTuaApp/).
  • I file di build temporanei si troveranno in una sottocartella _build.

6. Suggerimenti e Risoluzione dei Problemi

  • "NON TROVATO!" in Percorsi Derivati: Controlla attentamente la struttura delle cartelle del tuo progetto e la denominazione dei file rispetto alle convenzioni previste. Assicurati che __main__.py e (se ti affidi a uno esistente) il file nomeprogetto.spec siano posizionati correttamente.
  • La Build Fallisce / L'Eseguibile Non Parte:
    1. Controlla il Log di Build: Cerca errori o avvisi da PyInstaller.
    2. Modalità Console per Debugging: Se il tuo eseguibile non si avvia, modifica temporaneamente il file .spec generato (ad es. nomedeltuoprogetto.spec) e cambia console=False in console=True nel blocco EXE(). Quindi, ricompila eseguendo pyinstaller nomedeltuoprogetto.spec --clean dalla riga di comando nella root del tuo progetto. Quando esegui l'eseguibile, apparirà una finestra di console che mostrerà eventuali errori Python.
    3. Import Nascosti (Hidden Imports): Alcune librerie Python utilizzano import dinamici che PyInstaller potrebbe non rilevare. Potrebbe essere necessario aggiungerli alla lista hiddenimports nel tuo file .spec o tramite un file hook.
  • Informazioni Git Non Iniettate: Assicurati che Git sia installato e accessibile nel PATH del tuo sistema sulla macchina su cui stai eseguendo PyInstaller GUI Wrapper. Inoltre, assicurati che la directory del progetto selezionata sia effettivamente un repository Git.