Capítol 5. Altres fitxers del directori debian.

Sumari

5.1. README.Debian (LLEGEIX-ME.debian)
5.2. Fitxer compat.
5.3. Fitxer conffiles.
5.4. Fitxers nom_del_paquet.cron.*
5.5. Fitxer dirs.
5.6. Fitxer nom_del_paquet.doc-base.
5.7. Fitxer docs.
5.8. Fitxer emacsen-*.
5.9. Fitxer nom_del_paquet.examples.
5.10. Fitxers nom_del_paquet.init nom_del_paquet.default
5.11. Fitxer install.
5.12. Fitxer nom_del_paquet.info.
5.13. Fitxer nom_del_paquet.links.
5.14. Fitxers {nom_arxiu.source/}lintian-overrides
5.15. Fitxers manpage.*.
5.15.1. Fitxers manpage.1.ex
5.15.2. Fitxer manpage.sgml.ex.
5.15.3. Fitxer manpage.xml.ex.
5.16. Fitxer nom_del_paquet.manpages
5.17. Fitxer NEWS.
5.18. Fitxers {pre,post}{inst,rm}
5.19. Fitxer nom_del_paquet.symbols.
5.20. Fitxer TODO.
5.21. Fitxer watch.
5.22. Fitxer source/format.
5.23. Fitxer source/local-options.
5.24. Fitxer source/options
5.25. Fitxers patches/*.

The dh_make command had major updates since this old document was written. So some parts of this document aren't applicable any more.

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.

The debmake command is used in place of the dh_make command in my new Guide for Debian Maintainers.

Per tal de controlar el treball de debhelper en la compilació del paquet, pots afegir fitxers de configuració en el directori debian. En aquest capítol es resumeix el que pots fer amb cada un d'ells i el seu format. Consulta «Debian Policy Manual» i «Debian Developer's Reference» per a les directrius de construcció de paquets.

The dh_make command will create some template configuration files under the debian directory. Take a look at all of them.

En aquest capítol, es farà referència als arxius ubicats en el directori debian sense afegir el prefix debian/ per a simplificar el text i sempre que no hi hagi possibilitat de confusió.

En altres casos, dh_make no pot construir plantilles de configuració per a debhelper. En aquests casos tu mateix escriuràs els fitxers amb un editor.

Si vols fer servir els fitxers generats en la construcció del paquet, fes el següent:

Els fitxers de configuració construïts per debhelper que no tenen el prefix nnom_del_paquet com és ara install s'aplicaran al primer paquet binari. Si hi ha més d'una paquet binari, les seves configuracions s'especificaran amb el prefix del paquet binari corresponent al seu nom: paquet-1.install, paquet-2.install, etc.

Qualsevol detall extra o discrepància entre el programa original i la seva versió Debian cal documentar-la en aquest arxiu.

dh_make en genera un predeterminat, que és el següent:

gentoo for Debian
-----------------
<possible notes regarding this package - if none, delete this file>
 -- Josip Rodin <[email protected]>, Wed, 11 Nov 1998 21:02:14 +0100

Atès que no tenim res per explicar, eliminarem el fitxer. Consulta dh_installdocs(1).

The compat file defines the debhelper compatibility level. Currently, you should set it to the debhelper v10 as follows:

$ echo 10 > debian/compat

You may use compat level v9 in certain circumstances for compatibility with older systems. However, using any level below v9 is not recommended and should be avoided for new packages.

Una de les coses més molestes dels programes és quan després de dedicar molt de temps i esforç a configurar un programa (com a usuari), una actualització del programa fa inútils els canvis. Debian resol aquesta situació marcant els fitxers de configuració[54] de manera que quan actualitzes un paquet, tens l'opció de mantenir la teva configuració.

Des de la versió 3 de debhelper, dh_installdeb(1) considera automàticament a tots els fitxers ubicats en el directori /etc com fitxers de configuració, de manera que si tots els fitxers de configuració del programa són en aquest directori, no es necessari que els incloguis en el fitxer «conffiles» (abreviatura d'arxiu de configuració). Per a la majoria de paquets, l'única ubicació dels arxius de configuració és /etc i en aquest cas pots eliminar aquest arxiu.

Si el teu programa fa servir fitxers de configuració però també els sobreescriu ell mateix (directament des del codi font) es millor no marcar-los com «conffiles». Si ho fas, dpkg informarà als usuaris que revisin els canvis realitzats en aquests fitxers en cada actualització.

Si el programa que empaquetes requereix que cada usuari modifiqui els fitxers de configuració del directori /etc, hi ha dues formes per a no marcar-los com fitxers «conffiles» i que no siguin manipulats per dpkg:

  • Construir un enllaç simbòlic dels fitxers ubicats en /etc que apunti als fitxers ubicats en el directori /var generats per guions del desenvolupador («maintainer scripts»).

  • Posar els fitxers generats pels guions del desenvolupador en el directori /etc.

Si vols més informació sobre els guions del desenvolupador consulta Secció 5.18, «Fitxers {pre,post}{inst,rm}».

Si el teu paquet requereix la realització de tasques periòdiques per funcionar correctament, pots fer servir aquest arxiu. Pots establir la realització de tasques cada hora, dia, setmana o mes o qualsevol altre període de temps. Els noms dels fitxers són:

  • nom_del_paquet.cron.hourly - instal·lats com /etc/cron.hourly/nom_del_paquet: s'executen cada hora.

  • nom_del_paquet.cron.daily - instal·lats com /etc/cron.daily/nom_del_paquet: s'executen cada dia, habitualment a primera hora del matí.

  • nom_del_paquet.cron.weekly - instal·lats com /etc/cron.weekly/nom_del_paquet: s'executen cada setmana, habitualment en el matí del diumenge.

  • nom_del_paquet.cron.hourly - instal·lats com /etc/cron.hourly/nom_del_paquet: s'executen cada hora.

  • nom_del_paquet.cron.d - instal·lats com /etc/cron.d/nom_del_paquet: per a qualsevol altre període de temps.

Els fitxers tenen el format de guions shell. Amb l'excepció dels fitxers nom_del_paquet.cron.d que s'ajustaran al format descrit a crontab(5).

No és necessari explicitar un arxiu cron.* per a configurar la rotació de registres, per aquest cas consulta dh_installlogrotate(1) i logrotate(8). Elimina aquest arxiu si no s'ha de fer servir amb el teu paquet.

Aquest arxiu especifica els directoris necessaris però que per alguna raó no s'han creat en el procés d'instal·lació normal (make install DESTDIR=... executat per dh_auto_install). Generalment això és degut a un problema en el fitxer Makefile.

Els fitxers llistats en el fitxer install no requereixen la creació prèvia dels directoris. Consulta Secció 5.11, «Fitxer install.

És recomanable executar en primer lloc la instal·lació i només fer ús d'aquest arxiu si es produeix algú problema. No s'ha de posar la barra inicial en els noms dels directoris llistats a l'arxiu dirs.

Si el teu paquet té documentació a més de les pàgines de manual i d'informació, pots fer servir el fitxer doc-base per a registrar-la i així l'usuari la trobarà més fàcilment amb dhelp(1), dwww(1) o doccentral(1).

La documentació inclourà fitxers HTML, PS i PDF ubicats en /usr/share/doc/nom_del_paquet/.

Aquest és el contingut del fitxer gentoo.doc-base de gentoo:

Document: gentoo
Title: Gentoo Manual
Author: Emil Brink
Abstract: This manual describes what Gentoo is, and how it can be used.
Section: File Management
Format: HTML
Index: /usr/share/doc/gentoo/html/index.html
Files: /usr/share/doc/gentoo/html/*.html

Per obtenir informació sobre el format del fitxer, consulta install-docs(8) i en el manual Debian doc-base en la còpia local /usr/share/doc/doc-base/doc-base.html/index.html proporcionat pel paquet doc-base.

Per a més detalls sobre la instal·lació de documentació addicional, consulta Secció 3.3, «La instal lació dels arxius al seu destí».

Aquest arxiu especifica els noms dels fitxers de documentació que dh_installdocs(1) instal·larà en el directori temporal.

L'opció predeterminada inclourà tots els fitxers existents en els directoris del nivell més alt del codi amb els noms BUGS, README*, TODO etc.

També n'inclouré alguns d'altres per a gentoo:

  BUGS
  CONFIG-CHANGES
  CREDITS
  ONEWS
  README
  README.gtkrc
  TODO

Si el teu paquet proporciona fitxers Emacs que es poden compilar a bytes en el moment de la instal·lació, pots fer servir aquests fitxers.

Aquests fitxers seran instal·lats en el directori temporal per dh_installemacsen(1).

Elimina'ls si no els necessites.

L'ordre dh_installexamples(1) instal·la els fitxers i directoris llistats en aquest arxiu com a fitxers d'exemple.

Si el teu paquet és un dimoni que s'executa en iniciar-se el sistema, és que no has fet cas a la meva recomanació inicial, o no? :-)

Please read dh_installinit(1) dh_installsystemd(1) to provide startup script.

The package.default file will be installed as /etc/default/package. This file sets defaults that are sourced by the init script. This package.default file is most often used to set some default flags or timeouts. If your init script has certain configurable features, you can set them in the package.default file, instead of in the init script itself.

Si el programa original inclou un arxiu pel guió «init», tu pots fer-ne ús o bé descartar-ho. Si decideixes no fer servir el guió «init» original, caldrà que en facis un de nou a debian/nom_del_paquet.init. Tot i així, si el guió «init» original té bona pinta i s'instal·la en la ubicació correcta, encara caldrà configurar el fitxer rc* d'enllaços simbòlics. Caldrà reescriure l'objectiu dh_installinit de l'arxiu rules com segueix:

override_dh_installinit:
        dh_installinit --onlyscripts

Elimina el fitxer si no el fas servir.

If there are files that need to be installed into your package but your standard make install won't do it, put the filenames and destinations into this install file. They are installed by dh_install(1).[55] You should first check that there is not a more specific tool to use. For example, documents should be in the docs file and not in this one.

En el fitxer install hi haurà una línia per a cada un dels fitxers a instal·lar, amb el seu nom (sempre relatiu al directori superior de la compilació) i després d'un espai, el directori d'instal·lació (relatiu al directori d'instal·lació). En el cas que no s'instal·li el fitxer binari src/arxiu_binari del gentoo, hauries d'escriure el següent:

src/arxiu_binari usr/bin

Quan s'instal·li el paquet, hi haurà una ordre executable /usr/bin/arxiu_binari.

En el fitxer install pots escriure el nom del fitxer sense el directori d'instal·lació sempre que la ruta relativa de directori no canvii. Aquest format es fa servir amb paquets grans que separen el resultat de la compilació en més d'un paquet binari fent servir el conjunt de fitxers nom_del_paquet-1.install, nom_del_paquet-2.install, etc.

L'ordre dh_install revisarà el directori debian/tmp per cercar els fitxers si no els troba en el directori actual (o en la ubicació establerta per a la recerca amb l'opció --sourcedir).

Si el teu paquet fa servir fitxers «info» (sistema d'ajuda), pots instal·lar-los fent servir dh_installinfo(1) que utilitzarà el llistat del fitxer package.info.

Si has de generar enllaços simbòlics addicionals en el directori de compilació del paquet com a responsable del paquet, pots fer-ho fent servir dh_link(1) fent un llistat dels directoris complets de l'origen i destí dels fitxers a un fitxer nom_del_paquet.links

If lintian reports an erroneous diagnostic for a case where Debian policy allows exceptions to some rule, you can use package.lintian-overrides or source/lintian-overrides to quieten it. Please read the Lintian User's Manual (https://lintian.debian.org/manual/index.html) and refrain from abusing this.

El fitxer nom_del_paquet.lintian-overrides és per a un paquet binari amb el nom nom_del_paquet i s'instal·la a usr/share/lintian/overrides/nom_del_paquet per l'ordre dh_lintian.

El fitxer source/lintian-overrides és per als paquets de codi original i no s'instal·la.

Cal que el programa tengui una pàgina de manual. Si l'autor original no l'ha fet, l'hauràs de fer tu. L'ordre dh_make construeix alguns fitxers de plantilla per a les pàgines de manual. Caldrà editar-los i emplenar-los. Comprova que elimines els fitxers que no fas servir.

Las pàgines de manual s'escriuen normalment amb nroff(1). L'exemple manpage.1.ex està escrit amb nroff. Consulta la pàgina de manual man(7) on s'explica com editar el fitxer.

El nom del fitxer de manual ha d'incloure el nom del programa corresponent: així canviaràs el nom de manpage a gentoo. El nom del fitxer inclou .1 com a sufixe: aquest és el codi que indica que la pàgina de manual correspon a un programa d'usuari. Comprova que és la secció correcta. Aquí tens una petita llista de les seccions de les pàgines de manual.

En el cas del gentoo, el nom del fitxer serà gentoo.1. Com què no hi havia una pàgina de manual en els fitxers de fonts de gentoo.1, en vaig escriure una canviant el nom de la plantilla manpage.1.ex per gentoo.1 i editant-la fent servir la informació de l'exemple i la documentació del programador original.

Fes servir l'ordre help2man per generar la pàgina de manual fent servir la informació aportada per les opcions «--help» i «--version» de cada programa [56].

Si el teu paquet té pàgines de manual, les instal·laràs amb dh_installman(1) llistant els fitxers corresponents en el fitxer nom_del_paquet.manpages.

Per instal·lar el fitxer docs/gentoo.1 del paquet gentoo com el seu manual, escriu en el fitxer gentoo.manpages el següent:

docs/gentoo.1

L'ordre dh_installchangelogs(1) instal·la aquest arxiu.

Els arxius postinst, preinst, postrm, i prerm[57] s'anomenen guions del desenvolupador («maintainer scripts»), i són guions que es col·loquen en l'àrea de control del paquet i són executats pel paquet dpkg quan el teu paquet s'instal·la, s'actualitza o és eliminat.

Hauries d'evitar editar manualment els guions del desenvolupador degut a la seva complexitat. Consulta «Debian Policy Manual, 6 "Package maintainer scripts and installation procedure"» i examina els exemples contruïts per dh_make.

Si malgrat les meves advertències, adaptes els guions del desenvolupador per al teu paquet, comprova el seu funcionament en la instal·lació, actualització, desinstal·lació i eliminació completa.

Les actualitzacions a una nova versió cal que siguin «silencioses» i no intrusives (els usuaris només haurien de veure que s'han arreglat els errors i afegit noves funcions).

Quan l'actualització és necessàriament intrusiva (p. ex. fitxers de configuració dispersos en diversos directoris amb una estructura totalment modificada), s'haurien d'establir els valors predeterminats segurs (p. ex. desactivar els serveis) i facilitar la documentació apropiada establerta en les normes (fitxers README.Debian i NEWS.Debian) com a darrer recurs. Cal evitar molestar a l'usuari amb notes debconf invocades pels guions del desenvolupador en les actualitzacions.

El paquet ucf facilita el sistema conffile-like per preservar els canvis de configuració realitzats per l'usuari i per això no han de anomenar-se com conffiles els fitxers gestionats pels guions del desenvolupador. Així es minimitzen les incidències associades amb ells.

Aquests guions del desenvolupador són un exemple de les característiques de Debian que expliquen perquè la gent elegeix Debian. Has de ser acurat amb no molestar amb ells.

Packaging of a library is not easy for a novice maintainer and should be avoided. Having said it, if your package has libraries, you should have debian/package.symbols files. See Secció A.2, «Gestionant debian/nom_del_paquet.symbols».

L'ordre dh_installdocs(1) instal·la aquest arxiu.

The watch file format is documented in the uscan(1) manpage. The watch file configures the uscan program (in the devscripts package) to watch the site where you originally got the source. This is also used by the Debian Package Tracker service.

Aquest és el seu contingut:

# watch control file for uscan
version=3
http://sf.net/gentoo/gentoo-(.+)\.tar\.gz debian uupdate

Amb aquest arxiu watch, l'URL http://sf.net/gentoo es descarrega i es busca els enllaços de tipus <a href=...>. El nom base (just la part després del / final) d'aquests enllaços URL es comparen amb la funció «regexp» de Perl (consulta perlre(1)) amb el patró gentoo-(.+)\.tar\.gz. Dels fitxers trobats que s'ajusten al patró, es descarrega el de la versió més recent i el programa uupdate s'executa per actualitzar el codi original.

Although this is true for other sites, the SourceForge download service at http://sf.net is an exception. When the watch file has a URL matching the Perl regexp ^http://sf\.net/, the uscan program replaces it with http://qa.debian.org/watch/sf.php/ and then applies this rule. The URL redirector service at http://qa.debian.org/ is designed to offer a stable redirect service to the desired file for any watch pattern of the form http://sf.net/project/tar-name-(.+)\.tar\.gz. This solves issues related to periodically changing SourceForge URLs.

Si l'autor original publica la signatura criptogràfica del fitxer tarball, es recomana verificar la seva autenticitat fent servir l'opció pgpsigurlmangle descrita a uscan(1).

El fitxer debian/source/format, només conté una línia que indica el format de construcció del paquet (consulta dpkg-source(1) on hi ha la llista completa). Després de squeeze hauria de ser:

  • 3.0 (native) per a paquets nadius de Debian o

  • 3.0 (quilt) per als altres paquets.

El nou format 3.0 (quilt) registre els canvis realitzats en el paquet en fitxers de pegats quilt en el directori debian/patches. Aquests canvis s'aplique automàticament en l'extracció dels fitxers originals del paquet [58]. Les modificacions es desen en el fitxer debian.tar.gz que conté tots els fitxers del directori debian utilitzat en la construcció del paquet. El nou format permet la inclusió d'arxius com els icones PNG sense necessitat de trucs [59].

Quan dpkg-source extreu un paquet amb les fonts amb el format 3.0 (quilt), automàticament s'apliquen tots els pegats llistats en l'arxiu debian/patches/series. Això ho pots evitar amb l'opció --skip-patches.

When you want to manage Debian packaging activities under a VCS, you typically create one branch (e.g., upstream) tracking the upstream source and another branch (e.g., typically master for Git) tracking the Debian package. For the latter, you usually want to have unpatched upstream source with your debian/* files for the Debian packaging to ease merging of the new upstream source.

Un cop compilat el paquet, els pegats s'hauran aplicat a les fonts. Hauràs de desfer els pegats executant dquilt pop -a abans de sincronitzar-les amb la branca master. Pots automatitzar aquesta tasca afegint l'arxiu opcional debian/source/local-options el contingut del qual serà unapply-patches. Aquest arxiu no s'inclou en el paquet font generat i únicament canvia l'entorn local de construcció. Aquest fitxer també pot contenir la línia abort-on-upstream-changes (consulta dpkg-source(1)).

unapply-patches
abort-on-upstream-changes

Els arxius generats automàticament a l'arbre del codi font poden ser bastant molests en la construcció de paquets ja que generen arxius grans de pegats. Hi ha mòduls personalitzats, com ara dh_autoreconf per alleujar aquest problema com es descriu a Secció 4.4.3, «Personalització del fitxer rules.

Pots proporcionar una expressió regular en Perl per a l'opció --extend-diff-ignore de dpkg-source(1) per fer cas omís dels canvis realitzats en els arxius generats automàticament en crear el paquet font.

Pots emmagatzemar aquestes opcions de l'ordre dpkg-source a l'arxiu source/options de les fonts del paquet com a solució genèrica per a fer front a aquest problema dels arxius generats automàticament. A l'exemple, s'evita la creació d'arxius de pegat pels arxius config.sub, config.guess i Makefile.

extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"

L'antic format 1.0 construïa un arxiu diff.gz amb el contingut dels fitxers de construcció del paquet del directori debian i els canvis a realitzar en les fonts. Aquest format per conservar els canvis era una mica enutjós quan es tractava d'inspeccionar i entendre cada modificació de les fonts. Ja no és eficaç.

El nou format 3.0 (quilt) de les fonts, desa les modificacions (els pegats) a fer als fitxers en el directori debian/patches/* fent servir l'ordre quilt. Aquests pegats i altres dades del paquet ubicats en el directori debian es conserven en el fitxer debian.tar.gz. Des que l'ordre dpkg-source pot aplicar els pegats a les fonts amb el nou format 3.0 (quilt) sense el paquet quilt, no és necessari afegir el paquet quilt en el camp Build-Depends del fitxer control [60].

El funcionament de l'ordre quilt s'explica en quilt(1). Conserva les modificacions de les fonts en una col·lecció de fitxers de pegats -p1 en el directori debian/patches i les fonts originals romanen sense modificar fora del directori debian. L'ordre d'aplicació de les modificacions es conserva en el fitxer debian/patches/series. Pots executar («push»), desfer («pop») i actualitzar les modificacions fàcilment [61].

A Capítol 3, Modificar les fonts originals., s'han construït tres fitxers de pegats en el directori debian/patches.

Com que els pegats s'ubiquen en debian/patches, comprova que has configurat correctament l'ordre dquilt com es descriu a Secció 3.1, «Configuració de quilt.

Quan algú (inclòs tu mateix), facilita un pegat nom_pegat.patch per a les fonts, una vegada construït el paquet, la modificació del paquet amb format 3.0 (quilt) és així de simple:

$ dpkg-source -x gentoo_0.9.12.dsc
$ cd gentoo-0.9.12
$ dquilt import ../foo.patch
$ dquilt push
$ dquilt refresh
$ dquilt header -e
... descripció de la modificació

Els pegats conservats amb el nou format de fonts 3.0 (quilt) han d'estar exempts de coses innecessàries. Pots comprovar-ho executant dquilt pop -a; while dquilt push; do dquilt refresh; done.



[55] Aquesta ordre reemplaça l'ordre obsoleta dh_movefiles(1) que feia servir el fitxer files.

[56] Cal tenir present que el marcador de posició de pàgines de manual help2man reclamarà que la informació més detallada estigui disponible en el sistema d'informació. Si l'ordre no troba una pàgina info, caldrà que editis manualment la pàgina de manual construïda per help2man.

[57] Encara que faig servir les expressions bash abreujades {pre,post}{inst,rm} pels noms d'aquests arxius, has de fer servir la sintaxi pura POSIX per a aquests guions del desenvolupador per mantenir la compatibilitat el sistema «shell» dash.

[58] Consulta DebSrc3.0 on es resumeix la informació sobre els formats 3.0 (quilt) i 3.0 (native).

[59] Actualment, el nou format també permet treballar amb més d'un arxiu «tar» amb les fonts originals i altres sistemes de compressió. Aquestes funcions no s'expliquen en aquest document.

[60] Es fan servir altres mètodes d'aplicació de pegats a Debian. El sistema quilt és el recomanat. Altres sistemes són dpatch, dbs, cdbs, etc. La majoria d'ells conserven els pegats en fitxers en el directori debian/patches/*.

[61] Si has demanat a un patrocinador que afegeixi el paquet al repositori Debian, aquest sistema de separació i documentació dels canvia és molt important per facilitar la revisió del paquet per part del patrocinador.