Capítol 2. Primers passos.

# Capítol 2. Primers passos.

The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Maintainers. Please use this new tutorial as the primary tutorial document.

Començarem la construcció del teu paquet (o encara millor, pots adoptar un paquet ja existent).

## 2.1. Pla de treball de la construcció de paquets Debian

Si estàs treballant en la construcció d'un paquet Debian a partir de les fonts d'un programa, el pla de treball típic requereix la construcció d'arxius amb noms específics a cada una de les etapes de la següent manera:

- Obtindre una còpia del codi font del programa, normalment en un arxiu comprimit en format «tar».

  - ``nom_del_paquet`-`versió`.tar.gz`

- Afegir les modificacions específiques de la construcció del paquet Debian a les fonts del programa en el directori `debian`, i generar un paquet font no nadiu (o sigui, el conjunt d'arxius d'entrada que es fan servir en la compilació del paquet Debian).

  - ``nom_del_paquet`_`versió`.orig.tar.gz`
  - ``nom_del_paquet`_`versió`-`revisió`.debian.tar.gz` [4]
  - ``nom_del_paquet`_`versió`-`revisió`.dsc`

- Construir paquets binaris Debian, habitualment paquets ordinaris per a la instal·lació en format `.deb` (o en format `.udeb`, fet servir per l'instal·lador de Debian) a partir del paquet font Debian.

  - ``nom_del_paquet`_`versió`-`revisió`_`arquitectura`.deb`

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.

## 2.2. Seleccionar el programa.

Probablement ja tens clar quin paquet vols construir. Primer cal que comprovis si ja està inclòs en el repositori fent servir:

- l'ordre aptitude.

- la pàgina web paquets Debian.

- pàgina web Debian Package Tracker (Sistema de seguiment de paquets de Debian)

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:

- L'ordre wnpp-alert del paquet `devscripts`

- Work-Needing and Prospective Packages (Paquets en què es treballa i futurs paquets)

- Registre Debian d'Informes d'errors: errors en el pseudo-paquet `wnpp` a `unstable`

- Paquets Debian que necessiten atenció

- Navegació en els errors del paquet `wnpp` basada en paraules clau

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:

- Fer-te càrrec de paquets orfes d'ús freqüent

- unir-te als equips de desenvolupadors.

- Selecciona errors dels paquets més populars.

- Selecciona paquets QA o NMU.

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ó:

- Aprèn el funcionament del programa i fes-ho servir una temporada (per comprovar la seva utilitat).

- You must check that no one else is already working on the package on the Work-Needing and Prospective Packages site. If no one else is working on it, file an ITP (Intent To Package) bug report to the `wnpp` pseudo-package using reportbug. If someone's already on it, contact them if you feel you need to. If not — find another interesting program that nobody is maintaining.

- Cal que el programa tengui una llicència:

  - Per a paquets de la secció `main` cal que el programa s'ajusti a les Directrius de Debian per al programari (DFSG) lliure (consulta DFSG) i no ha de precisar la instal·lació de cap altre paquet que no pertanyi a la secció `main` en la compilació o execució com requereix la directiva de Debian («Debian Policy»).

  - Per a paquets de la secció `contrib`, la llicència cal que compleixi tots els requisits de la DFSG però pot precisar la instal·lació d'altres paquets que no siguin de la secció `main` en la compilació o execució.

  - Per a paquets de la secció `non-free`, no és necessari que la llicència compleixi tots els requisits de la DFSG però cal que permeti la distribució del programa.

  - Si tens dubtes a l'hora d'assignar el paquet a una secció, envia un correu amb el text de la llicència (en anglès) adreçat a debian-legal@lists.debian.org.

- The program should not introduce security and maintenance concerns into the Debian system.

  - The program should be well documented and its code needs to be understandable (i.e., not obfuscated).

  - Cal que contactis amb l'autor o autors del programa per comprovar que accepten la construcció del paquet. És important que els autors continuïn amb el manteniment del programa de manera que puguis fer consultes sobre problemes específics del programa. No comencis a empaquetar un programa que no sigui mantingut pels autors.

  - El programa no s'ha d'executar com a «setuid root»: cal que no sigui «setuid» ni «setgid».

  - Cal que el programa no sigui un dimoni, o que s'instal·li en els directoris `*/sbin` o obrir un port com a usuari administrador.

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.

- Paquets simples

  - un únic paquet binari, arquitectura = totes (col·lecció de dades com per exemple gràfics de fons de pantalla)

  - un únic paquet binari, arquitectura = totes (executables escrits en un llenguatge interpretat com per exemple POSIX)

- Paquets de complexitat intermèdia

  - un únic paquet binari, arquitectura = totes (executables binaris ELF escrits en un llenguatge compilat com és ara C i C++)

  - paquet múltiple binari, arquitectura = qualsevol i totes (paquets amb executables binaris ELF i documentació)

  - el format de l'arxiu font no és ni `tar.gz` ni `tar.bz2`

  - paquets amb parts de les fonts que no es poden distribuir.

- Paquets molt complexes

  - paquets amb mòduls d'intèrprets fets servir per altres paquets

  - paquets de biblioteques genèriques ELF que fan servir altres paquets

  - paquets amb múltiples binaris incloent paquets de biblioteques ELF

  - paquets de fonts amb fonts originals diverses

  - paquets amb mòduls del nucli

  - paquets amb pegats del nucli.

  - qualsevol paquet amb guions del desenvolupador no trivials

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:

- Perl policy

- Normes per a Python

- Normes per a Java

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

## 2.3. Aconsegueix el programa i prova'l.

La primera passa és trobar i descarregar el codi font original del programa. Les fonts dels programes lliures de GNU/Linux és habitual que es distribueixin en fitxers amb format tar+gzip amb extensió `.tar.gz` o amb format tar+bzip2 amb extensió `.tar.bz2`, i generalment tenen un directori amb el nom ``programa`-`versió`` amb tots els fitxers del codi font.

If the latest version of the source is available through a Version Control System (VCS) such as Git, Subversion, or CVS, you need to get it with `git clone`, `svn co`, or `cvs co` and repack it into tar+gzip format yourself by using the `--exclude-vcs` option.

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.

## 2.4. Sistemes de compilació simples

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`.

## 2.5. Sistemes de compilació populars

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.

## 2.6. Nom del paquet i versió.

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:

- Les cadenes es comparen des del cap fins la cua.

- Les lletres són anteriors als dígits.

- Els nombres es comparen com enters.

- Les lletres es comparen per l'ordre del seu codi ASCII.

- Hi ha normes especials per al punt (`.`), signe més (`+`) i `~` com es mostra a continuació:

  `0.0` < `0.5` < `0.10` < `0.99` < `1` < `1.0~rc1` < `1.0` < `1.0+b1` < `1.0+nmu1` < `1.1` < `2.0`

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`.

## 2.7. Configuració de quilt.

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

## 2.8. Paquet Debian no nadiu inicial.

Els paquets normals Debian són paquets de Debian no nadius construïts a partir dels programes originals. Si vols construir un paquet no nadiu Debian del codi font `gentoo-0.9.12.tar.gz`, pots construir el paquet no nadiu inicial Debian fent servir l'ordre dh_make de la següent manera:

    $ 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`:

- El nom del paquet i de la versió estan separats per «`_`».

- S'ha afegit `.orig` abans de l'extensió `.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`.»).

[4] Per a paquets no nadius Debian construïts amb l'antic format `1.0`, es fa servir ``nom_del_paquet`_`versió`-`revisió`.diff.gz`

[5] Consulta 5.6.1 "Source", 5.6.7 "Package", i 5.6.12 "Version". El codi de l'arquitectura del paquet segueix el Debian Policy Manual, 5.6.8 "Architecture" i s'assigna automàticament en el procés de construcció del paquet.

[6] See Debian Developer's Reference 5.9.5 "Adopting a package".

[7] Tot i així, hi ha nous programes que són d'interès per a Debian.

[8] No et preocupis per l'arxiu `Makefile` perdut. Pots instal·lar l'ordre hello fent servir l'ordre debhelper com s'ha explicat a Secció 5.11, «Fitxer `install`.» o modificant les fonts originals afegint un nou `Makefile` amb l'objectiu `install` com a Capítol 3, Modificar les fonts originals..

[9] Pots identificar el format de l'arxius fent servir l'ordre file.

[10] Aquest programa ja està empaquetat. La versió actual fa servir «Autotools» en la seva construcció i ha canviat molt respecte a la versió 0.9.12 feta servir en els exemples.

[11] Many modern programs come with a script named `configure`, which when executed creates a `Makefile` customized for your system.

[12] Autotools is too big to deal with in this small tutorial. This section is meant to provide keywords and references only. Please make sure to read the Autotools Tutorial and the local copy of `/usr/share/doc/autotools-dev/README.Debian.gz`, if you need to use it.

[13] Pots automatitzar el procés utilitzant `dh-autoreconf`. Consulta Secció 4.4.3, «Personalització del fitxer `rules`.».

[14] La longitud predeterminada pel nom del paquet de l'ordre aptitude és 30. Per a més del 90% dels paquets, el nom del paquet té menys de 24 caràcters.

[15] If you follow the Debian Developer's Reference 5.1. "New packages", the ITP process will usually catch this kind of issue.

[16] Aquesta norma més estricta hauria d'ajudar a evitar noms d'arxius confusos.

[17] La longitud predeterminada pel codi de versió de l'ordre aptitude és 10. El codi de revisió Debian precedit per un guió en consumeix 2. Per a més del 80% dels paquets, la versió del codi font té una longitud inferior a 8 caràcters i el codi de la revisió Debian menys de 2. Per a més del 90% dels paquets, la versió del codi font té menys de 10 caràcters i la revisió Debian menys de 3.

[18] Les cadenes de versió poden ésser la versió del codi font (``versió``), la revisió Debian (``revisió``), o versió (``versió`-`revisió``). Consulta Secció 8.1, «Nova revisió Debian del paquet.» per saber com cal incrementar la revisió Debian.

[19] El text mostrat a continuació dona per suposat que fas servir «Bash» com a intèrpret d'ordres. Si fas sevir altres intèrprets, com és ara «Z shell», hauràs de fer servir els seus arxius de configuració en lloc de `~/.bashrc`.

[20] If the upstream source provides the `debian` directory and its contents, run the dh_make command with the extra option `--addmissing`. The new source `3.0 (quilt)` format is robust enough not to break even for these packages. You may need to update the contents provided by the upstream version for your Debian package.

[21] Les opcions sobre el tipus de paquet són les següents: `s` per a un binari, `i` per a un paquet independent de l'arquitectura (paquet de codi font o de documentació), `m` per a paquets amb més d'un arxiu binari, `l` per a biblioteques, `k` per a un mòdul del nucli («kernel»), `n` per a un pegat del nucli i `b` per a paquets `cdbs`. Aquest document es centra amb l'ús del paquet `debhelper` i l'ordre dh per a la construcció de paquets amb un binari i tracta només parcialment el seu ús en la construcció de paquets independents de l'arquitectura i amb més d'un arxiu binari. El paquet `cdbs` proporciona guions alternatius a l'ordre dh i no s'explica en aquest document.

Capítol 1. Començant correctament. |  | Capítol 3. Modificar les fonts originals.