12 KiB

Raw Blame History

Guida alla Creazione di Pacchetti DEB per ComfyUI Launcher

Indice

Introduzione
Prerequisiti
Concetti Fondamentali
Struttura del Packaging Debian
File Essenziali
Processo di Build Automatizzato
Processo di Build Manuale
Verifica e Testing
Installazione e Distribuzione
Troubleshooting
Best Practices
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

# 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

Source Package: Contiene il codice sorgente e i metadati
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:

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:

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:

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):

#!/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:

3.0 (quilt)

Processo di Build Automatizzato

Utilizzo dello Script

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

# Esegui il build
./build-deb.sh

Cosa fa lo Script

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

Output dello Script

[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

# 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

# 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

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

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

Step 5: Verifica

# 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

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

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

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

Testing Installazione

# 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

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

Installazione e Distribuzione

Installazione Locale

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

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

Registrati su Launchpad
Crea un PPA
Carica il source package firmato

3. GitHub Releases

# 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

# Soluzione: Verifica debian/rules e override_dh_auto_install

Errore: missing build dependencies

# Installa dipendenze mancanti
sudo apt-get build-dep .

Lintian Warnings

Warning: binary-without-manpage

# Aggiungi manpage o ignora per applicazioni GUI

Error: copyright-file-missing

# Verifica che debian/copyright esista e sia corretto

Dependency Issues

Errore: dependency not found

# Verifica nomi pacchetti con
apt-cache search package-name

Debug del Build

# Build verbose
debuild -us -uc -- --verbose

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

Testing in Ambiente Pulito

# 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

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
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

# Build completo
./build-deb.sh

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

Verifica Rapida

# Check policy compliance
lintian package.deb

# Test installation
sudo apt install ./package.deb

Cleanup

# 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

12 KiB Raw Blame History