# (c) 2003 Software in the Public Interest # Esta traducción ha sido realizada por Rubén Porras Campo # y revisada por Javier Fernández-Sanguino , # Santiago Vila y Esteban Manchado # Está basada en la página de manual original: # versión 1.7 del CVS de # /cvs/debian-doc/manpages/english/debhelper/debhelper.pod =head1 NOMBRE debhelper - El conjunto de herramientas debhelper =head1 SINOPSIS BI<*> [B<-v>] [B<-a>] [B<-i>] [B<-s>] [B<--no-act>] [B<-ppaquete>] [B<-Npaquete] [-Ptmpdir>] =head1 DESCRIPCIÓN Debhelper ayuda a construir un paquete de Debian. La filosofía que se esconde detrás de Debhelper es una colección de herramientas pequeñas, simples y fáciles de entender que son usadas en debian/rules para automatizar varios aspectos comunes a la hora de construir un paquete. Esto hace que usted, el empaquetador, tenga menos trabajo. Además si cambia la política de Debian, los paquetes que necesiten cambios sólo necesitan ser reconstruidos para que se ajusten a la nueva política. Un fichero debian/rules típico que use debhelper hará varias llamadas en cadena a órdenes de debhelper . Las órdenes de debhelper tienen todas el prefijo "dh_". Ejemplos de ficheros rules que usan debhelper se pueden encontrar en F Para crear un nuevo paquete de Debian usando debhelper, simplemente puede copiar uno de los ficheros rules de ejemplo y editarlo a mano, o usar el paquete dh-make que contiene la orden L que automatiza parcialmente el proceso. Para una introducción más apropiada el paquete maint-guide contiene un tutorial acerca de como hacer tu primer paquete usando debhelper. (existe una versión traducida al castellano en el paquete maint-guide-es) =head1 ÓRDENES DE DEBHELPER A continuación se muestra la lista completa de las órdenes de debhelper, para más información consulte sus respectivas páginas del manual. =over 4 #LIST# =back Si el nombre de un programa empieza con "dh_", y no está en la lista anterior, no es parte del paquete debhelper, pero aún así debería funcionar como los programas descritos en está página. =head1 FICHEROS DE CONFIGURACIÓN DE DEBHELPER Muchas de las órdenes de debhelper hacen uso de los ficheros en F para controlar lo que hacen. Además de los ficheros comunes F y F, que están en todos los paquetes, no sólo aquellos que usan debhelper, se pueden usar ficheros adicionales para configurar el comportamiento de una orden específica de debhelper. Estos ficheros se suelen llamar debian/paquete.tal (donde "paquete", es reemplazado por el paquete sobre el que se está trabajando). Por ejemplo, dh_installdocs usa el archivo llamado debian/paquete.docs para listar los ficheros de documentación que instalará. Lea las páginas del manual de cada orden para conocer más detalles acerca de los nombres y formatos de los ficheros que usan. Generalmente, estos ficheros listan los ficheros sobre los que se actúa, uno por línea. Algunos programas de debhelper usan un par de ficheros y destinos o algún formato un poco más complicado. Dese cuenta que si un paquete es el primero (o el único) paquete binario listado en debian/control, debhelper usará debian/tal si no existe debian/paquete.tal. En algunos casos raros, puede querer tener diferentes versiones de los archivos para diferentes arquitecturas. Si los ficheros debian/paquete.tal.arch existen, donde "arch" es igual a la salida de "dpkg --print-architecture", entonces se usarán preferentemente a otros ficheros generales. En muchos casos, estos ficheros de configuración se usan para especificar varios tipos de ficheros. Documentación o ficheros de ejemplo a instalar, ficheros a mover, y demás. Cuando sea apropiado, en casos como estos, puedes usar comodines del shell como ('?' y '*') en estos ficheros. =head1 OPCIONES COMPARTIDAS DE DEBHELPER La siguiente línea de órdenes es aceptada por todos los programas de debhelper. =over 4 =item B<-v>, B<--verbose> Modo explicativo: muestra todos las órdenes que modifican el directorio de construcción del paquete. =item B<--no-act> No hacer nada realmente. Si se usa con -v, mostrará todo lo que hubiera hecho. =item B<-a>, B<--arch> Actuar en todos los paquetes dependientes de la arquitectura. =item B<-i>, B<--indep> Actuar en todos los paquetes independientes de la arquitectura. =item B<->I, B<--package=>I Actúa sobre el paquete nombrado "paquete". Esta opción puede ser especificada varias veces para hacer que debhelper opere sobre una serie de paquetes. =item B<-s>, B<--same-arch> Esta es una opción refinada de la opción -a, que se usa en raras circunstancias. Si el fichero de control tiene una línea para el paquete como "Architecture: i386", entonces debhelper no actuará sobre el paquete en otras arquitecturas. Así pues, esta opción hace que la orden actúe en todos los paquetes "Architecture: any" así como en cualquier paquete que tenga la arquitectura actual definida explícitamente. Esto es distinto a la opción -a, que hace que la orden actúe en todos los paquetes que son dependientes de la arquitectura. =item B<-N>I, B<--no-package=>I No actuar sobre un paquete especificado incluso si las opciones -a, -i, o -p listan este paquete como uno sobre los que se debe actuar. =item B<-P>I, B<--tmpdir=>I Usa "tmpdir" como directorio para construir el paquete. Por defecto es debian/. =item B<--mainpackage=>I Esta opción poco usada cambia el paquete que debhelper considera el "paquete principal", esto es, el primero listado en debian/control, y sobre el cual se pueden usar los ficheros debian/tal en vez de los usuales debian/package.tal. =back =head1 OPCIONES COMUNES DE DEBHELPER Las siguientes opciones son válidas para algunos programas de debhelper. Mire la página del manual de cada programa para una explicación detallada de lo que hace cada una. =over 4 =item B<-n> No modificar los scripts postinst/postrm/etc. =item B<-X>I, B<--exclude=>I No procesar un elemento. Esta opción puede ser usada varias veces, para excluir distintos elementos. =item B<-A>, B<-all> Hace que los archivos o elementos especificados en la línea de órdenes tengan efecto en TODOS los paquetes sobre los que actúa, no sólo el primero. =back =head1 NOTAS =head2 Soporte para varios paquetes binarios Si su paquete fuente genera más de un paquete binario, por defecto los programas de debhelper actuarán sobre todos los paquetes binarios. Si se diera el caso de que su paquete fuente genera un paquete dependiente de la arquitectura, y otro independiente, este no es un comportamiento correcto, porque necesitará generar los paquetes dependientes de la arquitectura en el objetivo binary-arch de debian/rules, y los paquetes independientes de la arquitectura en el objetivo binary-indep de debian/rules. Para facilitar esto, así como para dar mayor control sobre qué paquetes actúan los programas de debhelper, todos estos aceptan los parámetros <-a>, B<-i>, B<-p>, y B<-s>. Estos parámetros son acumulativos. Si no se especifica ninguno los programas de debhelper actúan por defecto en todos los paquetes listados en el fichero de control. Consulte F para ver un ejemplo de como usar esto en un paquete que genera múltiples paquetes binarios. =head2 Generación automática de los scripts de instalación de debian Algunas órdenes de debhelper generarán automáticamente parte de los scripts de instalación de Debian. Si quiere que estas órdenes generen automáticamente lo que esté incluido en sus scripts de instalación de debian, entonces necesita añadir "#DEBHELPER#" a tus scripts, en el lugar donde el código deba de ser añadido. "#DEBHELPER#" será remplazado por cualquier código auto-generado cuando ejecutes dh_installdeb. Todos los scripts que generan código automáticamente de esta manera se pueden deshabilitar con el parámetro -n (ver arriba). Fijese que el código insertado sera código de shell, por eso no puede usarlo directamente es un script perl. Si desea introducirlo en un script perl, hagalo de la siguiente forma (Dese cuenta que en este caso, se asegura que $1, $2, etc están establecidas con la orden set): my $temp="set -e\nset -- @ARGV\n" . << 'EOF'; #DEBHELPER# EOF system ($temp) / 256 == 0 or die "Problema con los scripts de debhelper: $!"; =head2 Generación automática de diversas dependencias. Es posible que algunas órdenes de debhelper hagan que los paquetes generados dependan de otros paquetes. Por ejemplo, si usas L, el paquete que genera dependerá de debconf. Si usas L, el paquete dependerá de una determinada versión de xutils. Llevar la cuenta de todas estas dependencias puede ser tedioso, porque dependen de como debhelper haga las cosas, por eso debhelper ofrece una manera de automatizarlo. Todas las órdenes de este tipo, además de documentar qué dependencias pueden ser necesarias en las páginas del manual, generarán automáticamente una variable de substitución llamada ${misc:Depends}. Si introduce esta variable en el archivo debian/control, será expandida a las dependencias que debhelper crea oportunas. Esto es totalmente independiente de la estándar ${shlibs:Depends} generada por L, y de la ${perl:Depends} generada por L. Puedes elegir no elegir ninguna de estas si la expansión de debhelper de estas variables no son correctas. =head2 Directorios de construcción del paquete Por defecto, todos los programas de debhelper asumen que el directorio temporal usado para ensamblar el árbol de ficheros en un paquete es debian/. Algunas veces, puede que desee usar otro directorio temporal. Esto se puede conseguir con la opción -P. Por ejemplo, "dh_installdocs -Pdebian/tmp", usará el directorio debian/tmp como directorio temporal. Dese cuenta que si usas la opción -P, los programas de debhelper sólo pueden actuar sobre un paquete a la vez. Por eso, si tiene un paquete que construye muchos paquetes binarios, tendrá que hacer uso de la opción -p para especificar el paquete binario sobre el que debhelper actuará. =head2 Niveles de compatibilidad de debhelper Cada cierto tiempo, debhelper necesita cambios que lo pueden hacer incompatible con versiones anteriores, para de este modo mantenerse con un buen diseño a medida que necesita cambios y que su autor gana más experiencia. Los niveles de compatibilidad de debhelper se crearon para impedir que estos cambios estropeen algún paquete. Según el nivel de compatibilidad que se especifique debhelper se comporta de diferentes maneras. Para especificar un nivel de compatibilidad debes de escribir un número en debian/compat. Por ejemplo, para activar el modo V4: % echo 4 > debian/compat Los niveles de compatibilidad disponibles son: =over 4 =item V1 Este es el nivel de compatibilidad original de debhelper, y por tanto es el nivel por defecto. En este modo, debhelper usa debian/tmp como el árbol de directorios y debian/paquete para el resto de paquetes listados en el fichero de control. Se desaconseja su uso. =item V2 En este modo, debhelper usará consistentemente debian/ como el árbol de directorios para cada paquete que se construya. =item V3 Este modo funciona como el V2 con los siguientes añadidos: =over 8 =item - Los ficheros de configuración de Debhelper soportan comodines mediante * y ? cuando sea apropiado. Para usar * y ? simplemente como caracteres poner como prefijo una barra invertida. =item - dh_makeshlibs hace que los scripts postinst y postrm ejecuten ldconfig. =item - dh_installdeb marca automáticamente todos los ficheros en etc/ como conffiles. =back =item V4 Este es el modo de operación aconsejado. Hace lo mismo que V3 y además: =over 8 =item - dh_makeshlibs -V no incluirá la parte de Debian en el numero de versión generado en la línea de dependencias del fichero shlibs. =item - Se aconseja que use el nuevo ${misc:Depends} en debian/control para reemplazar el campo ${shlibs:Depends}. =item - dh_fixperms hará ejecutables todos los archivos en los directorios bin/ y etc/init.d. =item - dh_link corregirá los enlaces existentes para ajustarse a la política de debian. =back =back =head2 Enlaces a los directorios Doc A veces es útil hacer que un paquete no tenga un directorio /usr/share/doc/paquete, en vez de esto se hará un enlace colgando en el paquete binario que apunte a otro directorio de documentación. La política de Debian permite esto mientras mientras el paquete dependa del paquete al que pertenece el directorio de documentación que está usando. Para conseguir esto, lo único que hay que hacer es no decirle a debhelper que cree ningún directorio con documentación y usar dh_link para crear el enlace (o crear el enlace a mano), y debhelper hará lo correcto: se dará cuenta de que es un enlace colgante y no tratará de instalar un fichero de copyright o changelog. =head2 udebs Debhelper incluye soporte para udebs. Para crear un udeb con debhelper, añada "XC-Package-Type: udeb" al párrafo del paquete binario en debian/control, y una dependencia de construcción en debhelper (>= 4.2). Debhelper tratará de crear udebs que cumplan con las normas del "debian-installer", haciendo que los ficheros de los paquetes terminen en ".udeb", no instalando ninguna documentación en un udeb, pasando de los scripts de preinst, postrm, prerm, y de configuración, etc. =head2 Otras notas En general si algún programa de debhelper necesita que exista un directorio bajo debian/, lo creará. No me he preocupado por documentarlo en todas las páginas del manual, pero por ejemplo, dh_installdeb sabe hacer debian//DEBIAN/ antes de tratar de poner los ficheros allí, dh_installmenu sabe que necesita debian//usr/lib/menu/ antes de instalar los archivos del menú, etc. Una vez que su paquete usa debhelper para construirse, asegurese de añadir debhelper a sus dependencias de construcción en debian/control. Debería usar como build-depend una versión de debhelper igual a (o mayor) el nivel de compatibilidad de debhelper que use su paquete. Por ejemplo, si su paquete usa el nivel de compatibilidad 4: Build-Depends: debhelper (>= 4) =head1 ENTORNO =over 4 =item DH_VERBOSE Poner a uno para activar el modo explicativo. Debhelper mostrará todas las órdenes usadas que modifiquen ficheros en el sistema en el que se hace la construcción. =item DH_COMPAT Especifica temporalmente bajo que nivel de compatibilidad debe de actuar debhelper, ignorando cualquier valor en debian/compat. =item DH_NO_ACT Poner a 1 para habilitar el modo no-act. =item DH_OPTIONS Todo lo que halla en esta variable se antepondrá a los argumentos en la línea de órdenes de todas las órdenes de debhelper. Esto es útil en algunas situaciones, por ejemplo, si necesita pasar la opción -p a todas las órdenes de debhelper que va a utilizar. Una buena manera de dar valor a DH_OPTIONS es usando "Target-specific Variable Values" en su fichero debian/rules. Lea la documentación de make para los detalles sobre como hacer esto. =item DH_ALWAYS_EXCLUDE Si está establecida, añade su valor a la opción -X de todas las órdenes que soporten dicha opción. Es más, dh_builddeb hará un rm -rf a todo lo que coincida con el valor en el árbol de construcción. Esto puede ser útil si está compilando desde un árbol de CVS, en cuyo caso estableciendo DH_ALWAYS_EXCLUDE=CVS evitará que los directorios CVS se introduzcan en el paquete construido. O, si su paquete original (imprudentemente) incluye directorios CVS, puede ser útil exportar ALWAYS_EXCLUDE=CVS en debian/rules, para que esto tenga efecto en cualquier sitio donde se construya el paquete. Si se tienen varias cosas para excluir, éstas pueden separarse mediante dos puntos, p. ej.: DH_ALWAYS_EXCLUDE=CVS:.svn =back =head1 VÉASE ADEMÁS =over 4 =item F Varios ficheros de ejemplo debian/rules que usan debhelper. =item L Web de Debhelper. =back =head1 AUTOR Joey Hess =cut