Capítol 2. Primers passos.

Sumari

2.1. Pla de treball de la construcció de paquets Debian
2.2. Seleccionar el programa.
2.3. Aconsegueix el programa i prova'l.
2.4. Sistemes de compilació simples
2.5. Sistemes de compilació populars
2.6. Nom del paquet i versió.
2.7. Configuració de quilt.
2.8. Paquet Debian no nadiu inicial.

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

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:

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.

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

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

  • 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 [email protected].

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

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

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.

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:

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

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="[email protected]"
DEBFULLNAME="Firstname Lastname"
export DEBEMAIL DEBFULLNAME
EOF
$ . ~/.bashrc

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.

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