enne2
/
gtk-comfyui-launcher
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2 Commits
1 Branch
1 Tag
201 KiB
 
 
 
Branch: master
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'master'
${ noResults }
gtk-comfyui-launcher/DEB_BUILD_GUIDE.md

12 KiB
Raw Permalink Blame History

Guida alla Creazione di Pacchetti DEB per ComfyUI Launcher

Indice

  1. Introduzione
  2. Prerequisiti
  3. Concetti Fondamentali
  4. Struttura del Packaging Debian
  5. File Essenziali
  6. Processo di Build Automatizzato
  7. Processo di Build Manuale
  8. Verifica e Testing
  9. Installazione e Distribuzione
  10. Troubleshooting
  11. Best Practices
  12. 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

  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:

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

  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

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

  1. Registrati su Launchpad
  2. Crea un PPA
  3. 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

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