add manual

doc/English-manual.md

@@ -0,0 +1,129 @@
+
+# PyInstaller GUI Wrapper - User Manual
+
+## English
+
+### 1. Introduction
+
+The **PyInstaller GUI Wrapper** is a desktop application that provides a graphical user interface (GUI) for PyInstaller, a popular tool for converting Python scripts into standalone executable applications. This wrapper aims to simplify the build process, especially for projects adhering to a specific directory structure, and offers features like automatic version information injection.
+
+### 2. Prerequisites
+
+Before using the PyInstaller GUI Wrapper, ensure you have the following installed:
+
+*   **Python 3.x:** The wrapper is a Python application itself.
+*   **PyInstaller:** This is the core tool used for building executables. Install it via pip:
+    ```bash
+    pip install pyinstaller
+    ```
+*   **Git (Recommended):** While optional, Git is required if you want the wrapper to automatically extract version information (tags, commit hashes, branch names) from your project's Git repository and inject it into your build.
+
+### 3. Launching the Application
+
+If you have the source code, you can run the PyInstaller GUI Wrapper from your terminal by navigating to its root directory and executing:
+
+```bash
+python -m pyinstallerguiwrapper
+```
+
+If you have a compiled executable of the wrapper, simply run that executable.
+
+### 4. Main Interface Overview
+
+The main window of the PyInstaller GUI Wrapper is divided into several sections:
+
+*   **Project Directory:**
+    *   **Main Project Directory:** An entry field (read-only) showing the path to the selected project.
+    *   **Browse...:** A button to open a dialog to select the root directory of the Python project you wish to build.
+*   **Derived Paths (Automatic):**
+    *   This section displays the paths that the wrapper automatically attempts to find based on your project directory selection and standard conventions. It helps verify if your project structure is recognized correctly.
+    *   **Script Found:** Shows the path to the detected `__main__.py` file.
+    *   **Spec File Found:** Shows the path to the detected `projectname.spec` file.
+    *   **Icon Found:** Shows the path to the detected `projectname.ico` (or platform-equivalent) file.
+    *   Status messages like "N/A" or "NOT FOUND!" will indicate if a file is not present or could not be located.
+*   **Options Tabs:**
+    *   **Basic Options (from Spec/GUI):**
+        *   **App Name:** The name of your application. This can be derived from the project name, loaded from an existing `.spec` file, or manually entered.
+        *   **Icon File:** Path to the application icon. Can be auto-detected, loaded from a spec, or selected manually using "Browse...". The "Clear" button removes the selection.
+        *   **Single File (One Executable):** Checkbox corresponding to PyInstaller's `--onefile` option. Creates a single executable file.
+        *   **Windowed (No Console):** Checkbox corresponding to PyInstaller's `--windowed` (or `--noconsole`) option. For GUI applications that should not open a console window.
+    *   **Additional Files (from Spec/GUI):**
+        *   **Files/Folders to Include:** A listbox displaying files or folders to be added to your application bundle.
+        *   **Add File...:** Opens a dialog to select an individual file to include.
+        *   **Add Folder...:** Opens a dialog to select an entire folder to include.
+        *   **Remove Selected:** Removes the highlighted item from the list.
+        *   When adding files/folders, you'll be prompted for the *destination path* within the bundle (e.g., `.` for the root, `data/` for a subfolder). Source paths are stored relative to the project root.
+*   **Build Log:** A text area that displays real-time output and log messages from the PyInstaller build process and from the wrapper itself.
+*   **Build Executable:** The main action button to start the build process. It is disabled until a valid project directory with the essential files is selected.
+
+### 5. Workflow: Building Your Python Project
+
+#### 5.1. Selecting Your Project
+
+1.  Click the **"Browse..."** button in the "Project Directory" section.
+2.  Navigate to and select the **root directory** of the Python project you want to package.
+    *   **Expected Project Structure:** The wrapper works best with projects structured as follows:
+        ```
+        YourProjectRoot/
+        ├── yourprojectroot/      # Source code subfolder (lowercase project name)
+        │   ├── __init__.py
+        │   ├── __main__.py     # Main entry point for your application
+        │   └── ... (other .py files and sub-packages)
+        ├── yourprojectroot.spec  # PyInstaller spec file (optional, will be generated/overwritten)
+        └── yourprojectroot.ico   # Application icon (optional, platform extensions vary)
+        ```
+3.  Once selected, the "Derived Paths" section will update, showing which of the expected files were found. If essential files like `__main__.py` or the `.spec` file (if you intend to use an existing one that is then modified by the GUI) are not found, the "Build Executable" button may remain disabled.
+
+#### 5.2. Automatic Version File Generation (`_version.py`)
+
+If the selected project directory (`YourProjectRoot`) is a Git repository:
+
+1.  The wrapper will attempt to extract version information (latest tag, commit hash, current branch, and dirty status if any uncommitted changes exist).
+2.  It will then automatically create or overwrite a file named `_version.py` inside your project's source subfolder (e.g., `YourProjectRoot/yourprojectroot/_version.py`).
+3.  This `_version.py` file will contain:
+    *   Variables like `__version__`, `GIT_COMMIT_HASH`, `GIT_BRANCH`, `BUILD_TIMESTAMP`, and `IS_GIT_REPO`.
+    *   A helper function `get_version_string(format_string=None)` that you can call from your application's code to get a formatted string of this version information.
+    *   Example of `format_string` placeholders: `{{version}}`, `{{tag}}`, `{{commit_short}}`, `{{branch}}`, `{{dirty}}`, `{{timestamp}}`.
+4.  If the project directory is not a Git repository, or if Git commands fail, `_version.py` will still be created but will contain default "unknown" values.
+
+*To use this in your application, import `_version` and call `_version.get_version_string()` or access the variables directly. See the README.md for an example.*
+
+#### 5.3. Configuring Build Options
+
+1.  **Basic Options:**
+    *   Review and set the **App Name**.
+    *   Select an **Icon File** if desired (this overrides any auto-detected icon or icon from a loaded spec).
+    *   Choose between **Single File** (one-file build) or a directory build (one-dir, by unchecking "Single File"). One-dir is often more stable for GUI applications.
+    *   Select **Windowed (No Console)** for GUI applications. Uncheck it for console-based applications.
+2.  **Additional Files:**
+    *   Use **"Add File..."** or **"Add Folder..."** to include any necessary data files, assets, or non-Python dependencies.
+    *   You will be prompted for the destination path within the application bundle. For example, if you add `assets/image.png` and specify the destination as `images`, it will be available in your bundled app at `images/image.png`.
+    *   Paths are relative to the `.spec` file (which is in your project root).
+
+*Note: If a `.spec` file was found in your project root, its options are loaded into the GUI. Any changes you make in the GUI will be used to regenerate and overwrite this `.spec` file before the build starts.*
+
+#### 5.4. Starting the Build
+
+1.  Once you have selected your project and configured the options, click the **"Build Executable"** button.
+2.  The wrapper will:
+    *   Generate/update the `_version.py` file in your target project's source folder.
+    *   Generate/update the `.spec` file in your project root based on the current GUI settings.
+    *   Execute PyInstaller in a separate thread.
+3.  The **Build Log** will show real-time output from PyInstaller.
+4.  Upon completion (or failure), a message box will appear, and the build log will contain the final status.
+
+#### 5.5. Locating the Executable
+
+*   If the build is successful, the bundled application will be located in a subfolder named `_dist` (by default) within your selected project directory (e.g., `YourProjectRoot/_dist/YourAppName/`).
+*   Temporary build files will be in a `_build` subfolder.
+
+### 6. Tips and Troubleshooting
+
+*   **"NOT FOUND!" in Derived Paths:** Double-check your project's folder structure and file naming against the expected conventions. Ensure the `__main__.py` and (if you're relying on an existing one) `projectname.spec` files are correctly placed.
+*   **Build Fails / Executable Doesn't Run:**
+    1.  **Check the Build Log:** Look for errors or warnings from PyInstaller.
+    2.  **Console Mode for Debugging:** If your executable doesn't start, temporarily edit the generated `.spec` file (e.g., `yourprojectroot.spec`) and change `console=False` to `console=True` in the `EXE()` block. Then, rebuild by running `pyinstaller yourprojectroot.spec --clean` from the command line in your project root. When you run the executable, a console window will appear and show any Python errors.
+    3.  **Hidden Imports:** Some Python libraries use dynamic imports that PyInstaller might miss. You may need to add them to the `hiddenimports` list in your `.spec` file or via a hook file.
+*   **Git Information Not Injected:** Ensure Git is installed and accessible in your system's PATH on the machine where you are running the PyInstaller GUI Wrapper. Also, ensure the project directory you selected is indeed a Git repository.
+
+---

doc/Italian-manual.md

@@ -0,0 +1,124 @@
+## 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.