Provided by:
dpkg-dev_1.15.8.4ubuntu3_all 
NOMBRE
dpkg-gensymbols - Generacin de ficheros symbols (informacin de
dependencia de bibliotecas compartidas)
SINOPSIS
dpkg-gensymbols [opciones]
DESCRIPCIN
dpkg-gensymbols analiza un rbol temporal de construccin (debian/tmp por
omisin) en busca de bibliotecas para generar un fichero symbols que los
describa. Este fichero, si no est vaco, se instala en el subdirectorio
DEBIAN del rbol de construccin, para despus incluir el contenido en la
informacin de control del paquete.
Al generar estos ficheros, usa algunos ficheros symbols como entrada
proporcionados por el desarrollador. Busca los siguientes ficheros,
usando el primero que encuentra.
o debian/package.symbols.arch
o debian/symbols.arch
o debian/package.symbols
o debian/symbols
La meta principal de estos ficheros es proporcionar la versin mnima
asociada a cada smbolo proporcionado por las bibliotecas.
Habitualmente, se corresponde con la primera versin de ese paquete que
proporciona el smbolo, pero el desarrollador lo puede incrementar
manualmente si la ABI del smbolo se extiende sin romper la
compatibilidad con versiones anteriores. Es la responsabilidad del
desarrollador que estos ficheros estn al da y que sean apropiados, pero
dpkg-gensymbols le asiste en esta tarea.
Cuando los ficheros symbols generados difieren del proporcionado por el
desarrollador, dpkg-gensymbols mostrar las diferencias entre ambas
versiones. Ms an, puede que falle si la diferencia es demasiado grande,
(puede configurar cuanta diferencia tolerar, consulte la opcin -c).
MANTENER FICHEROS SYMBOLS
Los ficheros symbols son realmente tiles slo cuando reflejan la
evolucin del paquete a lo largo de varias publicaciones. Por ello, el
desarrollador tiene que actualizarlos cada vez que se aada un smbolo
nuevo, para que as la mnima versin asociada concuerde con la realidad.
Para hacer esto apropiadamente puede usar los diff contenidos en los
registros de construccin. En la mayora de los caso, el diff se aplica
directamente sobre el fichero debian/package.symbols. Dicho esto, es
necesario afinar este proceso: se recomienda, por ejemplo, eliminar el
nmero de revisin de Debian de la versin mnima para que as aquellas
adaptaciones hacia atrs (backports) con un nmero de versin menor, pero
con la misma versin que la fuente original, puedan satisfacer las
dependencias generadas. Si no se puede eliminar la revisin de Debian
porque el smbolo se aadi debido a un cambio especfico de Debian puede
afijar ~ a la versin.
Antes de aplicar un parche al fichero symbols el desarrollador debera
revisar nuevamente que es adecuado. Se espera que los smbolos pblicos
no desaparezcan as que, idealmente, el parche slo debera aadir lneas
nuevas.
Usar la sustitucin de #PACKAGE#
En algunos casos aislados el nombre de la biblioteca vara segn la
arquitectura. Puede usar el marcador #PACKAGE# para evitar incrustar
(hardcode) el nombre del paquete en el fichero symbols. Se reemplazar
por el nombre real del paquete durante la instalacin de los ficheros
symbols. A diferencia del marcador #MINVER#, #PACKAGE# nunca aparecer
en un fichero symbols contenido en un paquete binario.
Usar etiquetas de smbolos
El etiquetado de smbolos es til para marcar aquellos smbolos que son de
alguna manera especiales. Cada smbolo puede tener un nmero arbitrario
de etiquetas asociadas a ste. Aunque se analizan y guardan todas las
etiquetas, dpkg-gensymbols slo entiende algunas de ellas, e iniciar un
tratamiento especial de los smbolos. Consulte la sub-seccin Etiquetas
estndar de smbolos para una referencia de estas etiquetas.
La especificacin de la etiqueta aparece a continuacin del nombre del
smbolo (no se permite un espacio vaco entre estos). Siempre comienza
con un parntesis de apertura (, finaliza con un parntesis de cierre ),
y debe contener al menos una etiqueta. Varias etiquetas se separan con
un carcter |. Opcionalmente, cada etiqueta puede tener un valor
separado del nombre de la etiqueta mediante el carcter =. Los nombres
de etiqueta y valores pueden ser cadenas arbitrarias, a excepcin de que
no pueden contener ningn carcter especial: ), | y =. Los nombres de
smbolo a continuacin de una especificacin de etiqueta se pueden
entrecomillar con caracteres ' o ", permitiendo as espacios vacos. Por
otra parte, de no existir ninguna etiqueta definida para el smbolo, las
comillas se tratarn como parte del nombre del smbolo, continuando hasta
el primer espacio.
(tag1=tengo una marca|nombre de etiqueta con espacio)"smbolo
entrecomillado y etiquetado"@Base 1.0
(optional)smbolo_sin_comillas_y_etiquetado@Base 1.0 1
smbolo_sin_etiquetar@Base 1.0
El primer smbolo del ejemplo se llama smbolo entrecomillado y
etiquetado, y tiene dos etiquetas: tag1, con el valor tengo una marca y
nombre de etiqueta con espacio, que no tiene valor. El segundo smbolo
se llama smbolo_sin_comillas_y_etiquetado, y slo tiene una etiqueta
llamada optional. El ltimo smbolo es un ejemplo de un smbolo normal sin
etiquetar.
Debido a que las etiquetas de smbolos son una extensin del formato
deb-symbols(5) slo pueden formar parte de los ficheros symbols de
paquetes fuente (estos ficheros deberan aparecer como plantillas usadas
para generar los ficheros symbols integrados en paquetes binarios).
Cuando invoca dpkg-gensymbols con la opcin -t, enviar por la salida
ficheros symbols compatibles con el formato deb-symbols(5): procesa
completamente los smbolos de acuerdo a los requerimientos de sus
etiquetas estndar, y elimina todas las etiquetas de la salida. Por otra
parte, en el modo plantilla (-t), todos los smbolos y etiquetas
(estndar y desconocidos) se muestran por la salida, y se escriben en su
forma original a medida que se cargan.
Etiquetas de smbolo estndar
optional
Un smbolo marcado como opcional puede desaparecer de la
biblioteca en cualquier momento sin causar un fallo de
dpkg-gensymbols. Por otra parte, los smbolos opcionales
desaparecidos aparecern continuamente como MISSING (ausente) en
el diff de cada nueva revisin del paquete. Este comportamiento
sirve como un recordatorio para el desarrollador para informar
de la necesidad de eliminar tal smbolo del fichero symbols, o de
aadir ste nuevamente a la biblioteca. Cuando el smbolo opcional
declarado previamente como MISSING reaparece de sbito en la
siguiente revisin, se actualizara a un estado existente sin
modificar la versin mnima.
Esta etiqueta es til para aquellos smbolos privados cuya
desaparicin no rompe la ABI. Por ejemplo, la mayora de
plantillas de produccin de un objeto definido ms especficamente
por medio del reemplazo de ciertas variables por valores
(instantiation) de C++ se encuentran dentro de esta categora. Al
igual que con cualquier otra etiqueta, ste puede tener un valor
arbitrario: se puede usar para indicar porqu el smbolo se
considera opcional.
arch=lista-de-arquitecturas
Esta etiqueta permite limitar el conjunto de arquitecturas dnde
se supone que el smbolo existe. Cuando la lista de smbolos se
actualiza con los smbolos descubiertos en la biblioteca, todos
los smbolos especficos de la arquitectura que no son relevantes
para la arquitectura anfitrin se toman como no existentes. Si un
smbolo especfico a la arquitectura que concuerda con la
arquitectura anfitrin presente no existe en la biblioteca, se
aplicarn los procedimientos normales para smbolos desaparecidos,
llevando a que dpkg-gensymbols falle. Por otra parte, si el
smbolo especfico a la arquitectura se encuentra cuando se supona
que no existe (porque la arquitectura anfitrin presente no est
listada en la etiqueta), pasa a ser neutral a la arquitectura
(por ejemplo, se elimina la etiqueta de arquitectura,
apareciendo el smbolo en el diff debido a la modificacin), pero
no se toma como un nuevo smbolo.
Al operar en el modo por omisin (sin plantilla) slo se escribirn
al fichero symbols aquellos smbolos especficos a la arquitectura
que coinciden con la arquitectura anfitrin. Por otra parte, en
el modo plantilla todos los smbolos especficos a la arquitectura
(incluyendo arquitecturas alternativas) siempre se escribirn al
fichero symbols.
El formato de lista-de-arquitecturas es el mismo que el usado en
el campo Build-Depends de debian/control (a excepcin de los
parntesis cuadrados de cierre []). Por ejemplo, el primer smbolo
de la lista a continuacin se considerar slo en las arquitecturas
alpha, amd64, kfreebsd-amd64 y ia64, mientras que el segundo en
todos menos armel.
(arch=alpha amd64 kfreebsd-amd64 ia64)un_smbolo
_especfico_64bit@Base 1.0
(arch=!armel)smbolo_que_armel_no_tiene@Base 1.0
ignore-blacklist
dpkg-gensymbols tiene una lista negra interna de smbolos que no
deberan aparecer en los ficheros symbols, ya que habitualmente
son slo efectos secundarios de los detallas de implementacin de
la cadena de herramientas. Si por alguna razn desea incluir uno
de esos smbolos en el fichero symbols debera etiquetar el smbolo
con ignore-blacklist. Puede ser necesario con alguna cadena de
herramientas de bajo nivel como libgcc.
c++ Denota el patrn c++- Consulte la subseccin a continuacin Usar
patrones de smbolos.
symver Denota el patrn de smbolos symver (versin del smbolo). Consulte
la sub-seccin a continuacin Usar patrones de smbolos.
regex Denota el patrn de smbolos regex (expresin regular). Consulte la
sub-seccin a continuacin Usar patrones de smbolos.
Usar patrones de smbolos.
A diferencia de cualquier definicin de smbolo estndar un patrn puede
cubrir varios smbolos reales de la biblioteca. dpkg-gensymbols intentar
emparejar cada patrn con cada smbolo real que no tiene un smbolo
especfico de contrapartida definido en el fichero de smbolos. En el
momento que se encuentre el primer patrn que coincida se usarn todas
sus etiquetas y propiedades como un definicin bsica del smbolo. Si
ninguno de los patrones encaja, el smbolo se considerar nuevo.
Un patrn se considera perdido si no encaja con ningn smbolo en la
biblioteca. Por omisin, esto accionar un fallo de dpkg-gensymbols bajo
-c1 o un nivel superior. Aun as, si no desea la aparicin del fallo,
puede marcar el patrn con la etiqueta optional. Entonces, si el patrn
no encaja con nada simplemente aparecer en el diff como MISSING. An ms,
al igual que con cualquier smbolo, puede limitar el patrn a unas
arquitecturas definidas con la etiqueta arch. Consulte la seccin
anterior Etiquetas de smbolo estndar.
Los patrones son una extensin del formato deb-symbols(5), y por ello
slo son vlidos en plantillas de fichero de smbolos. Por otra parte, la
parte del nombre del smbolo definido sirve como una expresin que se
comparar con el nombre@versin del smbolo real. Para poder distinguir
entre los diferentes tipos de patrn, ste se etiquetar habitualmente con
una etiqueta especial.
A da de hoy, dpkg-gensymbols es compatible con tres tipos de patrones
bsicos:
c++
Este patrn se indica con la etiqueta c++. Slo encaja con el nombre
demangled de smbolos C++ (tal y como muestra la herramienta
c++filt(1)). Este patrn es de utilidad para emparejar smbolos con
nombres mangled que pueden variar segn la arquitectura, mientras que
sus nombres demangled permanecen sin cambios. Un grupo de estos
smbolos son los thunk no virtuales, que tienen direcciones relativas
(offsets) especficas a la arquitectura integradas en sus nombres
mangled. Un ejemplo comn de este caso es un destructor virtual, que
bajo una herencia de diamante necesita un smbolo thunk no virtual.
Por ejemplo, incluso si _ZThn8_N3NSB6ClassDD1Ev@Base en
arquitecturas de 32bit es _ZThn16_N3NSB6ClassDD1Ev@Base en
arquitecturas de 64bit, puede emparejarlo con un nico patrn c++:
libdummy.so.1 libdummy1 #MINVER#
[...]
(c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
[...]
Puede obtener el nombre demangled del ejemplo anterior ejecutando la
siguiente orden:
$ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt
Observe que aunque el nombre mangled sea por definicin nico en la
biblioteca, no es necesariamente cierto para nombres demangled.
Puede que dos smbolos reales y distintos tengan el mismo nombre
demangled. Por ejemplo, en caso de existir smbolos thunk no
virtuales en complejas configuraciones de herencia, o con la mayora
de constructores y destructores (ya que habitualmente g++ genera dos
smbolos para ellos). Por otra parte, estas colisiones aparecen al
nivel de la ABI, y por ello no deberan degradar la calidad del
fichero de smbolos.
symver
La etiqueta symver indica este patrn. Las bibliotecas bien
mantenidas tienen smbolos con versin, donde cada versin corresponde
con la versin del autor original en la que se aadi el smbolo. De ser
as, puede usar un patrn symver para emparejar el smbolo asociado con
una versin en particular. Por ejemplo:
libc.so.6 libc6 #MINVER#
(symver)GLIBC_2.0 2.0
[...]
(symver)GLIBC_2.7 2.7
access@GLIBC_2.0 2.2
Todos los smbolos asociados con las versiones GLIBC_2.0 y GLIBC_2.7
llevan a una versin mnima de 2.0 y 2.7 respectivamente, con la
excepcin del smbolo access@GLIBC_2.0. El segundo lleva a una
dependencia mnima sobre la versin 2.2 de libc6, a pesar de estar en
el rango del patrn (symver)GLIBC_2.0, debido a que los smbolos
especficos tiene precedencia sobre los patrones.
Tenga en cuanta que los patrones de comodn antiguos (indicados por
*@versio en el campo del nombre del smbolo) son an compatibles,
aunque han quedado obsoletos por el nuevo estilo de sintaxis
(symver|optional)versin. Por ejemplo, debera escribir *@GLIBC_2.0
2.0 como (symver|optional)GLIBC_2.0 2.0 si desea el mismo
comportamiento.
regex
Los patrones de expresiones regulares se indican con la etiqueta
regex. Buscan coincidencias con la expresin regular de perl definido
en el campo de nombre del smbolo. Una expresin regular se empareja
tal cual, por ello no olvide insertar ^ al inicio de la misma o
puede que coincida con cualquier parte de la cadena real del smbolo
nombre@versin. Por ejemplo:
libdummy.so.1 libdummy1 #MINVER#
(regex)"^mystack_.*@Base$" 1.0
(regex|optional)"private" 1.0
Los smbolos como mystack_new@Base, mystack_push@Base,
mystack_pop@Base y similares encajaran con el primer patrn, mientras
que otros como ng_mystack_new@Base no lo haran. El segundo patrn
encaja con todos los smbolos con private en su nombre, y las
coincidencias heredarn de este patrn la etiqueta optional.
Puede combinar los patrones listados anteriormente, cuando tenga
sentido. En tal caso, se procesan en el orden de las etiquetas
definidas. Por ejemplo, ambos
(c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
(regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
encaja con _ZN3NSA6ClassA7Private11privmethod1Ei@Base y
_ZN3NSA6ClassA7Private11privmethod2Ei@Base. Al comparar el primer patrn
se demangle el smbolo sin procesar como smbolo C++, para despus
comparar el nombre demangled con la expresin regular. Por otra parte,
al comparar el segundo patrn la expresin regular se compara con el
nombre sin procesar del smbolo, para despus confirmar si es un smbolo
de C++ mediante demangle. Un fallo de un patrn bsico lleva a un fallo
de todo el patrn. Por ejemplo,
__N3NSA6ClassA7Private11privmethod\dEi@Base no encajara con ningn patrn
porque no es un smbolo vlido de C++.
En general, todos los patrones se dividen en dos grupos: aliases (los
bsicos c++ y symver) y patrones genricos (regex, todas las
combinaciones de varios patrones bsicos). Establecer coincidencias con
patrones basados en alias es rpido (0(1)) mientras que los patrones
genricos son 0(N) (N - cuenta genrica del patrn) para cada smbolo.
Debido a ello, se recomienda no abusar de los patrones genricos.
Los alias (primero c++, despus symver) tienen prioridad sobre los
patrones genricos. stos se emparejan por orden de aparicin en la
plantilla del fichero de smbolos hasta el primer resultado de xito.
Tenga en cuenta, no obstante, que no se recomienda la reorganizacin
manual de las entradas en plantillas de fichero ya que dpkg-gensymbols
genera diffs basados en el orden alfanumrico de sus nombres.
Usar include
Hay casos en los que usar un slo fichero de smbolos es contraproducente
cuando el conjunto de smbolos exportados difiere segn la arquitectura.
En estos casos, una directiva include puede ser til de un par de
maneras:
o Puede factorizar la parte comn en algn fichero externo, e incluir
ese fichero en su fichero paquete.symbols.arq usando una directiva
include como esta:
#include "packages.symbols.common"
o Al igual que con cualquier smbolo, puede etiquetar la directiva
include:
(etiqueta|..|etiquetaN)#include "fichero-para-include"
Como resultado, se considerar que todos los smbolos incluidos en
fichero-para-include estn etiquetados con etiqueta .. etiquetaN por
omisin. Puede usar esta caracterstica para crear un fichero comn
package.symbols, que incluye ficheros de smbolos especficos a la
arquitectura.
common_symbol1@Base 1.0
(arch=amd64 ia64 alpha)#include "package.symbols.64bit"
(arch=!amd64 !ia64 !alpha)#include "package.symbols.32bit"
common_symbol2@Base 1.0
Los ficheros de smbolos se leen lnea a lnea, y las directivas include
se procesan por orden de aparicin. Esto significa que el contenido del
fichero incluido puede sustituir cualquier contenido aparecido antes de
la directiva include, y que todo contenido a continuacin de la
directiva puede sustituir cualquier contenido del fichero incluido.
Todo smbolo (o incluso otra directiva #include) en el fichero incluido
puede especificar etiquetas adicionales, o sustituir valores de las
etiquetas heredadas en la especificacin de etiqueta. Por otra parte, el
smbolo no puede eliminar ninguna de las etiquetas heredadas.
Un fichero incluido puede repetir la lnea de cabecera que contiene el
SONAME de la biblioteca. En tal caso, sustituye cualquier lnea de
cabecera leda anteriormente. Por otra parte, generalmente es mejor
evitar duplicar las lneas de cabecera. A continuacin puede ver una
manera de realizar esto:
#include "libsomething1.symbols.common"
arch_specific_symbol@Base 1.0
Buena gestin de bibliotecas
Una biblioteca mantenida adecuadamente tiene las siguientes
caractersticas:
o su API es estable (los smbolos pblicos nunca se eliminan, sino que
slo se aaden smbolos nuevos), y los cambios pueden introducir una
incompatibilidad slo cuando el SONAME cambia;
o Idealmente, usa el versionado de smbolos para alcanzar la
estabilidad de la ABI, a pesar de cambios internos y la extensin de
la API;
o No exporta smbolos privados (tales como smbolos etiquetados como
opcionales para evitar un problema).
Al mantener un fichero symbols es sencillo notar la aparicin y
desaparicin de smbolos. Pero es ms difcil notar cambios incompatibles
en las API y ABI. Por ello, el responsable del paquete debera leer
cuidadosamente el registro de cambios de la fuente original en busca de
casos en los que se ha roto la correcta gestin de bibliotecas. Se
debera notificar al autor original en caso de encontrar problemas
potenciales, ya que un arreglo en la fuente original del software es
siempre preferible a un arreglo especfico de Debian.
OPCIONES
-Pdirectorio-compilacin-paquete
Analiza directorio-compilacin-paquete en lugar de debian/tmp.
-ppaquete
Define el nombre del paquete. Es necesario si aparece ms de un
paquete binario en debian/control (o si no existe ningn fichero
debian/control).
-vversin
Define la versin del paquete. El valor por omisin es la versin
extrada de debian/changelog. Necesario en caso de una invocacin
externa al rbol del paquete fuente.
-efichero-biblioteca
Slo analiza las bibliotecas listadas explcitamente, en lugar de
buscar todas las bibliotecas pblicas. Puede usar una expresin
regular en fichero-biblioteca para emparejar varias bibliotecas
con un nico argumento (de otra forma, necesita varias -e).
-Inombre-fichero
Usa nombre-fichero como un fichero de referencia para generar el
fichero symbols integrado en el mismo paquete.
-O Muestra por la salida estndar el fichero symbols generado, en
lugar de almacenarlo en el rbol de construccin del paquete.
-Ofichero
Guarda el fichero de smbolos generado como fichero. Si el
fichero ya existe su contenido se usar como base para el fichero
symbols generado. Puede usar esta caracterstica para actualizar
un fichero symbols para que coincida con una versin ms reciente
de la biblioteca del autor original.
-t Escribe el fichero symbols en modo plantilla en lugar del
formato compatible con deb-symbols(5). La diferencia ms notable
es que en modo plantilla los nombres de smbolo y etiquetas se
escriben en su forma original, en lugar de los nombres de smbolo
post-procesados con las etiquetas eliminadas en modo compatible.
Adems, puede que se omitan algunos smbolos al escribir un
fichero estndar de deb-symbols(5) (de acuerdo a las reglas de
procesamiento de etiquetas), mientras que siempre se insertan
todos los smbolos en el modo plantilla.
-c[0-4]
Define las comprobaciones a realizar al comparar el fichero
symbols generado usando como base el fichero de plantilla. El
nivel predefinido es 1. Aumentar los niveles conlleva ms
comprobaciones, as como la inclusin de todos los niveles
inferiores. El nivel 0 nunca falla. El nivel 1 falla si algunos
smbolos han desaparecido. El nivel 2 falla si se han introducido
smbolos nuevos. El nivel 3 falla si han desaparecido algunas
bibliotecas. El nivel 4 falla si se han introducido bibliotecas
nuevas.
Puede sustituir este valor con la variable de entorno
DPKG_GENSYMBOLS_CHECK_LEVEL.
-q No muestra informes y nunca genera un diff entre el fichero
symbols generado y el fichero de plantilla tomado como base, ni
muestra ningn aviso relativo a bibliotecas nuevas o ausentes, o
smbolos nuevos o ausentes. Esta opcin solo desactiva la salida
informativa, pero no las comprobaciones (consulte la opcin -c).
-aarquitectura
Toma arquitectura como la arquitectura anfitrin al procesar
ficheros symbols. Use esta opcin para generar un fichero symbols
o un diff para cualquier arquitectura, siempre y cuando sus
binarios ya estn disponibles.
-d Activa el modo de depuracin. Se muestran numerosos mensajes que
explican las acciones de dpkg-gensymbols.
-V Activa el modo verboso. El fichero symbols generado contiene
smbolos obsoletos en la forma de comentarios. Adems, en modo
plantilla los patrones de smbolo anteceden a los comentarios que
listan los smbolos reales que coinciden con el patrn.
-h, --help
Muestra el modo de uso y termina.
--version
Muestra la versin y termina.
VASE TAMBIN
http://people.redhat.com/drepper/symbol-versioning
http://people.redhat.com/drepper/goodpractice.pdf
http://people.redhat.com/drepper/dsohowto.pdf
deb-symbols(5), dpkg-shlibdeps(1).
AUTORES
Copyright (C) 2007-2009 Raphael Hertzog
Esto es software libre; vea la versin 2 o posterior de la Licencia
Pblica General GNU para condiciones de copia. NO hay ninguna garanta.
TRADUCTOR
Rudy Godoy <rudy@kernel-panik.org>, Rubn Porras <nahoo@inicia.es>,
Bruno Barrera C. <bruno.barrera@igloo.cl>, Carlos Izquierdo
<gheesh@ertis.net>, Esteban Manchado y NOK. Debian L10n Spanish
<debian-l10n-spanish@lists.debian.org>.
Revisiones por Santiago Vila <sanvila@unex.es>, Javier
Fernndez-Sanguino, Rubn Porras, Luis Uribe y Omar Campagne.