Finished notes on the use of cowbuilder

docs/pacchetti-e-repository.rst

@@ -246,16 +246,19 @@ 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 devscripts dput-ng
+   # 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/
@@ -263,8 +266,37 @@ Setup
 Build
 -----
 
-::
-   $ DIST=stretch pdebuild --buildresult ../build/ --use-pdebuild-internal --pbuilder cowbuilder -- --basepath /var/cache/pbuilder/base-stretch.cow/
+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.
 
 Policy di versionamento
 =======================