Quartz 4

Builder di Distribuzione Portable - build_portable.py

2 min read

build_portable.py

1. Scopo e Contesto d’Uso

Lo script build_portable.py è il motore di build ufficiale per la distribuzione di FIRE. Il suo scopo è trasformare l’ambiente di sviluppo Python (che richiede installazione e configurazione complesse) in un artefatto “Zero-Configuration”: una cartella o un file .exe che può essere eseguito su qualsiasi macchina Windows senza pre-requisiti.

È progettato specificamente per gestire le complessità delle librerie di Intelligenza Artificiale (torch, prophet, timesfm), che spesso causano fallimenti con i tool di build standard a causa di file di dati nascosti o dipendenze binarie non standard.

2. Funzionalità Principali

Lo script agisce come un wrapper intelligente attorno a PyInstaller, configurando automaticamente tutti i parametri necessari per una build di successo:

  • Gestione Hidden Imports: Include automaticamente moduli che vengono caricati dinamicamente a runtime (es. sklearn.utils, scipy.special) e che PyInstaller non rileverebbe da solo.
  • Inclusione Risorse: Copia automaticamente le cartelle resources/ (icone, template) e prompts/ all’interno del pacchetto distribuito.
  • Fix per Librerie AI (--collect-all): Applica la strategia di raccolta totale per pacchetti problematici come prophet, timesfm, chronos e cmdstanpy. Questo risolve errori comuni come FileNotFoundError: __version__.py copiando l’intero pacchetto sorgente nel dist.
  • Pulizia Automatica: Esegue una pulizia della cache di build (--clean) ad ogni lancio per evitare artefatti corrotti.

3. Workflow Operativo

Lo script si esegue direttamente dalla root del progetto:

python build_portable.py

Modalità di Build (Console vs Windowed)

Lo script è configurato di default in modalità Console (--console) per facilitare il debugging:

  • Fase di Test: La finestra nera (console) appare all’avvio dell’exe. Se l’app crasha, l’errore (Traceback) rimane visibile.
  • Fase di Rilascio: Per la versione finale, si deve modificare lo script commentando --console e scommentando --windowed.

Output

Il risultato della build si trova nella cartella dist/FIRE_Portable/. L’intera cartella deve essere distribuita.

4. Quando Usarlo

  • Rilascio di Versione: Ogni volta che si vuole creare una versione stabile da consegnare agli utenti.
  • Test su Macchina Pulita: Per verificare che l’applicazione funzioni su un computer che non ha Python o CUDA installati.
  • Backup Eseguibile: Per creare una copia “congelata” e funzionante dell’applicazione in un determinato stato.

5. Riferimenti

Graph View