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

.. 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-<versione>.json`` contenente::

    {
        "method": "sftp",
        "fqdn": "archive.fuss.bz.it",
        "incoming": "/iso/incoming/<versione>",
        "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 ``<versione>`` è ``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 <versione>_build
    # debootstrap <versione> <versione>_build (<mirror>)
    # chroot <versione>_build
    # apt install debhelper devscripts dpkg-dev

dove ``<versione>`` è al momento (settembre 2018) ``jessie`` per il FUSS
server e ``stretch`` per il FUSS client.

Clone del repository
--------------------

Clonare il repository del progetto desiderato::

    git clone https://work.fuss.bz.it/git/<progetto>


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.

Il programma ``dch``,  permette di automatizzare l'editing del file
``debian/changelog`` che contiene la versione del pacchetto.

* Eseguire il comando ``dch -i`` che aprirà, tramite l'editor di
  default, il changelog, dove verrà inserita automaticamente una nuova
  entry con il numero di versione aumentato di 1.
  Nel caso non si sia tra elencati tra i Maintainer e Uploaders in
  ``debian/control`` verrà impostato un numero di versione con ``+nmu``
  (Non Maintainer Upload); correggerlo per incrementare normalmente ed
  eliminare la riga relativa dall'elenco delle modifiche.

* Modificare ``UNRELEASED`` con ``unstable`` nella prima riga; questo si
  può fare anche con il comando ``dch -r``.

* Descrivere la modifica effettuata, possibilmente indicando il ticket
  di riferimento da cui nasce la richiesta di modifica

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.

Test
----

Tramite ``dpkg -i <nomefile>.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 <nomefile>.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 "<modifiche effettuate>. 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-<versione> nomepacchetto_versione_arch.changes

Nel caso si voglia procedere manualmente invece si possono copiare i
file generati su ``isolda`` nella directory ``/iso/incoming/<versione>``
ed aggiornare il repository con il comando::

    # /iso/bin/post-upload

Verificare poi che in ``/iso/incoming/<versione>`` non siano rimasti
file spuri, e nel caso cancellarli a mano.

Configurazione del repository
=============================