IMPORTANT: Per accedir als fitxer de subversion: http://acacha.org/svn (sense password). Poc a poc s'aniran migrant els enllaços. Encara però funciona el subversion de la farga però no se sap fins quan... (usuari: prova i la paraula de pas 123456)

Conceptes

La terminologia (en anglès Jargon) utilitzada amb el paquets Debian i concretament, amb els paquets Debian font, pot ser confusa i cal tenir-la clara. Alguns dels conceptes a conèixer són:

  • upstream source: fa referència al codi font del autor del programa, el codi font original a partir del qual s'ha creat un paquet. Aquest codi sempre és més recent que el codi que es pot trobar al repositori public de paquets Debian. [1]
  • El conveni dels fitxers comprimits (The compression convention): sembla ser que hi ha un conveni pel qual normalment només s'indiquen dos fitxers a la llista de fitxers del fitxers dsc: un fitxer XXX.orig.tar.gz i un XXX.diff.gz. És a dir que en comptes d'especificar tots els fitxers del paquet font un a un s'utilitza el fitxer comprimit (sovint gz tot i que amb 3.0 quilt ja es permeten altres formats de compressió) i empaquetat (tar) XXX.orig.tar.gz. Cal indicar que és tracta d'un conveni i no pas d'una obligació.

Introducció

El primer que cal comentar sobre els paquets font (aka) S-package) és que anomenar a aquests paquets "fitxer" pot ser origen d'equívocs ja que realment es tracta d'un conjunt de fitxers i no pas un sol fitxer com succeïx amb els paquets binaris.

IMPORTANT: Els paquets font no són els paquets binaris acabats en .deb! El que si es possible és crear aquest últims a partir del paquets font. De fet en certa manera el que estem dient és que els paquets són un aplicació més la qual té el seu codi font i el seu codi binari i per tant podem crear un paquet binari compilant el paquet codi font. Vegeu l'exemple Recompilar el paquet Debian d'Squid

Els fitxers que formen un paquet font són:

  • Fitxer .dsc: Normalment amb el format <packagename>_<version>.dsc. DSC són les inicials de Debian Source Control. El fitxer DSC és un fitxer de text que indica quins són els altres fitxers que formen part del paquet font utilitzant la paraula clau "Files:"

IMPORTANT: Sovint s'anomena al fitxers DSC directament com a paquets font Debian ja que a partir d'ells es pot obtenir realment el paquet font sencer amb tots els fitxers que el componen

  • Resta de fitxers
  • Cal tenir en compte que la resta de fitxers es poden indicar de múltiples formes tot i que el conveni més utilitzat és el The compression convention i per tant normalment trobareu dos fitxers:
  • <nompaquet>_<versio>.orig.tar.gz : Conté el codi font original de l'aplicació
  • <nompaquet>_<versio>.diff.gz: Conté els canvis que cal aplicar al codi font original per a poder Debianitzar el paquet. Aquí es on realment es fan aportacions i canvis sobre el paquet original. Entre els fitxers obligatoris al resultat d'aplicar aquest pegat tenim:
  • Carpeta (./debian): Tot paquet font Debian ha de tenir aquesta carpeta. La informació continguda aquí és sovint anomenada informació de control i és aquí on hi ha la feina a fer i on s'han de crear fitxers per tal de debianitzar un paquet. Per a més detalls consulteu l'apartat carpeta debian

Formats

Fins al 2008 i des de els inicis del projecte Debian només hi ha hagut un format per a la creació de paquets de codi font a Debian utilitzant l'ordre dpkg-source, el format és conegut com a 1.0. A partir del 2008 es desenvolupa el nou format 3.0 anomenat quilt (al fitxer que indica el format (debian/source/format) s'escriu 3.0 quilt). Com el seu nom indica el nou format està basat en l'eina quilt.

És durant l'aparició de Debian Squeeze i sobretot durant els anys 2010-11 que comencen a migrar-se molts paquets font al nou format. Podeu veure una gràfica a:

http://upsilon.cc/~zack/stuff/dpkg-v3/

IMPORTANT: És va fer un disseny de una versió 2.0 però s'ha descartat, per tant hi ha un salt de 1.0 a 3.0

Format 3.0

Característiques

TODO:

Features of “3.0 (quilt)”

This is the format that replaces the non-native variant of the 1.0 source format. The features below are specific to the new format and differentiate it from its ancestor:

  • Supports compression formats other than gzip: bzip2, lzma, xz.
  • Can use multiple upstream tarballs.
  • Can include binary files in the debian packaging.
  • Automatically replaces the “debian” directory present in the upstream tarball (no repacking required).
  • Creates a new quilt-managed patch in debian/patches/ when it finds changes to the upstream files.

Features of “3.0 (native)”

This format is very similar to the native variant of the 1.0 source format except for two things:

  • it supports compression formats other than gzip: bzip2, lzma, xz.
  • it excludes by default a bunch of files that should usually not be part of the tarball (VCS specific files, vim backup files, etc.)


Integració amb sistemes de control de versions

Notes sobre els fitxers diff i versions d'un paquet font Debian

Quan se segueix el conveni The compression convention normalment tenim dos fitxers al paquet font Debian:

  • <nompaquet>_<versio>.orig.tar.gz : Aquest paquet conté el codi font original a partir del qual es fa un paquet. Normalment la versió correspon a una versió important (anomenades en anglès major-version), per exemple la versió 2.5
  • <nompaquet>_<versio>.diff.gz: aquesta versió és una versió menor per exemple la 2.5-1

Per exemple al paquet hello:

$ ls -l 
-rw-rw-r--  1 sergi sergi   5965 2010-05-09 17:06 hello_2.5-1.diff.gz
-rw-rw-r--  1 sergi sergi   1219 2010-05-09 17:06 hello_2.5-1.dsc
-rw-rw-r--  1 sergi sergi 582535 2010-05-09 17:06 hello_2.5.orig.tar.gz

Tipus de fitxers font: natius i no natius

Hi ha dos tipus de paquets Debina/Ubuntu:

  • natius(natives): Paquet especifics d'Ubuntu/Debian, no parteixen de cap codi font "extern" si no que el codi font ja és el propi paquet.
  • no natius(non-natives): Són els paquets més comuns i són els que tenen dos fitxers (el orig.tar.gz i el diff.tar.gz)

IMPORTANT: Hi ha una nova versió de paquets font no natius: 3.0 (quilt). Aquests paquets tenen un fitxer debian.tar.gz en comptes del .diff.gz, que com l'anterior conté la carpeta debian i pegats que s'apliquen a fitxers del codi font original utilitzant el patch system quilt

Fitxers

Fitxer dsc

L'apartat més important és l'apartat Files que indica els fitxers que formen part del paquet font. S'acostuma a utilitzar força el conveni The compression convention segons el qual s'indiquen només dos fitxers:

  • <nom_paquet>_<versio>.orig.tar.gz:
  • <nom_paquet>_<subversio>diff.gz

Per exemple la secció files del paquet font Hello és:

Files: 
 cf4b73d837692b93676ccd723bf6f797 582535 hello_2.5.orig.tar.gz
 fa6c41ce60b975294781ed00d67f32fe 5965 hello_2.5-1.diff.gz

Exemple de fitxers dsc. Hello package

$ apt-get source hello
$ cat hello_2.5-1.dsc 
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Format: 1.0
Source: hello
Binary: hello
Architecture: any
Version: 2.5-1
Maintainer: Santiago Vila <sanvila@debian.org>
Homepage: http://www.gnu.org/software/hello
Standards-Version: 3.8.4
Checksums-Sha1: 
 dfaf92bfc8144141bcd5ffb4a30777cd57501bfa 582535 hello_2.5.orig.tar.gz
 a98ab19072b35295ded3560721662131933f7c05 5965 hello_2.5-1.diff.gz
Checksums-Sha256: 
 22934a7d3a62f247ce3b5a77a2c7f7dd095ad8aef305efa2d0d15e0fef31c446 582535 hello_2.5.orig.tar.gz
 c2f17c08a6a94bdab4f4316beb4687e8468de03a5162f1d694a0bab4b90e5962 5965 hello_2.5-1.diff.gz
Files: 
 cf4b73d837692b93676ccd723bf6f797 582535 hello_2.5.orig.tar.gz
 fa6c41ce60b975294781ed00d67f32fe 5965 hello_2.5-1.diff.gz

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux) 
 
iQEcBAEBCAAGBQJLeDJTAAoJEEHOfwufG4syQSAH/0S9vYKRbs71bfGNmKTmRQy6
TJM1oj3hdjJoE9HBvCBoBhRSB7l5Iz+TDVyvKTcFOnXTWrZfhnNRCoErtOxP8Z0R
MOEeLDTPf3JEvpwaRbfzngp+dRkAXTJSI+equqOvj4jjPd1lrNegWtwTF6VIlXAX
5s+onfBp29/MesxzTGAdviobMYCdazmi2XceC+t5ZEJzEsMMPO6i/v22SrvE/Jkg
LiD/U6gea3/1dovsUY6I7/VyzMhHgdcuUW4dzovr2daLwE+uRp9R90XDtKN5aWUM
oBzk8vBIsw/3EV5kjCKdMtqFGdHBjn4nTKvyoXmJ1SvEzeEd21WvLsBFpcJVKaw=
=YMqG
-----END PGP SIGNATURE-----

Firmar fitxers dsc

Sovint els fitxer md5 van signats i contenen una llista amb els checksums md5 de tots els fitxers que formen part del paquet font Debian.

La signatura es fa amb l'ordre gpg:

gpg --clearsign filename.dsc

Es necessari publicar la clau pública en un servidor de claus públiques de forma que la gent pugui trobar la vostra clau pública a partir del vostre correu electrònic (recordeu que el correu electrònic del mantenidor del paquet forma part de la informació de control del paquet)

Carpeta debian

Fitxers obligatoris

TODO: Són obligatoris realment?
changelog

Changelog files are an ancient artifice of the computer-programmers world, dating back to the year dot, ie dating back to very early times. Everyone knows what they are for: maintaining a log of the changes made to a project. Specifically, they are there to tell you the difference between version x and version y of a project. The format expected in this context is documented on the debian policy manual.

copyright

The purpose of this file is to state what licencing restrictions apply to the source eg. GPL.

rules

Consulteu Fitxer rules debian

control
  This is nearly the same as the control file for B-packages, in format and meaning. The job of dpkg-gencontrol is to copy this file from the S-package into the B-package, and/or check & append stuff to it. 

the "files" file

   This is just a list of files, one per line and each line is of the format filename section priority. A space is used as a separator, and as a result this format is only valid if your filenames do not contain spaces. A file like this is generated by dpkg-gencontrol. This file is temporary and optional local file that is just a useful artifice for the suite of utility functions that someone has written. Its most likely use is to state what files should go into a debian package-update. 

the "watch" file

   This is something to do with specifying the url of where you publish package-updates (eg if you are one of these people like me who has his own website). There is a utility called uscan that checks for new versions, and the man page for uscan is probably the only source of documentation for this topic.
   The man page does at least give an indication of what they mean by the jargon "upstream source": seems to be the source code that the program author has, which is more recent and progressed than older things in the public repository.

Altres fitxers

files

This is just a list of files, one per line and each line is of the format filename section priority. A space is used as a separator, and as a result this format is only valid if your filenames do not contain spaces. A file like this is generated by dpkg-gencontrol. This file is temporary and optional local file that is just a useful artifice for the suite of utility functions that someone has written. Its most likely use is to state what files should go into a debian package-update.

watch

This is something to do with specifying the url of where you publish package-updates (eg if you are one of these people like me who has his own website). There is a utility called uscan that checks for new versions, and the man page for uscan is probably the only source of documentation for this topic.

Notes sobre diferents convencions a l'hora de crear paquets font Debian

Com ja s'ha comentat prèviament la convenció més habitual a l'hora d'indicar els fitxers que formen part d'un paquet Debian és la The compression convention. Cal però indicar que només es tracta d'una convenció i no pas d'una obligació i per aquesta raó també us podeu trobar altres formes d'indicar la llista de fitxers com per exemple:

  • Només el fitxer .diff.gz: Es tracta de paquets font Debian que depenent d'altres paquets font Debian, però compte que aquí no hi ha cap sistema que indiqui aquesta dependència ni cap eina que la gestioni. Simplement cal saber que el paquet depèn d'un altre paquet i espavilar-se ;-). Normalment serveixen per a crear una versió menor nova a partir d'una versió prèvia del paquet.
  • Posar només la carpeta ./debian dins del fitxer diff. No es tracta doncs realment d'un fitxer diff i aleshores s'entèn que un ha d'utilitzar aquesta carpeta de control amb el codi original i també un altre cop espavilar-se!

Fitxers changes

TODO:

debian package update

I am going to introduce the terminology "debian package-update", which is a collection of files: a .changes file which lists all the other files in the package under "Files:", together with those other files. As you can see, this is pretty similar to an S-package, but it is different. There is no requirement to have a ./debian directory anywhere, nor a .dsc file. The format of the .changes file is defined by debian (but where exactly I haven't a clue!).

Like a .dsc file, the .changes file maintains a list of md5 checksums and is thus the only file that needs to be signed to preserve the security of a debian package-update (see below).

You can get dpkg-genchanges -S to make a .changes file for you, and I don't think it acts very sensibly so I recommend avoiding it. If I get some requests I shall write an alternative to it. It goes and raids the control, files and changelog files for information to put into the .changes file, assuming a default location of ./debian/control etc. It also checks for the existance of the files that are listed. the something.changes file

This is the "debian package-update control file", although according to debian, these are known as "debian upload control file"s, and I think this is a typo error. These files list other file(s) foo, and the two items (something.changes and foo) form a debian package update. I think the original idea was that foo would be new source / diff file(s) to add / replace / alter source code of an existing package (but ignoring and excluding anything in the ./debian directory). The .changes file would provide other information like a changelog entry, a new version number, what package it was relevant to etc. which would be used to alter the stuff in the ./debian directory of the package.

Creating our own S-package

To make a source package, you must have a directory containing all the files you want to put into it, say it’s called foo. Then you must add a directory foo/debian and put the necessary files in it. Then you just need to create a .dsc file mentioning all the files in foo (and obviously its subdirectories). Then the S-package is everything in foo with the dsc file.

Probably the easiest way to do this is to use dpkg-source[1], which supports a variety of scenarios and options, and if you want a full understanding of these you should view the "Building" section of the man page, and see all the -s options. It follows the convention described in the section called “ The compression convention ” and produces a .gz archive. We are going to consider two cases. Creating an independent S-package

Put all the files you want included in a directory foo1, and create the directory foo1/debian, and put the necessaries in there. I think foo1 should be of the form <packagename>-<version> but I don't think it's necessary. Then type

dpkg-source -sn -b foo1

(note do not invoke this command from within foo1 or have '.' as foo1, or you may get strange results) and this will give you something like this:


dpkg-source: info: using source format `1.0'
dpkg-source: info: building blah in blah_2.0-0.tar.gz
dpkg-source: info: building blah in blah_2.0-0.dsc

and you'll find two new files in the current directory, a .dsc and a .tar.gz. Success! Creating an S-package for a project update

This essentially is packaging the information necessary to update from an "original" to current. For this I assume that you have a tarball representing the "original" state of the project which has a suffix orig.tar.gz, and a directory foo1 containing the current state of the project files. In a terminal type

dpkg-source -sp -b foo1 foo1.orig.tar.gz

Estructura dels paquets font Debian mitjançant el paquet hello

Si consulteu un repositori de paquets Debian com per exemple el repositori d'Ubuntu:

Obtindreu el següent:

PaquetsDebianRepositoriUbuntu.png

Com podeu veure hi han diferents versions del mateix paquet, i a més dels paquets Debian binaris per a diferents arquitectures (fitxers .deb) hi han altres fitxers:

  • hello_2.2-2.dsc: Fitxer principal que control el codi font del paquet, amb informació general del codi font. Estan firmats mitjançant PGP.
  • hello_2.2-2.orig.tar.gz: Codi font original o el que sovint s'anomena upstream.
  • hello_2.2-2.diff.gz: Fitxer diff que conté els canvis que s'han d'aplicar sobre l'original per tal d'obtenir la versió Debian del programa original

Si volem obtenir aquests fitxer els podem descarregar manualment o simplement executant:

$ apt-get source hello
S'està llegint la llista de paquets... Fet 
S'està construint l'arbre de dependències       
Reading state information... Fet           
Es necessita descarregar 388kB d'arxius font.
Des:1 http://ch.archive.ubuntu.com feisty/main hello 2.2-1build1 (dsc) [524B]
Des:2 http://ch.archive.ubuntu.com feisty/main hello 2.2-1build1 (tar) [383kB]
Des:3 http://ch.archive.ubuntu.com feisty/main hello 2.2-1build1 (diff) [4841B] 
388kB descarregats en 1s (372kB/s)     
gpg: Signature made dl 05 mar 2007 02:22:21 CET using DSA key ID 0F932C9C
gpg: No s'ha pogut comprovar la signatura: no s'ha trobat la clau pública
dpkg-source: s'està extraient hello a hello-2.2
dpkg-source: s'està desempaquetant hello_2.2.orig.tar.gz
dpkg-source: s'està aplicant ./hello_2.2-1build1.diff.gz

Ens descarrega tots els fitxer que conformen el font Debian hello i un cop descarregat aplica el pegat (fitxer diff) al fitxer original. Veiem les parts, primer obtenint informació prèvia necessària de les capçaleres:

S'està llegint la llista de paquets... Fet 
S'està construint l'arbre de dependències       
Reading state information... Fet           
Es necessita descarregar 388kB d'arxius font.

Després descarrega els tres fitxers:

Des:1 http://ch.archive.ubuntu.com feisty/main hello 2.2-1build1 (dsc) [524B]
Des:2 http://ch.archive.ubuntu.com feisty/main hello 2.2-1build1 (tar) [383kB]
Des:3 http://ch.archive.ubuntu.com feisty/main hello 2.2-1build1 (diff) [4841B] 
388kB descarregats en 1s (372kB/s)  

Comprovant la signatura:

gpg: Signature made dl 05 mar 2007 02:22:21 CET using DSA key ID 0F932C9C
gpg: No s'ha pogut comprovar la signatura: no s'ha trobat la clau pública

NOTA: En aquest cas dona un error ja que no s'ha pogut aconseguir la clau pública

I finalment s'utilitza dpkg-source que com em comentat el que fa és descomprimir i desempaquetar el codi original (fitxer orig.tar.gz):

dpkg-source: s'està extraient hello a hello-2.2
dpkg-source: s'està desempaquetant hello_2.2.orig.tar.gz

I un cop descomprimit aplicar el pegat (vegeu l'ordre patch)

dpkg-source: s'està aplicant ./hello_2.2-1build1.diff.gz

NOTA: Al següent enllaç: apt-get source/Comandes podeu veure que s'està executant internament al utilitzar apt-get source

El resultat és:

$ ls -l
total 404
drwxr-xr-x 10 sergi sergi   4096 2007-06-14 08:30 hello-2.2
-rw-r--r--  1 sergi sergi   4841 2007-03-05 03:04 hello_2.2-1build1.diff.gz
 -rw-r--r--  1 sergi sergi    524 2007-03-05 03:04 hello_2.2-1build1.dsc
-rw-r--r--  1 sergi sergi 382629 2006-12-12 14:03 hello_2.2.orig.tar.gz 

A la carpeta hello-2.2 tenim tot el codi font del paquet Debian format per el codi original més la part que correspon al paquet debian. Si voleu, podeu crear (compilar) el vostre paquet binari executant:

$ cd hello-2.2
$ fakeroot
# dpkg-buildpackage 

NOTA: També ho podeu fer tot de com a apt-get source -b

Recursos:

Vegeu també

Enllaços externs