path: root/man/es/debhelper.pod

# (c) 2003 Software in the Public Interest
# Esta traducci�n ha sido realizada por Rub�n Porras Campo <nahoo@inicia.es>
# y revisada por Javier Fern�ndez-Sanguino <jfs@computer.org>,
# Santiago Vila <sanvila@unex.es> y Esteban Manchado <zoso@demiurgo.org>
# Est� basada en la p�gina de manual original:
# versi�n 1.6 del CVS de
# /cvs/debian-doc/manpages/english/debhelper/debhelper.pod

=head1 NOMBRE

debhelper - El conjunto de herramientas debhelper

=head1 SINOPSIS

B<dh_>I<*> [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</usr/share/doc/debhelper/examples/>

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<dh_make|dh_make(1)> 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<debian/> para
controlar lo que hacen. Adem�s de los ficheros comunes F<debian/changelog> y
F<debian/control>, 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<ppaquete>, B<--package=>I<paquete>

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<paquete>, B<--no-package=>I<paquete>

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<tmpdir>, B<--tmpdir=>I<tmpdir>

Usa "tmpdir" como directorio para construir el paquete. Por defecto es
debian/<paquete>.

=item B<--mainpackage=>I<paquete>

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<elemento>, B<--exclude=>I<elemento>

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</usr/share/doc/debhelper/examples/rules.multi> 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<dh_installdebconf(1)>, el
paquete que genera depender� de debconf. Si usas L<dh_installxfonts(1)>, 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<dh_makeshlibs(1)>, y de la ${perl:Depends} generada por L<dh_perl(1)>. 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/<paquete>.

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/<paquete> 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 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/<paquete>/DEBIAN/
antes de tratar de poner los ficheros all�, dh_installmenu sabe que necesita
debian/<paquete>/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</usr/share/doc/debhelper/examples/>

Varios ficheros de ejemplo debian/rules que usan debhelper.

=item L<http://kitenet.net/programs/debhelper/>

Web de Debhelper.

=back

=head1 AUTOR

Joey Hess <joeyh@debian.org>

=cut