man/es/debhelper.pod

   1 # (c) 2003 Software in the Public Interest
   2 # Esta traducción ha sido realizada por Rubén Porras Campo <nahoo@inicia.es>
   3 # y revisada por Javier Fernández-Sanguino <jfs@computer.org>,
   4 # Santiago Vila <sanvila@unex.es> y Esteban Manchado <zoso@demiurgo.org>
   5 # Está basada en la página de manual original:
   6 # versión 1.7 del CVS de
   7 # /cvs/debian-doc/manpages/english/debhelper/debhelper.pod
   8
   9 =head1 NOMBRE
  10
  11 debhelper - El conjunto de herramientas debhelper
  12
  13 =head1 SINOPSIS
  14
  15 B<dh_>I<*> [B<-v>] [B<-a>] [B<-i>] [B<-s>] [B<--no-act>] [B<-ppaquete>] [B<-Npaquete] [-Ptmpdir>]
  16
  17 =head1 DESCRIPCIÓN
  18
  19 Debhelper ayuda a construir un paquete de Debian. La filosofía que se esconde
  20 detrás de Debhelper es una colección de herramientas pequeñas, simples y fáciles
  21 de entender que son usadas en debian/rules para automatizar varios aspectos
  22 comunes a la hora de construir un paquete. Esto hace que usted, el empaquetador,
  23 tenga menos trabajo. Además si cambia la política de Debian, los paquetes que
  24 necesiten cambios sólo necesitan ser reconstruidos para que se ajusten a la
  25 nueva política.
  26
  27 Un fichero debian/rules típico que use debhelper hará varias llamadas en cadena
  28 a órdenes de debhelper . Las órdenes de debhelper tienen todas el prefijo
  29 "dh_". Ejemplos de ficheros rules que usan debhelper se pueden encontrar en
  30 F</usr/share/doc/debhelper/examples/>
  31
  32 Para crear un nuevo paquete de Debian usando debhelper, simplemente puede copiar
  33 uno de los ficheros rules de ejemplo y editarlo a mano, o usar el paquete
  34 dh-make que contiene la orden L<dh_make|dh_make(1)> que automatiza parcialmente
  35 el proceso. Para una introducción más apropiada el paquete maint-guide contiene
  36 un tutorial acerca de como hacer tu primer paquete usando debhelper.  (existe
  37 una versión traducida al castellano en el paquete maint-guide-es)
  38
  39 =head1 ÓRDENES DE DEBHELPER
  40
  41 A continuación se muestra la lista completa de las órdenes de debhelper,
  42 para más información consulte sus respectivas páginas del manual.
  43
  44 =over 4
  45
  46 #LIST#
  47
  48 =back
  49
  50 Si el nombre de un programa empieza con "dh_", y no está en la lista anterior,
  51 no es parte del paquete debhelper, pero aún así debería funcionar como los
  52 programas descritos en está página.
  53
  54 =head1 FICHEROS DE CONFIGURACIÓN DE DEBHELPER
  55
  56 Muchas de las órdenes de debhelper hacen uso de los ficheros en F<debian/> para
  57 controlar lo que hacen. Además de los ficheros comunes F<debian/changelog> y
  58 F<debian/control>, que están en todos los paquetes, no sólo aquellos que usan
  59 debhelper, se pueden usar ficheros adicionales para configurar el comportamiento
  60 de una orden específica de debhelper. Estos ficheros se suelen llamar
  61 debian/paquete.tal (donde "paquete", es reemplazado por el paquete sobre el que
  62 se está trabajando).
  63
  64 Por ejemplo, dh_installdocs usa el archivo llamado debian/paquete.docs para
  65 listar los ficheros de documentación que instalará. Lea las páginas del manual
  66 de cada orden para conocer más detalles acerca de los nombres y formatos de los
  67 ficheros que usan. Generalmente, estos ficheros listan los ficheros sobre los
  68 que se actúa, uno por línea. Algunos programas de debhelper usan un par de
  69 ficheros y destinos o algún formato un poco más complicado.
  70
  71 Dese cuenta que si un paquete es el primero (o el único) paquete
  72 binario listado en debian/control, debhelper usará debian/tal si no
  73 existe debian/paquete.tal.
  74
  75 En algunos casos raros, puede querer tener diferentes versiones de los archivos
  76 para diferentes arquitecturas. Si los ficheros debian/paquete.tal.arch existen,
  77 donde "arch" es igual a la salida de "dpkg --print-architecture", entonces se
  78 usarán preferentemente a otros ficheros generales.
  79
  80 En muchos casos, estos ficheros de configuración se usan para especificar varios
  81 tipos de ficheros. Documentación o ficheros de ejemplo a instalar, ficheros a
  82 mover, y demás.  Cuando sea apropiado, en casos como estos, puedes usar
  83 comodines del shell como ('?' y '*') en estos ficheros.
  84
  85 =head1 OPCIONES COMPARTIDAS DE DEBHELPER
  86
  87 La siguiente línea de órdenes es aceptada por todos los programas de debhelper.
  88
  89 =over 4
  90
  91 =item B<-v>, B<--verbose>
  92
  93 Modo explicativo: muestra todos las órdenes que modifican el directorio de
  94 construcción del paquete.
  95
  96 =item B<--no-act>
  97
  98 No hacer nada realmente. Si se usa con -v, mostrará todo lo que hubiera hecho.
  99
 100 =item B<-a>, B<--arch>
 101
 102 Actuar en todos los paquetes dependientes de la arquitectura.
 103
 104 =item B<-i>, B<--indep>
 105
 106 Actuar en todos los paquetes independientes de la arquitectura.
 107
 108 =item B<->I<ppaquete>, B<--package=>I<paquete>
 109
 110 Actúa sobre el paquete nombrado "paquete". Esta opción puede
 111 ser especificada varias veces para hacer que debhelper opere sobre una
 112 serie de paquetes.
 113
 114 =item B<-s>, B<--same-arch>
 115
 116 Esta es una opción refinada de la opción -a, que se usa en raras circunstancias.
 117 Si el fichero de control tiene una línea para el paquete como "Architecture:
 118 i386", entonces debhelper no actuará sobre el paquete en otras
 119 arquitecturas. Así pues, esta opción hace que la orden actúe en todos los
 120 paquetes "Architecture: any" así como en cualquier paquete que tenga la
 121 arquitectura actual definida explícitamente. Esto es distinto a la opción -a,
 122 que hace que la orden actúe en todos los paquetes que son dependientes de la
 123 arquitectura.
 124
 125 =item B<-N>I<paquete>, B<--no-package=>I<paquete>
 126
 127 No actuar sobre un paquete especificado incluso si las opciones -a, -i, o -p
 128 listan este paquete como uno sobre los que se debe actuar.
 129
 130 =item B<-P>I<tmpdir>, B<--tmpdir=>I<tmpdir>
 131
 132 Usa "tmpdir" como directorio para construir el paquete. Por defecto es
 133 debian/<paquete>.
 134
 135 =item B<--mainpackage=>I<paquete>
 136
 137 Esta opción poco usada cambia el paquete que debhelper considera el "paquete
 138 principal", esto es, el primero listado en debian/control, y sobre el cual se
 139 pueden usar los ficheros debian/tal en vez de los usuales debian/package.tal.
 140
 141 =back
 142
 143 =head1 OPCIONES COMUNES DE DEBHELPER
 144
 145 Las siguientes opciones son válidas para algunos programas de debhelper. Mire la
 146 página del manual de cada programa para una explicación detallada de lo que hace
 147 cada una.
 148
 149 =over 4
 150
 151 =item B<-n>
 152
 153 No modificar los scripts postinst/postrm/etc.
 154
 155 =item B<-X>I<elemento>, B<--exclude=>I<elemento>
 156
 157 No procesar un elemento. Esta opción puede ser usada varias
 158 veces, para excluir distintos elementos.
 159
 160 =item B<-A>, B<-all>
 161
 162 Hace que los archivos o elementos especificados en la línea de órdenes tengan
 163 efecto en TODOS los paquetes sobre los que actúa, no sólo el primero.
 164
 165 =back
 166
 167 =head1 NOTAS
 168
 169 =head2 Soporte para varios paquetes binarios
 170
 171 Si su paquete fuente genera más de un paquete binario, por defecto los
 172 programas de debhelper actuarán sobre todos los paquetes binarios. Si
 173 se diera el caso de que su paquete fuente genera un paquete
 174 dependiente de la arquitectura, y otro independiente, este no es un
 175 comportamiento correcto, porque necesitará generar los paquetes
 176 dependientes de la arquitectura en el objetivo binary-arch de
 177 debian/rules, y los paquetes independientes de la arquitectura en el
 178 objetivo binary-indep de debian/rules.
 179
 180 Para facilitar esto, así como para dar mayor control sobre qué paquetes actúan
 181 los programas de debhelper, todos estos aceptan los parámetros <-a>, B<-i>,
 182 B<-p>, y B<-s>. Estos parámetros son acumulativos. Si no se especifica ninguno
 183 los programas de debhelper actúan por defecto en todos los paquetes listados en
 184 el fichero de control.
 185
 186 Consulte F</usr/share/doc/debhelper/examples/rules.multi> para ver un ejemplo de
 187 como usar esto en un paquete que genera múltiples paquetes binarios.
 188
 189 =head2 Generación automática de los scripts de instalación de debian
 190
 191 Algunas órdenes de debhelper generarán automáticamente parte de los scripts de
 192 instalación de Debian. Si quiere que estas órdenes generen automáticamente lo
 193 que esté incluido en sus scripts de instalación de debian, entonces necesita
 194 añadir "#DEBHELPER#" a tus scripts, en el lugar donde el código deba de ser
 195 añadido. "#DEBHELPER#" será remplazado por cualquier código auto-generado
 196 cuando ejecutes dh_installdeb.
 197
 198 Todos los scripts que generan código automáticamente de esta manera se
 199 pueden deshabilitar con el parámetro -n (ver arriba).
 200
 201 Fijese que el código insertado sera código de shell, por eso no puede usarlo
 202 directamente es un script perl. Si desea introducirlo en un script perl, hagalo
 203 de la siguiente forma (Dese cuenta que en este caso, se asegura que $1, $2, etc
 204 están establecidas con la orden set):
 205
 206   my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
 207   #DEBHELPER#
 208   EOF
 209   system ($temp) / 256 == 0
 210         or die "Problema con los scripts de debhelper: $!";
 211
 212 =head2 Generación automática de diversas dependencias.
 213
 214 Es posible que algunas órdenes de debhelper hagan que los paquetes generados
 215 dependan de otros paquetes. Por ejemplo, si usas L<dh_installdebconf(1)>, el
 216 paquete que genera dependerá de debconf. Si usas L<dh_installxfonts(1)>, el
 217 paquete dependerá de una determinada versión de xutils. Llevar la cuenta de
 218 todas estas dependencias puede ser tedioso, porque dependen de como debhelper
 219 haga las cosas, por eso debhelper ofrece una manera de automatizarlo.
 220
 221 Todas las órdenes de este tipo, además de documentar qué dependencias pueden ser
 222 necesarias en las páginas del manual, generarán automáticamente una variable de
 223 substitución llamada ${misc:Depends}. Si introduce esta variable en el archivo
 224 debian/control, será expandida a las dependencias que debhelper crea oportunas.
 225
 226 Esto es totalmente independiente de la estándar ${shlibs:Depends} generada por
 227 L<dh_makeshlibs(1)>, y de la ${perl:Depends} generada por L<dh_perl(1)>. Puedes
 228 elegir no elegir ninguna de estas si la expansión de debhelper de estas
 229 variables no son correctas.
 230
 231 =head2 Directorios de construcción del paquete
 232
 233 Por defecto, todos los programas de debhelper asumen que el directorio temporal
 234 usado para ensamblar el árbol de ficheros en un paquete es debian/<paquete>.
 235
 236 Algunas veces, puede que desee usar otro directorio temporal. Esto se puede
 237 conseguir con la opción -P. Por ejemplo, "dh_installdocs -Pdebian/tmp", usará el
 238 directorio debian/tmp como directorio temporal. Dese cuenta que si usas la
 239 opción -P, los programas de debhelper sólo pueden actuar sobre un paquete a la
 240 vez. Por eso, si tiene un paquete que construye muchos paquetes binarios, tendrá
 241 que hacer uso de la opción -p para especificar el paquete binario sobre el que
 242 debhelper actuará.
 243
 244 =head2 Niveles de compatibilidad de debhelper
 245
 246 Cada cierto tiempo, debhelper necesita cambios que lo pueden hacer incompatible
 247 con versiones anteriores, para de este modo mantenerse con un buen diseño a
 248 medida que necesita cambios y que su autor gana más experiencia. Los niveles de
 249 compatibilidad de debhelper se crearon para impedir que estos cambios estropeen
 250 algún paquete. Según el nivel de compatibilidad que se especifique debhelper se
 251 comporta de diferentes maneras.
 252
 253 Para especificar un nivel de compatibilidad debes de escribir un número en
 254 debian/compat. Por ejemplo, para activar el modo V4:
 255
 256   % echo 4 > debian/compat
 257
 258 Los niveles de compatibilidad disponibles son:
 259
 260 =over 4
 261
 262 =item V1
 263
 264 Este es el nivel de compatibilidad original de debhelper, y por tanto es el
 265 nivel por defecto. En este modo, debhelper usa debian/tmp como el árbol de
 266 directorios y debian/paquete para el resto de paquetes listados en el fichero de
 267 control. Se desaconseja su uso.
 268
 269 =item V2
 270
 271 En este modo, debhelper usará consistentemente debian/<paquete> como el árbol de
 272 directorios para cada paquete que se construya.
 273
 274 =item V3
 275
 276 Este modo funciona como el V2 con los siguientes añadidos:
 277
 278 =over 8
 279
 280 =item -
 281
 282 Los ficheros de configuración de Debhelper soportan comodines mediante * y ?
 283 cuando sea apropiado. Para usar * y ? simplemente como caracteres poner como
 284 prefijo una barra invertida.
 285
 286 =item -
 287
 288 dh_makeshlibs hace que los scripts postinst y postrm ejecuten ldconfig.
 289
 290 =item -
 291
 292 dh_installdeb marca automáticamente todos los ficheros en etc/ como conffiles.
 293
 294 =back
 295
 296 =item V4
 297
 298 Este es el modo de operación aconsejado. Hace lo mismo que V3 y además:
 299
 300 =over 8
 301
 302 =item -
 303
 304 dh_makeshlibs -V no incluirá la parte de Debian en el numero de  versión
 305 generado en la línea de dependencias del fichero shlibs.
 306
 307 =item -
 308
 309 Se aconseja que use el nuevo ${misc:Depends} en debian/control para reemplazar
 310 el campo ${shlibs:Depends}.
 311
 312 =item -
 313
 314 dh_fixperms hará ejecutables todos los archivos en los directorios bin/ y etc/init.d.
 315
 316 =item -
 317
 318 dh_link corregirá los enlaces existentes para ajustarse a la política de debian.
 319
 320 =back
 321
 322 =back
 323
 324 =head2 Enlaces a los directorios Doc
 325
 326 A veces es útil hacer que un paquete no tenga un directorio
 327 /usr/share/doc/paquete, en vez de esto se hará un enlace colgando en el paquete
 328 binario que apunte a otro directorio de documentación.  La política de Debian
 329 permite esto mientras mientras el paquete dependa del paquete al que pertenece
 330 el directorio de documentación que está usando. Para conseguir esto, lo único
 331 que hay que hacer es no decirle a debhelper que cree ningún directorio con
 332 documentación y usar dh_link para crear el enlace (o crear el enlace a mano), y
 333 debhelper hará lo correcto: se dará cuenta de que es un enlace colgante y no
 334 tratará de instalar un fichero de copyright o changelog.
 335
 336 =head2 udebs
 337
 338 Debhelper incluye soporte para udebs. Para crear un udeb con debhelper, añada
 339 "XC-Package-Type: udeb" al párrafo del paquete binario en debian/control, y una
 340 dependencia de construcción en debhelper (>= 4.2). Debhelper tratará de crear
 341 udebs que cumplan con las normas del "debian-installer", haciendo que los
 342 ficheros de los paquetes terminen en ".udeb", no instalando ninguna
 343 documentación en un udeb, pasando de los scripts de preinst, postrm, prerm, y
 344 de configuración, etc.
 345
 346 =head2 Otras notas
 347
 348 En general si algún programa de debhelper necesita que exista un directorio bajo
 349 debian/, lo creará. No me he preocupado por documentarlo en todas las páginas
 350 del manual, pero por ejemplo, dh_installdeb sabe hacer debian/<paquete>/DEBIAN/
 351 antes de tratar de poner los ficheros allí, dh_installmenu sabe que necesita
 352 debian/<paquete>/usr/lib/menu/ antes de instalar los archivos del menú, etc.
 353
 354 Una vez que su paquete usa debhelper para construirse, asegurese de añadir
 355 debhelper a sus dependencias de construcción en debian/control.  Debería usar
 356 como build-depend una versión de debhelper igual a (o mayor) el nivel de
 357 compatibilidad de debhelper que use su paquete. Por ejemplo, si su paquete usa
 358 el nivel de compatibilidad 4:
 359
 360   Build-Depends: debhelper (>= 4)
 361
 362 =head1 ENTORNO
 363
 364 =over 4
 365
 366 =item DH_VERBOSE
 367
 368 Poner a uno para activar el modo explicativo. Debhelper mostrará todas las
 369 órdenes usadas que modifiquen ficheros en el sistema en el que se hace la
 370 construcción.
 371
 372 =item DH_COMPAT
 373
 374 Especifica temporalmente bajo que nivel de compatibilidad debe de actuar
 375 debhelper, ignorando cualquier valor en debian/compat.
 376
 377 =item DH_NO_ACT
 378
 379 Poner a 1 para habilitar el modo no-act.
 380
 381 =item DH_OPTIONS
 382
 383 Todo lo que halla en esta variable se antepondrá a los argumentos en la línea de
 384 órdenes de todas las órdenes de debhelper. Esto es útil en algunas situaciones,
 385 por ejemplo, si necesita pasar la opción -p a todas las órdenes de debhelper que
 386 va a utilizar. Una buena manera de dar valor a DH_OPTIONS es usando
 387 "Target-specific Variable Values" en su fichero debian/rules. Lea la
 388 documentación de make para los detalles sobre como hacer esto.
 389
 390 =item DH_ALWAYS_EXCLUDE
 391
 392 Si está establecida, añade su valor a la opción -X de todas las órdenes que
 393 soporten dicha opción. Es más, dh_builddeb hará un rm -rf a todo lo que
 394 coincida con el valor en el árbol de construcción.
 395
 396 Esto puede ser útil si está compilando desde un árbol de CVS, en cuyo caso
 397 estableciendo DH_ALWAYS_EXCLUDE=CVS evitará que los directorios CVS se
 398 introduzcan en el paquete construido. O, si su paquete original
 399 (imprudentemente) incluye directorios CVS, puede ser útil exportar
 400 ALWAYS_EXCLUDE=CVS en debian/rules, para que esto tenga efecto en cualquier
 401 sitio donde se construya el paquete.
 402
 403 Si se tienen varias cosas para excluir, éstas pueden separarse mediante dos
 404 puntos, p. ej.: DH_ALWAYS_EXCLUDE=CVS:.svn
 405
 406 =back
 407
 408 =head1 VÉASE ADEMÁS
 409
 410 =over 4
 411
 412 =item F</usr/share/doc/debhelper/examples/>
 413
 414 Varios ficheros de ejemplo debian/rules que usan debhelper.
 415
 416 =item L<http://kitenet.net/programs/debhelper/>
 417
 418 Web de Debhelper.
 419
 420 =back
 421
 422 =head1 AUTOR
 423
 424 Joey Hess <joeyh@debian.org>
 425
 426 =cut