********************** Pacchetti e Repository ********************** La distribuzione FUSS comprende un repository di pacchetti aggiuntivi rispetto alla base (Debian), disponibile all'indirizzo https://archive.fuss.bz.it/ ed ospitato su ``isolda.fuss.bz.it`` nella directory ``/iso/repo``. Build dei pacchetti =================== Nei repository del software sviluppato per FUSS è presente la directory ``debian`` contenente i file necessari per la generazione dei pacchetti ``.deb``. Setup ----- Per effettuare build locali dei pacchetti è necessario installare alcuni strumenti di sviluppo:: # apt install devscripts dput-ng dh-systemd .. note:: Assicurarsi di aver installato anche i Recommends dei pacchetti (questo è il comportamento di default di ``apt``, a meno che non lo si sia disabilitato manualmente), in particolare nel caso di ``dput-ng``. Inoltre è necessario impostare le variabili di ambiente ``DEBEMAIL`` e ``DEBFULLNAME``, contenenti rispettivamente il nome completo e l'email dello sviluppatore, che verranno usate per aggiornare alcuni metadati. Per usare ``dput-ng`` per effettuare gli upload serve configurarlo creando il file ``~/.dput.d/profiles/fuss-.json`` contenente:: { "method": "sftp", "fqdn": "archive.fuss.bz.it", "incoming": "/iso/incoming/", "allow_dcut": false, "allowed-distribution": {}, "codenames": null, "post_upload_command": "ssh -S none isolda.fuss.bz.it 'sudo /iso/bin/post-upload'", "hooks": [ "allowed-distribution", "checksum", "suite-mismatch" ] } dove ```` è ``jessie`` per FUSS server e ``stretch`` per FUSS client. Assicurarsi inoltre di poter accedere via ssh a ``isolda.fuss.bz.it`` senza ulteriori opzioni; ad esempio potrebbe essere necessario aggiungere quanto segue a ``~/.ssh/config``:: Host isolda.fuss.bz.it User root .. note:: dput-ng usa paramiko per effettuare le connessioni ssh; questo implica che le opzioni impostate direttamente in ``~/.ssh/config`` vengono lette correttamente, ma non c'è supporto per l'uso di ``Include`` per suddividere la configurazione su più file. Inoltre non verrà salvato il fingerprint dei server, ma verrà chiesto ogni volta di verificarlo. A luglio 2018 i fingerprint di isolda sono:: 256 SHA256:aLTgA+Trj5iYo0dl0i8Q82aigs3K/dPwDbazrvG95YY root@isolda (ECDSA) 256 SHA256:7i6j0jXPWRrW6LXDGbR+HWr3AFJi6gGSmdW41uBRJV4 root@isolda (ED25519) 2048 SHA256:OkP1maDf0pSIGCdq1mph8oI8CTADMrFXfe3aty608SA root@isolda (RSA) Chroot '''''' I pacchetti ``.deb`` vanno buildati all'interno della versione di destinazione in cui andranno installati; il modo più semplice per farlo è creare una chroot ed installarvi gli strumenti di base per la generazione di pacchetti:: # mkdir _build # debootstrap _build () # chroot _build # apt install debhelper devscripts dpkg-dev dove ```` è al momento (settembre 2018) ``jessie`` per il FUSS server e ``stretch`` per il FUSS client. In alternativa, vedere la sezione :ref:`cowbuilder` per gestire automaticamente le chroot, inclusa l'installazione automatica delle eventuali dipendenze necessarie. Clone del repository -------------------- Clonare il repository del progetto desiderato:: git clone https://work.fuss.bz.it/git/ Il branch da buildare per l'upload è ``master``, da aggiornare nel caso in cui si abbia già un clone locale del repository:: git checkout master git pull Versionamento ------------- Per poter pubblicare il pacchetto, è necessario incrementare il numero di versione nel file ``debian/changelog``. Il numero di versione da dare dipende dal tipo di pacchetto, come descritto nella sezione :ref:`versionamento` e nelle guide di sviluppo degli specifici pacchetti, ma nella maggior parte dei casi sarà da incrementare il patch level (es. da 9.0.5-1 a 9.0.6-1). .. note:: Nei pacchetti contenenti programmi in python è generalmente necessario mantenere aggiornato il numero di versione anche in ``setup.py``; come per debsrc sopra questo dovrebbe essere citato nel README dei pacchetti. Il programma ``dch``, permette di automatizzare l'editing del file ``debian/changelog`` che contiene la versione del pacchetto. * Quando si iniziano a fare modifiche usare il comando ``dch -v `` per creare una nuova stanza ed aprire il changelog nell'editor di default. Verrà impostato il numero di versione richiesto e la release speciale ``UNRELEASED`` che indica che le modifiche sono ancora in lavorazione. Si può anche usare ``dch`` senza opzioni: in questo modo se l'ultima stanza risulta ``UNRELEASED`` il file verrà aperto così com'è, mentre se l'ultima stanza riporta una release come ``unstable`` ne viene creata una nuova incrementando il numero di versione. Attenzione che in quest'ultimo caso dch potrebbe non essere in grado di indovinare la versione corretta: verificare e nel caso correggere. Inoltre, nel caso in cui non si sia elencati tra i Maintainer e Uploaders in ``debian/control`` verrà aggiunta una riga ``Non Maintainer Upload`` che per noi non è rilevante e va tolta. Nel caso in cui più persone facciano modifiche, dch provvederà a suddividerle in sezioni intestate con il nome della persona che ha effettuato la modifica. * Descrivere le modifiche effettuate, possibilmente indicando i ticket di riferimento da cui nascono le richieste di modifica. * Man mano che si fanno modifiche, descriverle se necessario nel changelog, usando ``dch`` senza opzioni, come descritto sopra. * Quando si è pronti a pubblicare il pacchetto, modificare ``UNRELEASED`` con ``unstable`` nella prima riga; questo si può fare anche con il comando ``dch -r``. Build ----- Alcuni pacchetti, come octofussd necessitano della preventiva creazione del tar dei sorgenti originali, come specificato nel README dei rispettivi repository; in tal caso prima di eseguire il comando precedente è necessario eseguire, nella directory principale del repository:: debian/rules debsrc Per eseguire il build del pacchetto, nella directory principale del repository eseguire:: dpkg-buildpackage -us -uc Se la procedura va a buon fine, nella directory superiore si troveranno i pacchetti ``.deb`` generati, e anche i file ``.changes``, ``.dsc`` e ``.tar.gz`` con il sorgente del pacchetto. La procedura potrebbe fallire con un errore contenente:: Unmet build dependencies: in tal caso installare semplicemente i pacchetti e riprovare. Tali dipendenze sono elencate nel campo ``Build-Depends`` del file ``debian/control``, nel caso ci si voglia assicurare di averle già installate prima di buildare. Test ---- Tramite ``dpkg -i .deb`` si puo' installare e testare il pacchetto. Si ricorda che ``dpkg`` non risolve le dipendenze, quindi darà un errore nel caso si sia aggiunta una nuova dipendenza. Per installare le dipendenze mancanti si può usare il comando:: apt -f install Un altro comando utile è ``dpkg -c .deb`` per verificare i file presenti nel pacchetto. Commit e push ------------- Eseguire il commit su git di tutte le modifiche apportate, indicando se possibile nel commit log il numero di ticket associato alla modifica, con la dicitura "refs #NUMERO". Un metodo veloce è eseguire:: git commit -a -m ". refs #NumeroTicket" e successivamente eseguire il push con:: git push Upload ------ Per uploadare il pacchetto buildato con ``dput-ng`` è sufficiente usare il comando:: dput fuss- nomepacchetto_versione_arch.changes Nel caso si voglia procedere manualmente invece si possono copiare i file generati su ``isolda`` nella directory ``/iso/incoming/`` ed aggiornare il repository con il comando:: # /iso/bin/post-upload Verificare poi che in ``/iso/incoming/`` non siano rimasti file spuri, e nel caso cancellarli a mano. .. _cowbuilder: Build dei pacchetti con cowbuilder ================================== cowbuilder e pbuilder sono degli strumenti per gestire delle chroot all'interno delle quali effettuare build di pacchetti in un ambiente pulito e abbastanza isolato dal sistema base. Buildare pacchetti all'interno di un sistema isolato è utile per evitare influenze da parte del proprio sistema (con librerie ed altre dipendenze già installate, magari in versioni non standard), ma è anche comodo nel caso si vogliano generare pacchetti per distribuzioni diverse da quelle in uso (ad esempio buildare per jessie o stretch su un sistema buster) Setup ----- Oltre a quanto indicato nelle istruzioni di setup generale, installare cowbuilder e pbuilder:: # apt install pbuilder cowbuilder Quindi creare le chroot base per le distribuzioni attualmente (agosto 2018) in uso stretch e jessie:: # cowbuilder --create --distribution stretch --debootstrap debootstrap --basepath /var/cache/pbuilder/base-stretch.cow # cowbuilder --create --distribution jessie --debootstrap debootstrap --basepath /var/cache/pbuilder/base-jessie.cow Nel caso in cui le chroot siano state create da un po' di tempo è opportuno aggiornarle, coi seguenti comandi:: # cowbuilder --update --basepath /var/cache/pbuilder/base-stretch.cow/ # cowbuilder --update --basepath /var/cache/pbuilder/base-jessie.cow/ Build ----- Una volta clonato o aggiornato il repository del pacchetto, aggiornata la versione come sopra, e se necessario genererato la tarball sorgente con ``debian/rules debsrc`` si può quindi usare ``pdebuild`` per eseguire la build del pacchetto all'interno di una chroot opportuna (sostituendo ``stretch`` con ``jessie`` nel caso del fuss server):: $ DIST=stretch pdebuild --use-pdebuild-internal --pbuilder cowbuilder -- --basepath /var/cache/pbuilder/base-stretch.cow/ ``pdebuild`` provvederà autonomamente ad installare le dipendenze necessarie all'interno della chroot e ad effettuare la build. Generalmente, l'infrastruttura di build [#infrastruttura]_ è in grado di capire dal numero di versione ed altri indizi se sia necessario o meno includere la tarball ``.orig`` tra ciò che va uploadato. Nel caso in cui però si stia effettuando un backport questo non è automatico: per il primo backport di una certa versione upstream è necessario prevedere l'inclusione della tarball sorgente con l'opzione ``--debbuildopts "-sa"``, ovvero:: $ DIST=stretch pdebuild --buildresult ../build/ --use-pdebuild-internal --pbuilder cowbuilder --debbuildopts "-sa" -- --basepath /var/cache/pbuilder/base-stretch.cow/ A questo punto si può procedere con test, commit+push ed upload come nel caso generale. .. [#infrastruttura] In particolare, l'inclusione o meno della tarball sorgente è decisa ed effettuata da ``dpkg-genchanges``, richiamato da ``dpkg-buildpackage`` al quale ``pdebuild`` passa le opzioni specificate con il parametro ``--debbuildopts``. Generalmente questo avviene in automatico, senza bisogno di preoccuparsi di chi faccia cosa. .. _versionamento: Policy di versionamento ======================= Software sviluppato per FUSS ---------------------------- Per i pacchetti sviluppati specificatamente per FUSS possono esserci policy specifiche indicate nella relativa guida sviluppatori e/o nei README dei progetti. In generale, lo schema usato prevede che la major version corrisponda alla versione di fuss per cui è rilasciato il pacchetto (che a sua volta corrisponde alla versione di debian su cui è basta). Un pacchetto per FUSS 8 avrà quindi versione tipo 8.X.Y, uno per FUSS 9 9.X.Y eccetera. I pacchetti possono essere nativi o meno: nel primo caso il numero di versione è del tipo 9.X.Y sia per il pacchetto che in ``setup.py``, mentre nel secondo si aggiunge un numero di revisione, es. 9.X.Y-Z; quest'ultimo va incrementato quando la nuova versione presenta modifiche nella pacchettizzazione (ovvero nella directory debian), ma non nel codice. I pacchetti nativi devono anche avere ``3.0 (native)`` nel file ``debian/source/format``, mentre i pacchetti non-nativi devono avere ``3.0 (quilt)`` e per buildarli è necessario generare una tarball sorgente (``_<9.X.Z>.orig.tar.gz``), ad esempio tramite ``debsrc``. Rebuild di pacchetti di debian ------------------------------ Per i pacchetti presi da debian e ribuildati da noi seguiamo una convenzione simile a quella usata dai backports_ aggiungendo ``~fussN-X`` al numero di versione, dove N è la versione di FUSS per la quale stiamo preparando il pacchetto e X la revisione del backport. .. _backports: https://backports.debian.org/ Se si fa una rebuild di un pacchetto che ad esempio ha versione 1.2.3-4 la nostra versione sarà 1.2.3-4~fuss9+1 (+2 per una rebuild successiva con modifiche alla sola pacchettizzazione, eccetera). Configurazione del repository ============================= Il file ``/iso/repo/conf/distributions`` definisce le distribuzioni utilizzate nel repository, con snippet di configurazione come:: Origin: FUSS Label: FUSS Suite: jessie Codename: jessie Version: 8.0 Architectures: i386 amd64 source Components: main contrib Description: FUSS 8.0 SignWith: C00D47EF47AA6DE72DFE1033229CF7A871C7C823 inoltre nello stesso file sono definite le versioni precedenti e future della distribuzione. Al momento attuale la configurazione riguarda fino alla versione 10 di Debian (codename ``buster``). Le varie distribuzioni sono raggiungibili da apt usando, in ``/etc/apt/sources.list``:: deb http://archive.fuss.bz.it CODENAME_DISTRIBUZIONE main contrib e la chiave con la quale viene firmato il repository si può installare su una macchina debian o derivate eseguendo, da root:: # wget -qO - https://archive.fuss.bz.it/apt.key | apt-key add - Aggiunta di nuova distribuzione e/o nuovo repository ---------------------------------------------------- Oltre al file ``/iso/repo/conf/distributions`` per indicare la nuova distribuzione e/o nuovo repository, è necessario: * Creare una cartella per lo spool di incoming dei pacchetti in ``/iso/incoming/`` * Aggiungere la descrizione e il path relativo al punto precedente nel file ``/iso/repo/conf/incoming`` * Aggiungere allo script ``/iso/bin/post-upload`` l'esecuzione del processing del nuovo path di incoming. In questo script vanno tolte quelle non più usate quando è certo che non ci saranno più nuovi pacchetti per una specifica distribuzione.