Translation(s): English - Español - Italiano - Português Brasileiro

Contents

  1. Building Tutorial
  2. Requisiti
  3. Primo passo: usare deb-src
  4. Scegliere il pacchetto
  5. Ottenere il pacchetto sorgente
  6. Ottenere le dipendenze di compilazione
  7. Ricompilare senza modifiche
  8. Modificare il codice sorgente
  9. Compilare il pacchetto modificato
  10. Installing and testing the modified package
  11. Building the source package
  12. Sending your changes to the BTS
  13. That's it, get ready for the next package
  14. Feedback
  15. Questions and Answers
  16. See also

Building Tutorial

Questo tutorial è basato su un Evento "Build it" di Debian Women tenuto da Margarita Manterola (in collaborazione con il progetto OpenHatch) il 07-maggio-2011

Questo tutorial tratta di come prendere un pacchetto esistente, ricompilarlo applicandovi delle modifiche e preparare tali modifiche in modo da poterle inviare come patch per un bug.

Requisiti

Per questo tutorial sono richieste molto poche conoscenze pregresse, ma non si deve aver paura della riga di comando :-)

Requisiti tecnici

Ricordarsi di eseguire: 

   sudo apt-get install build-essential fakeroot devscripts

Primo passo: usare deb-src

Una volta che sono stati installati i pacchetti necessari, la cosa successiva da fare è assicurarsi di avere configurato sulla propria macchina alcuni repository per i sorgenti. Aprire il file /etc/apt/sources.list e controllare che siano presenti una o più righe che iniziano con deb-src; queste righe sono necessarie per poter lavorare con i pacchetti sorgenti.

Se non c'è alcuna riga deb-src, è necessario aggiungerne almeno una. Ciò viene solitamente fatto copiando una delle righe deb esistenti e modificandola in deb-src. Lo si può fare usando un editor con i privilegi di amministratore (sudo gedit, sudo kate o sudo vim) aggiungendo questa riga: 

deb-src http://http.us.debian.org/debian unstable main

Solitamente è una buona idea usare unstable come repository, dato che così si lavorera con la versione più recente del pacchetto, ma se si vuole modificare un pacchetto così come è presente in stable o testing si può usare allo stesso modo una di quelle distribuzioni. Se si usa stable/testing/quello-che-è come distribuzione in uso, ottenere i sorgenti da unstable non ha effetto su di essa.

Una volta aggiunta la riga, è necessario eseguire 

   sudo apt-get update

per aggiornare l'elenco dei pacchetti disponibili per l'installazione.

Scegliere il pacchetto

Una volta aggiunto l'URL per i sorgenti ai propri repository apt, si è in grado di ottenere i sorgenti di qualsiasi pacchetto Debian si desideri. In questo specifico tutorial, verranno scaricati i sorgenti di un pacchetto di esempio a cui verrà fatta una piccola modifica in modo da farlo funzionare meglio.

È sempre una buona idea avere una directory dedicata a lavorare sul software sorgente, separata dalle altre directory usate per altri scopi. In caso non ce ne sia una già presente, è suggerita la creazione di una directory src con al suo interno un'altra chiamata debian: 

mkdir -p src/debian/; cd src/debian

All'interno di questa directory verranno messi i sorgenti del pacchetto su cui si lavorerà. In questo esempio verrà usato un pacchetto chiamato fdupes, uno strumento per rilevare file duplicati, e verrà risolto il bug Debian #585426.

Si dovrebbe installare il pacchetto (o controllare se è installato e aggiornato alla versione più recente) prima di procedere, dato che sarà necessario avere tutte le dipendenze soddisfatte quando si installerà quello modificato.

Se fdupes non è installato, lo si può installare usando: 

   sudo apt-get install fdupes

Controllare che il bug sia ancora presente; lo si può fare eseguendo 

   fdupes --help

e controllando che la seconda riga delle informazioni per l'opzione --debug continui a non avere alcun senso.

Ottenere il pacchetto sorgente

Per poter ottenere i sorgenti di fdupes, ciò che si deve fare è andare nella directory che si è scelta (src/debian in questo esempio) ed eseguire (come utente normale): 

   apt-get source fdupes

Ad esecuzione terminata, saranno stati scaricati 3 file (.dsc, .tar.gz, .diff.gz), che insieme creano il pacchetto sorgente Debian. Probabilmente si è anche stati informati che fdupes è mantenuto via Git.

Una volta che il pacchetto è stato scaricato, si può controllare la directory in cui ci si è spostati, digitando ls, e si può vedere che oltre ai 3 file scaricati c'è anche una directory chiamata fdupes-1.50-PR2. Questi sono i sorgenti non pacchettizzati del pacchetto Debian. Digitare:  cd fdupes-1.50-PR2/  per entrare in quella directory.

Controllando il contenuto di questa directory (digitando nuovamente ls), si vedono parecchi file di vario tipo ed una directory debian.

Ogni pacchetto Debian (o derivato da Debian) include una directory debian in cui vengono archiviate tutte le informazioni relative al pacchetto Debian. Tutto ciò che è al di fuori di quella directory, è codice originale a monte, cioè il codice originale rilasciato di chiunque abbia programmato il software.

Spostarsi nella directory debian digitando cd debian e guardare il suo contenuto usando ls. Questa è la directory che il manutentore del pacchetto ha aggiunto al codice sorgente per creare il pacchetto; in essa di solito si trovano molti file relativi alla versione Debian del programma, patch specifiche per Debian, pagine man, documentazione e così via. In questa occasione non ci soffermiamo oltre su questi file, ma ricordarsi che il file rules è il file eseguibile che dovrà essere usato per poter compilare il pacchetto. Ci sono anche diverse patch applicate dal manutentore nella directory patches.

Spostarsi indietro di una directory, usando cd ... Si dovrebbe essere di nuovo in fdupes-1.50-PR2, la directory principale del codice sorgente.

Ottenere le dipendenze di compilazione

Per quasi ogni programma, per poterlo compilare è necessaria l'installazione di alcune dipendenze. Le dipendenze sono i programmi o le librerie necessari per compilare il programma in questione. Solitamente si tratta di svariati pacchetti che finiscono in -dev, ma possono essere comprese anche altre cose, come automake o gcc, a seconda di quanti strumenti di sviluppo sono già stati installati sulla macchina.

apt fornisce un metodo per installare facilmente tutte le dipendenze necessarie: 

   sudo apt-get build-dep fdupes

Una volta scaricati questi strumenti, si è pronti per compilare il pacchetto.

Ricompilare senza modifiche

Prima di fare una qualunque modifica al codice, compilare il pacchetto come è adesso, solo per assicurarsi che si compila e si installa in modo corretto. Eseguire: 

   fakeroot debian/rules binary

Questo è il comando, quasi come make, che compila il pacchetto. Ci vorrà probabilmente un po' di tempo perché l'esecuzione di questo comando venga completata, dato che solitamente prima deve essere eseguito ./configure, poi deve essere compilato il codice sorgente e quindi creato il pacchetto. Di fatto, esegue i comandi che sono elencati nel file debian/rules e si spera termini con un messaggio simile a: 

   dpkg-deb: building package `fdupes' in `../fdupes_1.50-PR2-3_<mia arch>.deb'

localizzato nella lingua di sistema. <mia arch> può essere i386, amd64, a seconda della architettura sulla quale gira la macchina.

Una volta che il pacchetto è stato compilato correttamente, il passo successivo è installare questo file con: 

   sudo dpkg -i ../fdupes_1.50-PR2-3_<mia arch>.deb

Dopo, controllare che il bug sia ancora presente eseguendo fdupes --help.

Modificare il codice sorgente

Ora, si deve davvero risolvere questo bug. Qui inizia il divertimento. Quando si cerca di risolvere un bug di un pacchetto, a volte questo è nei sorgenti originali e a volte è correlato al modo in cui il programma è stato pacchettizzato per Debian. Perciò a seconda di dove è il problema si devono modificare file diversi.

In questo caso particolare, il pacchetto usa lo strumento dpatch, uno strumento per gestire patch per il pacchetto, perciò verrà usato tale strumento. Altri pacchetti usano uno strumento diverso, chiamato quilt, per gestire le patch ma non verrà trattato in questo tutorial.

Per creare una nuova patch, è necessario fare quanto segue. Digitare: 

   dpatch-edit-patch 80_bts585426_fix_help 70_bts537138_disambiguate_recurse.dpatch

Questo avvierà una nuova shell all'interno di un ambiente speciale, in cui si possono modificare i file e dpatch in seguito si occuperà di ottenere le differenze con l'originale. Il primo parametro è il nome assegnato alla nuova patch, il secondo è l'ultima patch che dovrebbe essere applicata prima di quella nuova. Il nome della patch è stato scelto in modo da essere conforme al modello già stabilito dal manutentore.

Ora deve essere modificato il file fdupes.c. Ciò può essere fatto con il proprio editor preferito (vi fdupes.c, gedit fdupes.c, kate fdupes.c, ecc.). Andare alla riga 1066 e cancellarla. La riga dice:

printf("                  \teach set of duplicates without prompting the user\n");

Una volta fatto, si deve digitare exit nella console; questo termina l'ambiente speciale che dpatch aveva creato e si ottiene una nuova patch nella directory debian/patches/. Controllare con: 

   cat debian/patches/80_bts585426_fix_help.dpatch

Per poter applicare questa patch, è necessario modificare il file debian/patches/00list e aggiungere 

   80_bts585426_fix_help

come ultima riga.

Il file 00list è il file dpatch che elenca tutte le patch che verranno applicate; queste vengono applicate in ordine, da quella nella prima riga a quella nell'ultima.

Prima di ricostruire il pacchetto con questa patch, si deve rendere il proprio pacchetto diverso da quello originale, in modo che in seguito possano essere estratte le differenze così da poterle inviare come patch per il bug. Per fare questo, digitare: 

   dch -n

Questo aggiunge una nuova voce nel file changelog, forse con il nome utente (a seconda della configurazione, argomento che qui non viene trattato), con la data e ora correnti e apre il file con l'editor a riga di comando preconfigurato. Se quest'ultimo è vi e questa è la prima volta che lo si usa, si può iniziare a modificare premendo il tasto Insert e, dopo che si è terminato, si può salvare e chiudere premendo ESC :wq

Ora si sta quindi modificando il file changelog; quello che è necessario inserire in questo file è una qualche descrizione del cambiamento che è stato fatto. Per esempio: 

   Added a patch to fix the --help issue with the --debug option. Closes: #585426".

Farlo nella riga con il carattere * vuoto.

Compilare il pacchetto modificato

Una volta che ciò è stato fatto, si deve prima pulire la directory di compilazione, in modo che tutto sia come quando si è iniziato, usando: 

   fakeroot debian/rules clean

e poi si può ricompilare il pacchetto di nuovo facendo la stessa cosa fatta prima: 

   fakeroot debian/rules binary

Nel caso che sia necessario fare il debug del pacchetto compilato, specialmente se si sta cercando di risolvere un problema di Segmentation Fault, può essere utile compilarlo nel modo seguente, in modo che il codice non venga ottimizzato e non siano rimossi i simboli di debug così da rendere più facile il debug.: 

   DEB_BUILD_OPTIONS=nostrip,noopt fakeroot debian/rules binary

Si vede a schermo dell'output della compilazione; di solito non è molto interessante, a meno che non si stia cercando un bug che è correlato alla compilazione stessa del pacchetto. Normalmente l'autrice lascia che proceda mentre va a fare qualcos'altro (ad esempio prendere qualche biscotto per il caffe).

This time, the package created should be: ../fdupes_1.50-PR2-3.1_<your arch>.deb, the version changed because dch changed it for us in the changelog (-3.1 instead of -3).

Installing and testing the modified package

Install it with: 

   sudo dpkg -i ../fdupes_1.50-PR2-3.1_<your arch>.deb

and test that the help is now correct. :)

If in any case what you've done has made things worst, you can always revert to Debian's version by doing: 

  apt-get install --reinstall fdupes=<previous_version>

Building the source package

Once a bug is fixed, you might want to also build the source package. This means not only the .deb file, but the other files that we downloaded at the beginning. This is done with: 

   dpkg-buildpackage -us -uc

The extra parameters are to prevent it from signing the package, since we don't need to sign it right now.

If you've built the source package, go to the previous directory with cd .. and check the files there with ls. You'll see that you have more files there now, including 2 dsc files, one for the original package and one for the one you just made.

Sending your changes to the BTS

Once you've built any source package, you can find out the difference between your package and the original one, by using debdiff: 

   debdiff fdupes_1.50-PR2-3.dsc fdupes_1.50-PR2-3.1.dsc > my_first_debdiff.diff

In this particular case, since we used the dpatch tool, what we would send to the BTS as a patch is the dpatch file that we created, because the change that we made is enclosed there.

But if we hadn't used dpatch, we could use the output of that debdiff and send that to the BTS.

That's it, get ready for the next package

You're done with modifying the package, you can now keep fixing bugs in other Debian packages! These are the important commands you'll need to remember: 

   apt-get source the-package
   apt-get build-dep the-package
   (...)
   fakeroot debian/rules binary
   dpkg -i the-package-blabla.deb
   dpkg-buildpackage -us -uc
   debdiff package-blabla.dsc package-blabla.1.dsc > another_debdiff.diff

Feedback

I hope you enjoyed the tutorial, please send me your feedback if you feel like it, or modify this wiki if you want to add some useful information I might have left out.

Questions and Answers

QUESTION: Is the number 80_ in the name of the patch a cosmetic thing?

ANSWER: It's so that you can get them in order when you list them with ls. The order of application is the order in which they appear in the 00list file. Some maintainers choose to give them numbers, some don't. But when you are patching a package, you should try to follow whichever pattern the maintainer chose.

QUESTION: About dpatch-edit-patch params, where did you get your params? I mean the bts****

ANSWER: The first one is the name of the patch. I chose a name similar to the other ones. "bts" stands for "bug tracking system", the number is the bug number that we are closing.

QUESTION: How does dch pick the number "3.1"?

ANSWER: We used dch -n, because we are not the maintainer of the package (n stands for non-maintainer). Then it's 3.1. If you were the maintainer, you'd have done dch -i, and it would have chosen -4

QUESTION: When sending a patch to the BTS, do we send anything about the changelog?

ANSWER: Not necessarily, but you can send that too, it depends on the bug that you are fixing. Sending the debdiff output is always acceptable.

If you're sending only a small and simple patch it's normal to let the maintainer write the changelog; if it's a big NMU update then yes you should send the changelog as part of your big patch to the BTS.

QUESTION: Sending a changelong with a NMU is considered not polite?

ANSWER: What some (not all) maintainers don't like is if when someone actually uploads an NMU. Sending a patch to the BTS is always/immer/siempre/sempre well received!

QUESTION: What is the quickest/easiest way to find out which tool (if any) is used to manage patches?

ANSWER: If there's a build dependency on quilt or dpatch in debian/control. Or if there's a debian/README.source file.

QUESTION: Does this workflow work for all packages?

ANSWER: The workflow is quite general. The only thing that might change is the patch management system (dpatch/quilt/none). The rest is basically always the same.

See also