## 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:
    ```bash
    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:

```bash
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.