Capítol 2. Primers passos.

Observa que el caràcter que separa nom_del_paquet i versió s'ha canviat de - (guió) a l'arxiu comprimit original a _ (guió baix) en el nom del paquet Debian.

En els noms del arxius anteriors, cal substituir nom_del_paquet pel nom del paquet, versió pel codi de versió del codi font, revisió pel codi de la revisió Debian i arquitectura per l'arquitectura del paquet com es defineix en el Manual de Normes de Debian ^[5].

Cada etapa d'aquest esquema s'explica amb detall en seccions posteriors.

Si el paquet ja existeix, comença per instal·lar-ho. Si és un paquet orfe (si el responsable actual és el «Debian QA Group», el grup de qualitat de Debian), pots adoptar-lo (convertir-te en el responsable del manteniment) si està disponible. Cal que ho comprovis a «Debian Bug report logs»: errors en el paquet «wnpp» de la distribució de treball («inestable» o «sid»). També pots adoptar un paquet si hi ha un avís de «sol·licitud d'adopció» («Request for Adoption» o RFA) ^[6].

Hi ha diversos recursos de seguiment dels paquets:

Cal tenir present que Debian incorpora paquets d'un gran nombre de programes de tot tipus i que la quantitat de paquets disponibles en el repositori de Debian és major que el nombre de col·laboradors amb autorització per afegir paquets al repositori. En conseqüència, la col·laboració en el manteniment de paquets que ja estan en el repositori es valora molt positivament (i és més fàcil trobar un patrocinador) per la resta de desenvolupadors ^[7]. Per col·laborar en el manteniment de paquets ja disponibles en el repositori tens les següents opcions:

If you are able to adopt the package, get the sources (with something like apt-get source packagename) and examine them. This document unfortunately doesn't include comprehensive information about adopting packages. Thankfully you shouldn't have a hard time figuring out how the package works since someone has already done the initial setup for you. Keep reading, though; a lot of the advice below will still be applicable to your case.

Si el paquet és nou i decideixes que t'agradaria posar-lo a disposició dels usuaris de Debian, has de seguir els passos indicats a continuació:

Of course, the last one is just a safety measure, and is intended to save you from enraging users if you do something wrong in some setuid daemon… When you gain more experience in packaging, you'll be able to package such software.

Com a nou desenvolupador, s'aconsella l'adquisició d'experiència amb la construcció de paquets senzills i no s'aconsella la construcció de paquets complicats.

Construir paquets molt complexes no és molt difícil, però requereix tenir més coneixements. Hauràs de buscar una orientació específica per a cada funció complexa. Per exemple, alguns llenguatges tenen els seus propis documents de normes:

There is another old Latin saying: fabricando fit faber (practice makes perfect). It is highly recommended to practice and experiment with all the steps of Debian packaging with simple packages while reading this tutorial. A trivial upstream tarball, hello-sh-1.0.tar.gz, created as follows may offer a good starting point:^[8]

$ mkdir -p hello-sh/hello-sh-1.0; cd hello-sh/hello-sh-1.0
$ cat > hello <<EOF
#!/bin/sh
# (C) 2011 Foo Bar, GPL2+
echo "Hello!"
EOF
$ chmod 755 hello
$ cd ..
$ tar -cvzf hello-sh-1.0.tar.gz hello-sh-1.0

Si el programa està disponible en una altre format (pot ésser un arxiu acabat en .Z o .zip^[9]), ho descomprimeixes amb l'eina adequada i el tornes a empaquetar adequadament.

Si algun dels continguts del codi font del teu programa no compleix les directrius DFSG, has de descomprimir-ho per eliminar-los hi tornar a comprimir-los afegint dfsg a la cadena de la versió del codi original.

Com exemple, faré servir el programa gentoo, un gestor de fitxers de X11 fet amb GTK+ ^[10].

Fes un nou directori al teu directori d'usuari amb el nom debian o deb o el que trobis més adequat (p.e. ~/gentoo/ és molt adequat). Copia en aquest nou directori el fitxer del codi font i extreu el seu contingut executant tar xzf gentoo-0.9.12.tar.gz. Comprova que no hi ha hagut errors, fins i tot els més irrellevants, degut a què és possible que hi hagi errors en desempaquetar-ho en sistemes d'altres persones que no ignorin aquestes errades. En el terminal hauràs fet el següent:

$ mkdir ~/gentoo ; cd ~/gentoo
$ wget http://www.example.org/gentoo-0.9.12.tar.gz
$ tar xvzf gentoo-0.9.12.tar.gz
$ ls -F
gentoo-0.9.12/
gentoo-0.9.12.tar.gz

Ara tens un nou directori amb el nom gentoo-0.9.12. Accedeix en aquest directori i llegeix atentament la documentació del programa, normalment en fitxers amb el nom README*, INSTALL*, *.lsm o *.html. Hi haurà instruccions per a la compilació i instal·lació del programa (probablement la instal·lació es farà a /usr/local/bin, però veurem a Secció 3.3, «La instal lació dels arxius al seu destí» que no és la destinació correcta).

Per començar la construcció del paquet, cal fer-ho amb el directori del codi font «net», o simplement només amb els fitxers de l'arxiu comprimit del codi font.

Alguns programes tenen un arxiu Makefile i és possible compilar-los simplement executant make ^[11]. Molts d'ells permeten executar make check, per fer comprovacions. La instal·lació en el directori de destí es fa executant make install.

Una vegada s'ha compilat el programa, prova'l i comprova que tot funciona correctament i que no es genera cap errada en el sistema en l'execució i/o instal·lació.

L'execució de l'ordre make clean (o make distclean) eliminarà del directori els fitxers generats per a la compilació i que són innecessaris. Habitualment, serà possible des-instal·lar el programa amb l'ordre make uninstall.

La majoria de programes lliures estan escrits en llenguatge C i C++. Molts fan servir les «Autotools» i «CMake» per compilar en diferents arquitectures. Aquestes eines generen un arxiu Makefile i d'altres fitxers necessaris per a la compilació. Així, molts programes es compilen i instal·len amb l'execució de make; make install.

Les Autotools són el sistema de compilació GNU que comprèn Autoconf, Automake (si l'entrada no existeix a la Viquipèdia, s'ha posat l'enllaç a la versió en castellà), Libtool i gettext. Confirmaràs que el programa fa servir les «autoools» per la presència dels arxius configure.ac, Makefile.am, i Makefile.in ^[12].

La primera etapa en l'ús de les «Autotools» és l'execució de l'ordre (per l'autor del codi font) autoreconf -i -f amb la qual es generen, fent servir el fitxers font (a l'esquerra del diagrama) els fitxers (a la dreta del diagrama) que després farà servir l'ordre «configure».

configure.ac-----+-> autoreconf -+-> configure
Makefile.am -----+        |      +-> Makefile.in
src/Makefile.am -+        |      +-> src/Makefile.in
                          |      +-> config.h.in
                      automake
                      aclocal
                      aclocal.m4
                      autoheader

Per a l'edició dels fitxers configure.ac i Makefile.am cal conèixer el funcionament de autoconf i automake. Consulta info autoconf i info automake (executant les ordres en el terminal).

La segona etapa del pla de treball amb «Autotools» és l'obtenció de les fonts i l'execució de ./configure && make en el directori del codi font per compilar el programa generant el fitxer binari.

Makefile.in -----+                +-> Makefile -----+-> make -> binary
src/Makefile.in -+-> ./configure -+-> src/Makefile -+
config.h.in -----+                +-> config.h -----+
                 |
  config.status -+
  config.guess --+

Pots fer canvis en el fitxer Makefile com és el directori d'instal·lació predeterminat fent servir les opcions ./configure --prefix=/usr.

Tot i què no és necessari, l'actualització del fitxer configure i dels altres fitxers amb l'ordre autoreconf -i -f és la forma més adient per comprovar la compatibilitat del codi font ^[13].

CMake (en el moment de fer aquesta traducció, aquesta entrada no existeix a la Viquipèdia en català) és un sistema de compilació alternatiu. Els programes que fan servir aquest sistema de compilació tenen un arxiu CMakeLists.txt en el codi font.

Si el codi font te el nom gentoo-0.9.12.tar.gz, pots fer servir gentoo com a nom del paquet (de les fonts) i 0.9.12 com a codi de la versió del codi font. Aquestes denominacions es fan servir a l'arxiu debian/changelog que es descriu més endavant a Secció 4.3, «El fitxer changelog.»

Although this simple approach works most of the time, you may need to adjust package name and upstream version by renaming the upstream source to follow Debian Policy and existing convention.

You must choose the package name to consist only of lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). It must be at least two characters long, must start with an alphanumeric character, and must not be the same as existing packages. It is a good idea to keep its length within 30 characters. ^[14]

Si l'autor original fa servir termes genèrics com prova de nom, és convenient canviar el nom de forma que identifiqui el seu contingut i evitar «embrutar» l'espai de noms ^[15].

You should choose the upstream version to consist only of alphanumerics (0-9A-Za-z), plus signs (+), tildes (~), and periods (.). It must start with a digit (0-9). ^[16] It is good idea to keep its length within 8 characters if possible. ^[17]

If upstream does not use a normal versioning scheme such as 2.30.32 but uses some kind of date such as 11Apr29, a random codename string, or a VCS hash value as part of the version, make sure to remove them from the upstream version. Such information can be recorded in the debian/changelog file. If you need to invent a version string, use the YYYYMMDD format such as 20110429 as upstream version. This ensures that dpkg interprets later versions correctly as upgrades. If you need to ensure smooth transition to the normal version scheme such as 0.1 in the future, use the 0~YYMMDD format such as 0~110429 as the upstream version.

El codi de versió ^[18] serà comparat per dpkg(1) de la següent manera:

$ dpkg --compare-versions versió_1 op versió_2

La norma de comparació de versions es pot resumir com:

Un cas complicat es produeix quan s'allibera una versió del codi font gentoo-0.9.12-ReleaseCandidate-99.tar.gz com a versió prèvia de gentoo-0.9.12.tar.gz. Cal assegurar que l'actualització funcionarà correctament canviant el nom de codi font per gentoo-0.9.12~rc99.tar.gz.

Comença per configurar les variables d'entorn del shell Bash $DEBEMAIL i $DEBFULLNAME que faran servir les eines de manteniment de Debian per tal d'obtenir el teu nom i adreça electrònica com s'indica a continuació^[19].

$ cat >>~/.bashrc <<EOF
DEBEMAIL="your.email.address@example.org"
DEBFULLNAME="Firstname Lastname"
export DEBEMAIL DEBFULLNAME
EOF
$ . ~/.bashrc

$ cd ~/gentoo
$ wget http://example.org/gentoo-0.9.12.tar.gz
$ tar -xvzf gentoo-0.9.12.tar.gz
$ cd gentoo-0.9.12
$ dh_make -f ../gentoo-0.9.12.tar.gz

Caldrà canviar el nom del fitxer amb el codi font ^[20]. Consulta dh_make(8) per a una descripció més detallada.

You should see some output asking you what sort of package you want to create. Gentoo is a single binary package — it creates only one binary package, i.e., one .deb file — so we will select the first option (with the s key), check the information on the screen, and confirm by pressing ENTER. ^[21]

Desprès d'executar l'ordre dh_make, es fa una còpia del fitxer amb el codi original amb el nom gentoo_0.9.12.orig.tar.gz en el directori arrel per facilitar la construcció del paquet de fonts no nadiu de Debian amb el fitxer debian.tar.gz:

$ cd ~/gentoo ; ls -F
gentoo-0.9.12/
gentoo-0.9.12.tar.gz
gentoo_0.9.12.orig.tar.gz

Posa atenció en els dos canvis en el nom del fitxer gentoo_0.9.12.orig.tar.gz:

Fitxa't que hi ha nous fitxers (de plantilla) en el directori debian dels quals es parlarà en Capítol 4, Fitxers necessaris en el directori debian. i Capítol 5, Altres fitxers del directori debian.. El procés d'empaquetament no està totalment automatitzat. La modificació dels fitxers Debian s'explicarà a Capítol 3, Modificar les fonts originals.. A continuació es compilarà el paquet Debian en l'apartat Capítol 6, Construir el paquet., la revisió del resultat a l'apartat Capítol 7, Com comprovar el teu paquet per trobar errors. i la transferència del paquet al repositori a Capítol 9, Enviar el paquet.. S'explicarà cada etapa a continuació.

Si casualment elimines algun dels fitxers de plantilles del directori «debian», pots tornar a generar-los executant dh_make amb l'opció --addmissing des del directori de les fonts.

L'actualització d'un paquet ja construït és un procés més complex: es probable que s'hagi construït amb procediments distints als que es fan servir actualment. Es millor treballar amb paquets actualitzats per aprendre els procediments bàsics de la construcció de paquets. Per empaquetar una revisió o una nova versió del teu paquet en el futur, faràs servir un procediment distint. Tot això s'explicarà a la secció Capítol 8, Actualitzar el paquet..

Please note that the source file does not need to contain any build system discussed in Secció 2.4, «Sistemes de compilació simples» and Secció 2.5, «Sistemes de compilació populars». It could be just a collection of graphical data, etc. Installation of files may be carried out using only debhelper configuration files such as debian/install (see Secció 5.11, «Fitxer install.»).