# Guida alla Creazione di Pacchetti DEB per ComfyUI Launcher

## Indice

1. [Introduzione](#introduzione)
2. [Prerequisiti](#prerequisiti)
3. [Concetti Fondamentali](#concetti-fondamentali)
4. [Struttura del Packaging Debian](#struttura-del-packaging-debian)
5. [File Essenziali](#file-essenziali)
6. [Processo di Build Automatizzato](#processo-di-build-automatizzato)
7. [Processo di Build Manuale](#processo-di-build-manuale)
8. [Verifica e Testing](#verifica-e-testing)
9. [Installazione e Distribuzione](#installazione-e-distribuzione)
10. [Troubleshooting](#troubleshooting)
11. [Best Practices](#best-practices)
12. [Risorse Aggiuntive](#risorse-aggiuntive)

## Introduzione

Questa guida spiega come creare pacchetti DEB per distribuzioni basate su Debian/Ubuntu. Un pacchetto DEB è un formato di archivio software utilizzato dal sistema di gestione pacchetti `dpkg` e dai suoi frontend come `apt`.

### Vantaggi dei Pacchetti DEB

- **Gestione dipendenze**: Risoluzione automatica delle dipendenze
- **Integrazione sistema**: Perfetta integrazione con il desktop environment
- **Facilità installazione**: Installazione con un doppio click o comando singolo
- **Aggiornamenti**: Aggiornamenti gestiti dal sistema
- **Rimozione pulita**: Disinstallazione completa senza residui

## Prerequisiti

### Pacchetti Sistema Richiesti

```bash
# Installa i pacchetti necessari per il packaging
sudo apt-get update
sudo apt-get install \
    build-essential \
    devscripts \
    debhelper \
    dh-python \
    python3-dev \
    python3-setuptools \
    python3-pip \
    python3-wheel \
    lintian \
    fakeroot \
    dh-make
```

### Conoscenze Prerequisite

- Conoscenza base della linea di comando Linux
- Comprensione dei sistemi di packaging Debian
- Familiarità con i Makefile (opzionale)
- Conoscenza di base di Python (per questo progetto specifico)

## Concetti Fondamentali

### Tipi di Pacchetti

1. **Source Package**: Contiene il codice sorgente e i metadati
2. **Binary Package**: Contiene i file compilati pronti per l'installazione

### Componenti Principali

- **Upstream Tarball**: L'archivio sorgente originale (`*.orig.tar.gz`)
- **Debian Directory**: Contiene tutti i file di packaging (`debian/`)
- **Control Files**: Definiscono metadati e dipendenze

### Naming Convention

- Source package: `nome-pacchetto_versione.orig.tar.gz`
- Binary package: `nome-pacchetto_versione-revisione_architettura.deb`

Esempio:
- `comfyui-launcher_1.0.0.orig.tar.gz` (sorgente)
- `comfyui-launcher_1.0.0-1_all.deb` (binario)

## Struttura del Packaging Debian

### Directory Structure

```
comfyui-launcher-1.0.0/
├── main.py                 # File sorgente principale
├── style.css              # File di stile
├── LICENSE                 # Licenza
├── README.md              # Documentazione
├── pyproject.toml         # Configurazione Python
└── debian/                # Directory di packaging
    ├── changelog          # Log delle modifiche
    ├── control           # Metadati e dipendenze
    ├── copyright         # Informazioni copyright
    ├── rules             # Script di build
    ├── compat            # Livello compatibilità debhelper
    ├── install           # File da installare
    ├── dirs              # Directory da creare
    ├── *.desktop         # File desktop
    ├── docs              # Documentazione da includere
    ├── watch             # Monitoraggio upstream
    └── source/
        └── format        # Formato source package
```

## File Essenziali

### 1. debian/changelog

Registra le modifiche al pacchetto:

```bash
comfyui-launcher (1.0.0-1) unstable; urgency=medium

  * Initial release.
  * Modern GTK4 launcher for ComfyUI with conda environment support

 -- Maintainer Name <email@example.com>  Mon, 29 Sep 2025 17:00:00 +0200
```

**Formato**: Molto rigido, rispetta esattamente la sintassi.

### 2. debian/control

Definisce metadati e dipendenze:

```bash
Source: comfyui-launcher
Section: graphics
Priority: optional
Maintainer: ComfyUI Launcher Team <your-email@example.com>
Build-Depends: debhelper-compat (= 13),
               dh-python,
               python3-all,
               python3-setuptools
Standards-Version: 4.6.2
Homepage: https://github.com/your-username/comfyui-launcher

Package: comfyui-launcher
Architecture: all
Depends: ${python3:Depends},
         ${misc:Depends},
         python3-gi,
         gir1.2-gtk-4.0,
         gir1.2-adw-1
Description: Modern GTK4 launcher for ComfyUI
 Detailed description here...
```

**Campi importanti**:
- `Build-Depends`: Pacchetti necessari per compilare
- `Depends`: Pacchetti necessari per l'esecuzione
- `Architecture`: `all` (indipendente) o `any` (dipendente)

### 3. debian/copyright

Informazioni legali:

```bash
Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: comfyui-launcher
Source: https://github.com/your-username/comfyui-launcher

Files: *
Copyright: 2025 ComfyUI Launcher Team
License: MIT

License: MIT
 [Testo completo della licenza MIT]
```

### 4. debian/rules

Script di build (Makefile):

```bash
#!/usr/bin/make -f

%:
	dh $@ --with python3 --buildsystem=pybuild

override_dh_auto_install:
	dh_auto_install
	install -Dm755 main.py debian/comfyui-launcher/usr/bin/comfyui-launcher
```

**Nota**: Usa TAB per l'indentazione, non spazi!

### 5. debian/source/format

Specifica il formato del source package:

```bash
3.0 (quilt)
```

## Processo di Build Automatizzato

### Utilizzo dello Script

```bash
# Rendi eseguibile lo script
chmod +x build-deb.sh

# Esegui il build
./build-deb.sh
```

### Cosa fa lo Script

1. **Verifica Prerequisites**: Controlla pacchetti installati
2. **Preparazione Environment**: Crea working directory in `/tmp/deb-build`
3. **Creazione Upstream Tarball**: Pacchetto sorgente originale
4. **Struttura Debian**: Crea tutti i file `debian/`
5. **Build Package**: Esegue `debuild`
6. **Verifica**: Testa con `lintian`
7. **Installazione Opzionale**: Propone installazione

### Output dello Script

```bash
[INFO] === Script di creazione pacchetto DEB per ComfyUI Launcher ===
[SUCCESS] Tutti i prerequisiti sono soddisfatti
[SUCCESS] Ambiente preparato in /tmp/deb-build/comfyui-launcher-1.0.0
[SUCCESS] Struttura debian/ creata
[SUCCESS] Pacchetto DEB costruito con successo
[SUCCESS] Pacchetto DEB verificato: ./comfyui-launcher_1.0.0-1_all.deb
```

## Processo di Build Manuale

### Step 1: Preparazione Upstream Tarball

```bash
# Crea il tarball originale
cd /tmp
mkdir deb-build && cd deb-build

# Copia e pacchetta i sorgenti
cp -r /path/to/source comfyui-launcher-1.0.0
tar -czf comfyui-launcher_1.0.0.orig.tar.gz comfyui-launcher-1.0.0/
cd comfyui-launcher-1.0.0
```

### Step 2: Inizializzazione con dh_make

```bash
# Inizializza la struttura debian (opzionale)
dh_make -s -p comfyui-launcher_1.0.0

# Oppure crea manualmente la directory
mkdir debian
```

### Step 3: Creazione File Debian

Crea manualmente tutti i file nella directory `debian/` come mostrato nella sezione precedente.

### Step 4: Build del Pacchetto

```bash
# Build senza firma (per sviluppo)
debuild -us -uc

# Oppure con dpkg-buildpackage
dpkg-buildpackage -us -uc -b
```

### Step 5: Verifica

```bash
# Controlla il pacchetto con lintian
lintian ../comfyui-launcher_*.deb

# Verifica contenuto
dpkg-deb --info ../comfyui-launcher_*.deb
dpkg-deb --contents ../comfyui-launcher_*.deb
```

## Verifica e Testing

### Controlli Automatici

```bash
# Lintian - controlla conformità policy Debian
lintian package.deb

# Verifica dipendenze
dpkg-deb --info package.deb

# Lista file
dpkg-deb --contents package.deb
```

### Testing Installazione

```bash
# Test installazione in ambiente pulito
sudo dpkg -i comfyui-launcher_*.deb

# Verifica dipendenze mancanti
sudo apt-get install -f

# Test funzionalità
comfyui-launcher --help

# Test rimozione
sudo apt-get remove comfyui-launcher
```

### Testing con Containers

```bash
# Test in container Docker
docker run -it ubuntu:latest
# Installa pacchetto e testa
```

## Installazione e Distribuzione

### Installazione Locale

```bash
# Metodo preferito (risolve dipendenze)
sudo apt install ./comfyui-launcher_1.0.0-1_all.deb

# Metodo alternativo
sudo dpkg -i comfyui-launcher_1.0.0-1_all.deb
sudo apt-get install -f  # risolve dipendenze
```

### Distribuzione

#### 1. Repository Personale

Crea un repository APT personale:

```bash
# Installa reprepro
sudo apt install reprepro

# Configura repository
mkdir -p ~/myrepo/conf
cat > ~/myrepo/conf/distributions << EOF
Codename: focal
Components: main
Architectures: all amd64
EOF

# Aggiungi pacchetto
reprepro -b ~/myrepo includedeb focal comfyui-launcher_*.deb
```

#### 2. PPA (Personal Package Archive)

Per Ubuntu, puoi creare un PPA su Launchpad:

1. Registrati su [Launchpad](https://launchpad.net)
2. Crea un PPA
3. Carica il source package firmato

#### 3. GitHub Releases

```bash
# Carica il .deb file come release asset
gh release create v1.0.0 comfyui-launcher_*.deb
```

## Troubleshooting

### Errori Comuni

#### Build Failures

**Errore**: `dh_auto_install failed`
```bash
# Soluzione: Verifica debian/rules e override_dh_auto_install
```

**Errore**: `missing build dependencies`
```bash
# Installa dipendenze mancanti
sudo apt-get build-dep .
```

#### Lintian Warnings

**Warning**: `binary-without-manpage`
```bash
# Aggiungi manpage o ignora per applicazioni GUI
```

**Error**: `copyright-file-missing`
```bash
# Verifica che debian/copyright esista e sia corretto
```

#### Dependency Issues

**Errore**: `dependency not found`
```bash
# Verifica nomi pacchetti con
apt-cache search package-name
```

### Debug del Build

```bash
# Build verbose
debuild -us -uc -- --verbose

# Solo specifici step
dh binary --no-act  # mostra cosa verrebbe eseguito
```

### Testing in Ambiente Pulito

```bash
# Usa pbuilder per build in ambiente pulito
sudo pbuilder create
sudo pbuilder build package.dsc
```

## Best Practices

### Naming e Versioning

- **Nome pacchetto**: lowercase, dash-separated
- **Versioning**: `upstream-version-debian-revision`
- **Incrementa debian revision** per bugfix senza cambio upstream

### Dependencies

- **Build-Depends**: Solo quello strettamente necessario
- **Depends**: Usa `${misc:Depends}` e `${shlibs:Depends}`
- **Recommends**: Per feature opzionali
- **Suggests**: Per integrazioni facoltative

### File Organization

- **Separa logica**: Un task per file debian
- **Documenta**: Commenta scelte non ovvie in debian/README.source
- **Testa**: Sempre testare installazione/rimozione

### Security

- **Firme**: Firma sempre i pacchetti per distribuzione
- **Permissions**: File eseguibili solo dove necessario
- **Paths**: Usa percorsi standard FHS

### Performance

- **Architecture**: Usa `all` se possibile per ridurre build time
- **Parallel Build**: Abilita build paralleli con `dh --parallel`

## Risorse Aggiuntive

### Documentazione Ufficiale

- [Debian New Maintainer's Guide](https://www.debian.org/doc/manuals/maint-guide/)
- [Debian Policy Manual](https://www.debian.org/doc/debian-policy/)
- [Ubuntu Packaging Guide](https://packaging.ubuntu.com/)

### Strumenti Utili

- **debhelper**: Sistema di build moderno
- **dh-make**: Template generator
- **lintian**: Policy checker
- **piuparts**: Installation/removal tester
- **pbuilder**: Clean build environment

### Community

- **IRC**: `#debian-mentors` su OFTC
- **Forum**: [Debian Forums](https://forums.debian.net/)
- **Mailing List**: debian-mentors@lists.debian.org

### Reference Files

Per questo progetto specifico, i file di esempio sono disponibili in:
- `build-deb.sh`: Script automatizzato
- `debian/`: Directory con tutti i file template

## Appendice: Comandi Rapidi

### Build Rapido

```bash
# Build completo
./build-deb.sh

# Solo build (senza setup)
debuild -us -uc
```

### Verifica Rapida

```bash
# Check policy compliance
lintian package.deb

# Test installation
sudo apt install ./package.deb
```

### Cleanup

```bash
# Pulisci build artifacts
debian/rules clean

# Reset working directory
git clean -fdx  # se in repo git
```

---

**Autore**: ComfyUI Launcher Team  
**Data**: 29 Settembre 2025  
**Versione Guida**: 1.0.0