# Guida Completa: Creare un Pacchetto RPM per ComfyUI Launcher

Questa guida ti mostrerà come creare un pacchetto RPM per l'applicazione ComfyUI Launcher, una moderna interfaccia GTK4 per lanciare ComfyUI con supporto per ambienti conda.

## Indice

1. [Prerequisiti](#prerequisiti)
2. [Struttura del Progetto](#struttura-del-progetto)
3. [Preparazione dell'Ambiente RPM](#preparazione-dellambiente-rpm)
4. [Creazione del File SPEC](#creazione-del-file-spec)
5. [Processo di Build Automatizzato](#processo-di-build-automatizzato)
6. [Build Manuale Step-by-Step](#build-manuale-step-by-step)
7. [Verifica e Test](#verifica-e-test)
8. [Installazione e Distribuzione](#installazione-e-distribuzione)
9. [Troubleshooting](#troubleshooting)
10. [Best Practices](#best-practices)

## Prerequisiti

### Distribuzione Linux Supportate
- **Fedora** (38+)
- **CentOS Stream** (8+)
- **RHEL** (8+)
- **openSUSE** (Leap 15.4+)
- **AlmaLinux/Rocky Linux** (8+)

### Pacchetti Necessari

#### Su Fedora/CentOS Stream/RHEL:
```bash
# Fedora
sudo dnf install rpm-build rpm-devel rpmlint rpmdevtools python3-devel \
                 python3-setuptools desktop-file-utils libappstream-glib \
                 gcc make python3-pip

# CentOS/RHEL (con EPEL)
sudo yum install epel-release
sudo yum install rpm-build rpm-devel rpmlint rpmdevtools python3-devel \
                 python3-setuptools desktop-file-utils libappstream-glib \
                 gcc make python3-pip
```

#### Su openSUSE:
```bash
sudo zypper install rpm-build rpmlint python3-devel python3-setuptools \
                    desktop-file-utils libappstream-glib-devel gcc make \
                    python3-pip
```

### Dipendenze Runtime
- **Python 3.9+**
- **GTK4** (4.6+)
- **libadwaita** (1.0+)
- **PyGObject** (3.42+)
- **conda** (per la gestione ambienti)

## Struttura del Progetto

Il progetto ComfyUI Launcher ha la seguente struttura:

```
gtk-app/
├── main.py                    # Applicazione principale
├── style.css                  # Stili GTK4
├── pyproject.toml             # Configurazione progetto Python
├── requirements.txt           # Dipendenze Python
├── LICENSE                    # Licenza MIT
├── README.md                  # Documentazione italiana
├── README_EN.md               # Documentazione inglese
├── CHANGELOG.md               # Cronologia cambiamenti
├── config.example.json        # Configurazione esempio
├── install.sh                 # Script di installazione
├── comfyui-launcher.spec      # File SPEC per RPM
└── build-rpm.sh              # Script automatizzato per build RPM
```

## Preparazione dell'Ambiente RPM

### 1. Setup Directory RPM

Crea la struttura di directory standard per RPM:

```bash
# Crea la struttura RPM
rpmdev-setuptree

# Verifica la struttura creata
tree ~/rpmbuild/
```

La struttura creata sarà:
```
~/rpmbuild/
├── BUILD        # Directory di build temporanea
├── RPMS         # RPM binari finali
├── SOURCES      # Codice sorgente e patch
├── SPECS        # File SPEC
└── SRPMS        # RPM sorgente
```

### 2. Verifica Macros RPM

Controlla le macro RPM disponibili:

```bash
# Macro Python
rpm --eval %{python3}
rpm --eval %{python3_sitelib}
rpm --eval %{python3_sitearch}

# Macro directory standard
rpm --eval %{_bindir}
rpm --eval %{_datadir}
rpm --eval %{_docdir}
```

## Creazione del File SPEC

Il file SPEC (`comfyui-launcher.spec`) è già stato creato con la seguente struttura:

### Sezione Preamble
```spec
Name:           comfyui-launcher
Version:        1.0.0
Release:        1%{?dist}
Summary:        A modern GTK4 launcher for ComfyUI with conda environment support

License:        MIT
URL:            https://github.com/your-username/comfyui-launcher
Source0:        %{name}-%{version}.tar.gz

BuildArch:      noarch
BuildRequires:  python3-devel
BuildRequires:  python3-setuptools
# ... altre dipendenze
```

### Sezioni Principali
- **%description**: Descrizione dettagliata dell'applicazione
- **%prep**: Preparazione del codice sorgente
- **%build**: Processo di build
- **%install**: Installazione nell'ambiente di build
- **%files**: Lista dei file inclusi nel pacchetto
- **%changelog**: Cronologia delle modifiche

## Processo di Build Automatizzato

### Utilizzo dello Script Automatizzato

Lo script `build-rpm.sh` automatizza tutto il processo:

```bash
# Esegui lo script di build
./build-rpm.sh
```

Lo script eseguirà automaticamente:

1. **Verifica prerequisiti**: Controlla che tutti i pacchetti necessari siano installati
2. **Setup ambiente**: Configura la struttura RPM
3. **Creazione archivio**: Crea l'archivio sorgente tar.gz
4. **Validazione SPEC**: Verifica il file SPEC con rpmlint
5. **Build SRPM**: Crea il pacchetto sorgente
6. **Build RPM**: Crea il pacchetto binario
7. **Verifica finale**: Testa il pacchetto creato

### Output dello Script

Lo script produrrà output colorato per ogni fase:
- 🔵 **[INFO]**: Informazioni generali
- 🟢 **[SUCCESS]**: Operazioni completate con successo
- 🟡 **[WARNING]**: Avvisi non critici
- 🔴 **[ERROR]**: Errori che bloccano il processo

## Build Manuale Step-by-Step

Se preferisci eseguire il processo manualmente:

### 1. Preparazione Archivio Sorgente

```bash
# Crea directory temporanea
TEMP_DIR=$(mktemp -d)
PROJECT_NAME="comfyui-launcher-1.0.0"

# Copia file progetto
mkdir -p "$TEMP_DIR/$PROJECT_NAME"
cp main.py style.css LICENSE README*.md CHANGELOG.md \
   pyproject.toml requirements.txt config.example.json \
   "$TEMP_DIR/$PROJECT_NAME/"

# Crea archivio
cd "$TEMP_DIR"
tar -czf ~/rpmbuild/SOURCES/comfyui-launcher-1.0.0.tar.gz "$PROJECT_NAME"

# Pulisci
rm -rf "$TEMP_DIR"
```

### 2. Copia File SPEC

```bash
cp comfyui-launcher.spec ~/rpmbuild/SPECS/
```

### 3. Verifica File SPEC

```bash
cd ~/rpmbuild/SPECS
rpmlint comfyui-launcher.spec
```

### 4. Build SRPM

```bash
rpmbuild -bs comfyui-launcher.spec
```

### 5. Build RPM Binario

```bash
rpmbuild -bb comfyui-launcher.spec
```

## Verifica e Test

### 1. Verifica con rpmlint

```bash
# Verifica SRPM
rpmlint ~/rpmbuild/SRPMS/comfyui-launcher-*.src.rpm

# Verifica RPM binario
rpmlint ~/rpmbuild/RPMS/noarch/comfyui-launcher-*.rpm
```

### 2. Ispezione Contenuto Pacchetto

```bash
# Lista file nel pacchetto
rpm -qlp ~/rpmbuild/RPMS/noarch/comfyui-launcher-*.rpm

# Informazioni pacchetto
rpm -qip ~/rpmbuild/RPMS/noarch/comfyui-launcher-*.rpm

# Dipendenze
rpm -qRp ~/rpmbuild/RPMS/noarch/comfyui-launcher-*.rpm
```

### 3. Test Installazione

```bash
# Test installazione (dry-run)
rpm -ivh --test ~/rpmbuild/RPMS/noarch/comfyui-launcher-*.rpm

# Installazione reale
sudo rpm -ivh ~/rpmbuild/RPMS/noarch/comfyui-launcher-*.rpm

# Oppure con DNF (raccomandato)
sudo dnf install ~/rpmbuild/RPMS/noarch/comfyui-launcher-*.rpm
```

## Installazione e Distribuzione

### Installazione Locale

```bash
# Metodo 1: DNF (gestisce dipendenze automaticamente)
sudo dnf install ~/rpmbuild/RPMS/noarch/comfyui-launcher-*.rpm

# Metodo 2: RPM diretto
sudo rpm -ivh ~/rpmbuild/RPMS/noarch/comfyui-launcher-*.rpm
```

### Verifica Installazione

```bash
# Verifica pacchetto installato
rpm -qi comfyui-launcher

# Verifica file installati
rpm -ql comfyui-launcher

# Test esecuzione
comfyui-launcher --help
```

### Distribuzione

#### Repository Locale

```bash
# Crea repository locale
mkdir -p ~/rpm-repo
cp ~/rpmbuild/RPMS/noarch/comfyui-launcher-*.rpm ~/rpm-repo/
createrepo ~/rpm-repo

# Aggiungi repository
sudo tee /etc/yum.repos.d/local-comfyui.repo << EOF
[local-comfyui]
name=Local ComfyUI Launcher Repository
baseurl=file://$HOME/rpm-repo
enabled=1
gpgcheck=0
EOF
```

#### Distribuzione Web

```bash
# Carica su server web
scp ~/rpmbuild/RPMS/noarch/comfyui-launcher-*.rpm user@server:/var/www/html/rpms/

# Su server
createrepo /var/www/html/rpms/
```

## Troubleshooting

### Problemi Comuni

#### 1. Errore "BuildRequires not found"

```bash
# Soluzione: Installa dipendenze mancanti
sudo dnf install python3-devel python3-setuptools desktop-file-utils
```

#### 2. Errore "File not found" durante %install

Verifica che tutti i file referenziati nel file SPEC esistano:
```bash
# Controlla file presenti nell'archivio
tar -tzf ~/rpmbuild/SOURCES/comfyui-launcher-1.0.0.tar.gz
```

#### 3. Warning rpmlint su desktop file

```bash
# Valida manualmente desktop file
desktop-file-validate /path/to/comfyui-launcher.desktop
```

#### 4. Errori di dipendenze GTK4

```bash
# Fedora
sudo dnf install gtk4-devel libadwaita-devel

# CentOS/RHEL (potrebbe richiedere repository aggiuntivi)
sudo dnf install gtk4-devel libadwaita-devel
```

### Debug Build Fallito

```bash
# Controlla log build dettagliato
rpmbuild -bb --verbose comfyui-launcher.spec

# Controlla directory BUILD per errori
ls -la ~/rpmbuild/BUILD/

# Mantieni directory BUILD per debug
rpmbuild -bb --short-circuit comfyui-launcher.spec
```

## Best Practices

### 1. Versionamento

- Usa [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PATCH)
- Incrementa `Release` per modifiche al packaging
- Reset `Release` a 1 per nuove `Version`

### 2. Dipendenze

```spec
# Specifica versioni minime
Requires: python3 >= 3.9
Requires: gtk4 >= 4.6

# Usa suggests per dipendenze opzionali
Suggests: python3-psutil
```

### 3. File di Configurazione

```spec
# Proteggi file di configurazione
%config(noreplace) %{_sysconfdir}/%{name}/config.json
```

### 4. Documentazione

```spec
# Includi documentazione completa
%doc README.md README_EN.md CHANGELOG.md
%license LICENSE
```

### 5. Script Pre/Post Installazione

```spec
%post
# Aggiorna cache icone
touch --no-create %{_datadir}/icons/hicolor &>/dev/null || :

%postun
if [ $1 -eq 0 ] ; then
    touch --no-create %{_datadir}/icons/hicolor &>/dev/null
    gtk-update-icon-cache %{_datadir}/icons/hicolor &>/dev/null || :
fi
```

### 6. Testing

- Testa sempre su un sistema pulito
- Verifica installazione/disinstallazione
- Controlla che l'applicazione si avvii correttamente
- Testa su diverse distribuzioni RPM

### 7. Sicurezza

```spec
# Non eseguire come root durante build
%if "%{_build_vendor}" == "redhat"
%global _hardened_build 1
%endif
```

## Conclusione

Hai ora una guida completa per creare pacchetti RPM per ComfyUI Launcher. Il processo automatizzato tramite `build-rpm.sh` semplifica notevolmente la creazione, mentre la guida manuale ti permette di comprendere ogni passaggio.

### File Creati

Al termine del processo avrai:
- **SRPM**: `~/rpmbuild/SRPMS/comfyui-launcher-1.0.0-1.*.src.rpm`
- **RPM Binario**: `~/rpmbuild/RPMS/noarch/comfyui-launcher-1.0.0-1.*.noarch.rpm`

### Prossimi Passi

1. **Test su Diverse Distribuzioni**: Testa il pacchetto su Fedora, CentOS, RHEL
2. **Automazione CI/CD**: Integra il build in pipeline automatizzate
3. **Repository Ufficiali**: Considera la submission a repository ufficiali (EPEL, RPM Fusion)
4. **Signature**: Implementa la firma GPG per i pacchetti
5. **Copr**: Pubblica su [Fedora Copr](https://copr.fedorainfracloud.org/) per distribuzione automatica

### Risorse Aggiuntive

- [Fedora Packaging Guidelines](https://docs.fedoraproject.org/en-US/packaging-guidelines/)
- [RPM Packaging Guide](https://rpm-packaging-guide.github.io/)
- [Python Packaging Guidelines](https://docs.fedoraproject.org/en-US/packaging-guidelines/Python/)
- [Desktop Application Guidelines](https://docs.fedoraproject.org/en-US/packaging-guidelines/#_desktop_applications)

---

**Happy RPM Building! 🚀**