Provided by: dpkg-dev_1.17.5ubuntu5.8_all 
NOMBRE
dpkg-gensymbols - Generación de ficheros «symbols» (información de dependencia de
bibliotecas compartidas)
SINOPSIS
dpkg-gensymbols [opción...]
DESCRIPCIÓN
dpkg-gensymbols analiza un árbol temporal de construcción («debian/tmp» por omisión) en
busca de bibliotecas para generar un fichero symbols que los describa. Este fichero, si no
está vacío, se instala en el subdirectorio «DEBIAN» del árbol de construcción, para
después incluir el contenido en la información de control del paquete.
Al generar estos ficheros, usa algunos ficheros «symbols» como entrada proporcionados por
el desarrollador. Busca los siguientes ficheros, utilizando el primero que encuentra.
• debian/package.symbols.arch
• debian/symbols.arch
• debian/package.symbols
• debian/symbols
The main interest of those files is to provide the minimal version associated to each
symbol provided by the libraries. Usually it corresponds to the first version of that
package that provided the symbol, but it can be manually incremented by the maintainer if
the ABI of the symbol is extended without breaking backwards compatibility. It's the
responsibility of the maintainer to keep those files up-to-date and accurate, but
dpkg-gensymbols helps with that.
Cuando los ficheros «symbols» generados difieren del proporcionado por el desarrollador,
dpkg-gensymbols mostrará las diferencias entre ambas versiones. Más aún, puede que falle
si la diferencia es demasiado grande, (puede configurar cuanta diferencia tolerar,
consulte la opción -c).
MANTENER FICHEROS «SYMBOLS»
The symbols files are really useful only if they reflect the evolution of the package
through several releases. Thus the maintainer has to update them every time that a new
symbol is added so that its associated minimal version matches reality. To do this
properly the diffs contained in the build logs can be used. In most cases, the diff
applies directly to the debian/package.symbols file. That said, further tweaks are usually
needed: it's recommended for example to drop the Debian revision from the minimal version
so that backports with a lower version number but the same upstream version still satisfy
the generated dependencies. If the Debian revision can't be dropped because the symbol
really got added by the Debian specific change, then one should suffix the version with
"~".
Antes de aplicar un parche al fichero «symbols» el desarrollador debería revisar
nuevamente que es adecuado. Se espera que los símbolos públicos no desaparezcan así que,
idealmente, el parche sólo debería añadir líneas nuevas.
Tenga en cuenta que puede añadir comentarios en los ficheros de símbolos: cualquier línea
que comienza con el carácter «#» es un comentario, a menos que empiece con «#include»
(consulte la sección Usar «include». Las líneas que comienzan con «#MISSING:» son
comentarios especiales que documentan los símbolos que han desaparecido.
Usar la sustitución de #PACKAGE#
En algunos casos aislados el nombre de la biblioteca varía según la arquitectura. Puede
utilizar 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 instalación
de los ficheros «symbols». A diferencia del marcador #MINVER#, #PACKAGE# nunca aparecerá
en un fichero «symbols» contenido en un paquete binario.
Usar etiquetas de símbolos
El etiquetado de símbolos es útil para marcar aquellos símbolos que son de alguna manera
especiales. Cada símbolo puede tener un número arbitrario de etiquetas asociadas a éste.
Aunque se analizan y guardan todas las etiquetas, dpkg-gensymbols sólo entiende algunas de
ellas, e iniciará un tratamiento especial de los símbolos. Consulte la sub-sección
Etiquetas estándar de símbolos para una referencia de estas etiquetas.
La especificación de la etiqueta aparece a continuación del nombre del símbolo (no se
permite un espacio vacío entre estos). Siempre comienza con un paréntesis de apertura (,
finaliza con un paréntesis de cierre ), y debe contener al menos una etiqueta. Varias
etiquetas se separan con un carácter |. Opcionalmente, cada etiqueta puede tener un valor
separado del nombre de la etiqueta mediante el carácter =. Los nombres de etiqueta y
valores pueden ser cadenas arbitrarias, a excepción de que no pueden contener ningún
carácter especial: ), | y =. Los nombres de símbolo a continuación de una especificación
de etiqueta se pueden entrecomillar con caracteres ' o ", permitiendo así espacios vacíos.
Por otra parte, de no existir ninguna etiqueta definida para el símbolo, las comillas se
tratarán como parte del nombre del símbolo, continuando hasta el primer espacio.
(tag1=tengo una marca|nombre de etiqueta con espacio)"símbolo
entrecomillado y etiquetado"@Base 1.0
(optional)símbolo_sin_comillas_y_etiquetado@Base 1.0 1
símbolo_sin_etiquetar@Base 1.0
El primer símbolo del ejemplo se llama símbolo 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 símbolo se llama símbolo_sin_comillas_y_etiquetado, y sólo tiene
una etiqueta llamada optional. El último símbolo es un ejemplo de un símbolo normal sin
etiquetar.
Since symbol tags are an extension of the deb-symbols(5) format, they can only be part of
the symbols files used in source packages (those files should then be seen as templates
used to build the symbols files that are embedded in binary packages). When
dpkg-gensymbols is called without the -t option, it will output symbols files compatible
to the deb-symbols(5) format: it fully processes symbols according to the requirements of
their standard tags and strips all tags from the output. On the contrary, in template mode
(-t) all symbols and their tags (both standard and unknown ones) are kept in the output
and are written in their original form as they were loaded.
Etiquetas de símbolo estándar
optional
Un símbolo marcado como opcional puede desaparecer de la biblioteca en cualquier
momento sin causar un fallo de dpkg-gensymbols. Por otra parte, los símbolos
opcionales desaparecidos aparecerán continuamente como «MISSING» (ausente) en el
«diff» de cada nueva revisión del paquete. Este comportamiento sirve como un
recordatorio para el desarrollador para informar de la necesidad de eliminar tal
símbolo del fichero «symbols», o de añadir éste nuevamente a la biblioteca. Cuando
el símbolo opcional declarado previamente como «MISSING» reaparece de súbito en la
siguiente revisión, se actualizara a un estado «existente» sin modificar la versión
mínima.
Esta etiqueta es útil para aquellos símbolos privados cuya desaparición no rompe la
ABI. Por ejemplo, la mayoría de plantillas de producción de un objeto definido más
específicamente por medio del reemplazo de ciertas variables por valores
(«instantiation») de C++ se encuentran dentro de esta categoría. Al igual que con
cualquier otra etiqueta, éste puede tener un valor arbitrario: se puede utilizar
para indicar porqué el símbolo se considera opcional.
arch=lista-de-arquitecturas
Esta etiqueta permite limitar el conjunto de arquitecturas dónde se supone que el
símbolo existe. Cuando la lista de símbolos se actualiza con los símbolos
descubiertos en la biblioteca, todos los símbolos específicos de la arquitectura
que no son relevantes para la arquitectura anfitrión se toman como no existentes.
Si un símbolo específico a la arquitectura que concuerda con la arquitectura
anfitrión presente no existe en la biblioteca, se aplicarán los procedimientos
normales para símbolos desaparecidos, llevando a que dpkg-gensymbols falle. Por
otra parte, si el símbolo específico a la arquitectura se encuentra cuando se
suponía que no existe (porque la arquitectura anfitrión presente no está listada en
la etiqueta), pasa a ser neutral a la arquitectura (por ejemplo, se elimina la
etiqueta de arquitectura, apareciendo el símbolo en el «diff» debido a la
modificación), pero no se toma como un nuevo símbolo.
Al operar en el modo por omisión (sin plantilla) sólo se escribirán al fichero
«symbols» aquellos símbolos específicos a la arquitectura que coinciden con la
arquitectura anfitrión. Por otra parte, en el modo plantilla todos los símbolos
específicos a la arquitectura (incluyendo arquitecturas alternativas) siempre se
escribirán al fichero «symbols».
The format of architecture list is the same as the one used in the Build-Depends
field of debian/control (except the enclosing square brackets []). For example, the
first symbol from the list below will be considered only on alpha, any-amd64 and
ia64 architectures, the second only on linux architectures, while the third one
anywhere except on armel.
(arch=alpha any-amd64 ia64)a_64bit_símbolo_específico@Base 1.0
(arch=linux-any)símbolo_específico_linux@Base 1.0
(arch=!armel)símbolo_ausente_en_armel@Base 1.0
ignore-blacklist
dpkg-gensymbols tiene una lista negra interna de símbolos que no deberían aparecer
en los ficheros «symbols», ya que habitualmente son sólo efectos secundarios de los
detallas de implementación de la cadena de herramientas. Si por alguna razón desea
incluir uno de esos símbolos en el fichero «symbols» debería etiquetar el símbolo
con ignore-blacklist. Puede ser necesario con alguna cadena de herramientas de bajo
nivel como libgcc.
c++ Denota el patrón c++- Consulte la subsección a continuación Usar patrones de
símbolos.
symver Denota el patrón de símbolos symver (versión del símbolo). Consulte la sub-sección
a continuación Usar patrones de símbolos.
regex Denota el patrón de símbolos regex (expresión regular). Consulte la sub-sección a
continuación Usar patrones de símbolos.
Usar patrones de símbolos
A diferencia de cualquier definición de símbolo estándar un patrón puede cubrir varios
símbolos reales de la biblioteca. dpkg-gensymbols intentará emparejar cada patrón con cada
símbolo real que no tiene un símbolo específico de contrapartida definido en el fichero de
símbolos. En el momento que se encuentre el primer patrón que coincida se usarán todas sus
etiquetas y propiedades como un definición básica del símbolo. Si ninguno de los patrones
encaja, el símbolo se considerará nuevo.
A pattern is considered lost if it does not match any symbol in the library. By default
this will trigger a dpkg-gensymbols failure under -c1 or higher level. However, if the
failure is undesired, the pattern may be marked with the optional tag. Then if the pattern
does not match anything, it will only appear in the diff as MISSING. Moreover, like any
symbol, the pattern may be limited to the specific architectures with the arch tag. Please
refer to Standard symbol tags subsection above for more information.
Patterns are an extension of the deb-symbols(5) format hence they are only valid in symbol
file templates. Pattern specification syntax is not any different from the one of a
specific symbol. However, symbol name part of the specification serves as an expression to
be matched against name@version of the real symbol. In order to distinguish among
different pattern types, a pattern will typically be tagged with a special tag.
A día de hoy, dpkg-gensymbols es compatible con tres tipos de patrones básicos:
c++
Este patrón se indica con la etiqueta c++. Sólo encaja con el nombre «demangled» de
símbolos C++ (tal y como muestra la herramienta c++filt(1)). Este patrón es de utilidad
para emparejar símbolos con nombres «mangled» que pueden variar según la arquitectura,
mientras que sus nombres «demangled» permanecen sin cambios. Un grupo de estos símbolos
son los thunk no virtuales, que tienen direcciones relativas («offsets») específicas a
la arquitectura integradas en sus nombres «mangled». Un ejemplo común de este caso es
un destructor virtual, que bajo una herencia de diamante necesita un símbolo 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 patrón 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 definición único en la biblioteca, no es
necesariamente cierto para nombres «demangled». Puede que dos símbolos reales y
distintos tengan el mismo nombre «demangled». Por ejemplo, en caso de existir símbolos
thunk no virtuales en complejas configuraciones de herencia, o con la mayoría de
constructores y destructores (ya que habitualmente g++ genera dos símbolos para ellos).
Por otra parte, estas colisiones aparecen al nivel de la ABI, y por ello no deberían
degradar la calidad del fichero de símbolos.
symver
La etiqueta symver indica este patrón. Las bibliotecas bien mantenidas tienen símbolos
con versión, donde cada versión corresponde con la versión del autor original en la que
se añadió el símbolo. De ser así, puede utilizar un patrón symver para emparejar el
símbolo asociado con una versión 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 símbolos asociados con las versiones «GLIBC_2.0» y «GLIBC_2.7» llevan a una
versión mínima de 2.0 y 2.7 respectivamente, con la excepción del símbolo
«access@GLIBC_2.0». El segundo lleva a una dependencia mínima sobre la versión 2.2 de
libc6, a pesar de estar en el rango del patrón «(symver)GLIBC_2.0», debido a que los
símbolos específicos tiene precedencia sobre los patrones.
Tenga en cuanta que los patrones de comodín antiguos (indicados por «*@versio» en el
campo del nombre del símbolo) son aún compatibles, aunque han quedado obsoletos por el
nuevo estilo de sintaxis «(symver|optional)versión». Por ejemplo, debería 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 expresión regular de perl definido en el campo de nombre del
símbolo. Una expresión 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
símbolo nombre@versión. Por ejemplo:
libdummy.so.1 libdummy1 #MINVER#
(regex)"^mystack_.*@Base$" 1.0
(regex|optional)"private" 1.0
Los símbolos como «mystack_new@Base», «mystack_push@Base», «mystack_pop@Base» y
similares encajarían con el primer patrón, mientras que otros como
«ng_mystack_new@Base» no lo harían. El segundo patrón encaja con todos los símbolos con
«private» en su nombre, y las coincidencias heredarán de este patrón 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 patrón se «demangle»
el símbolo sin procesar como símbolo C++, para después comparar el nombre «demangled» con
la expresión regular. Por otra parte, al comparar el segundo patrón la expresión regular
se compara con el nombre sin procesar del símbolo, para después confirmar si es un símbolo
de C++ mediante «demangle». Un fallo de un patrón básico lleva a un fallo de todo el
patrón. Por ejemplo, «__N3NSA6ClassA7Private11privmethod\dEi@Base» no encajaría con ningún
patrón porque no es un símbolo válido de C++.
En general, todos los patrones se dividen en dos grupos: aliases (los básicos c++ y
symver) y patrones genéricos (regex, todas las combinaciones de varios patrones básicos).
Establecer coincidencias con patrones basados en alias es rápido (0(1)) mientras que los
patrones genéricos son 0(N) (N - cuenta genérica del patrón) para cada símbolo. Debido a
ello, se recomienda no abusar de los patrones genéricos.
Los alias (primero c++, después symver) tienen prioridad sobre los patrones genéricos.
Éstos se emparejan por orden de aparición en la plantilla del fichero de símbolos hasta el
primer resultado de éxito. Tenga en cuenta, no obstante, que no se recomienda la
reorganización manual de las entradas en plantillas de fichero ya que dpkg-gensymbols
genera «diffs» basados en el orden alfanumérico de sus nombres.
Usar «include»
Hay casos en los que utilizar un sólo fichero de símbolos es contraproducente cuando el
conjunto de símbolos exportados difiere según la arquitectura. En estos casos, una
directiva «include» puede ser útil de un par de maneras:
• Puede factorizar la parte común en algún fichero externo, e incluir ese fichero en su
fichero paquete.symbols.arq usando una directiva «include» como esta:
#include "packages.symbols.common"
• Al igual que con cualquier símbolo, puede etiquetar la directiva «include»:
(etiqueta|...|etiquetaN)#include "fichero-para-include"
Como resultado, se considerará que todos los símbolos incluidos en
fichero-para-include están etiquetados con etiqueta ... etiquetaN por omisión. Puede
utilizar esta característica para crear un fichero común package.symbols, que incluye
ficheros de símbolos específicos 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 símbolos se leen línea a línea, y las directivas «include» se procesan por
orden de aparición. Esto significa que el contenido del fichero incluido puede sustituir
cualquier contenido aparecido antes de la directiva «include», y que todo contenido a
continuación de la directiva puede sustituir cualquier contenido del fichero incluido.
Todo símbolo (o incluso otra directiva «#include») en el fichero incluido puede
especificar etiquetas adicionales, o sustituir valores de las etiquetas heredadas en la
especificación de etiqueta. Por otra parte, el símbolo no puede eliminar ninguna de las
etiquetas heredadas.
Un fichero incluido puede repetir la línea de cabecera que contiene el «SONAME» de la
biblioteca. En tal caso, sustituye cualquier línea de cabecera leída anteriormente. Por
otra parte, generalmente es mejor evitar duplicar las líneas de cabecera. A continuación
puede ver una manera de realizar esto:
#include "libsomething1.symbols.common"
arch_specific_symbol@Base 1.0
Buena gestión de bibliotecas
Una biblioteca mantenida adecuadamente tiene las siguientes características:
• su API es estable (los símbolos públicos nunca se eliminan, sino que sólo se añaden
símbolos nuevos), y los cambios pueden introducir una incompatibilidad sólo cuando el
«SONAME» cambia;
• Idealmente, usa el versionado de símbolos para alcanzar la estabilidad de la ABI, a
pesar de cambios internos y la extensión de la API;
• No exporta símbolos privados (tales como símbolos etiquetados como opcionales para
evitar un problema).
Al mantener un fichero «symbols» es sencillo notar la aparición y desaparición de
símbolos. Pero es más difícil notar cambios incompatibles en las API y ABI. Por ello, el
responsable del paquete debería leer cuidadosamente el registro de cambios de la fuente
original en busca de casos en los que se ha roto la correcta gestión de bibliotecas. Se
debería 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 específico
de Debian.
OPCIONES
-Pdirectorio-compilación-paquete
Analiza directorio-compilación-paquete en lugar de «debian/tmp».
-ppaquete
Define el nombre del paquete. Es necesario si aparece más de un paquete binario en
«debian/control» (o si no existe ningún fichero «debian/control»).
-vversión
Define la versión del paquete. El valor por omisión es la versión extraída de
«debian/changelog». Necesario en caso de una ejecución externa al árbol del paquete
fuente.
-efichero-biblioteca
Only analyze libraries explicitly listed instead of finding all public libraries.
You can use shell patterns used for pathname expansions (see the File::Glob(3perl)
manual page for details) in library-file to match multiple libraries with a single
argument (otherwise you need multiple -e).
-Inombre-fichero
Usa nombre-fichero como un fichero de referencia para generar el fichero «symbols»
integrado en el mismo paquete.
-O[filename]
Print the generated symbols file to standard output or to filename if specified,
rather than to debian/tmp/DEBIAN/symbols (or package-build-dir/DEBIAN/symbols if -P
was used). If filename is pre-existing, its contents are used as basis for the
generated symbols file. You can use this feature to update a symbols file so that
it matches a newer upstream version of your library.
-t Write the symbol file in template mode rather than the format compatible with
deb-symbols(5). The main difference is that in the template mode symbol names and
tags are written in their original form contrary to the post-processed symbol names
with tags stripped in the compatibility mode. Moreover, some symbols might be
omitted when writing a standard deb-symbols(5) file (according to the tag
processing rules) while all symbols are always written to the symbol file template.
-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 más comprobaciones, así como la inclusión de todos los niveles
inferiores. El nivel 0 nunca falla. El nivel 1 falla si algunos símbolos han
desaparecido. El nivel 2 falla si se han introducido símbolos nuevos. El nivel 3
falla si han desaparecido algunas bibliotecas. El nivel 4 falla si se han
introducido bibliotecas nuevas.
This value can be overridden by the environment variable
DPKG_GENSYMBOLS_CHECK_LEVEL.
-q Keep quiet and never generate a diff between generated symbols file and the
template file used as starting point or show any warnings about new/lost libraries
or new/lost symbols. This option only disables informational output but not the
checks themselves (see -c option).
-aarquitectura
Toma arquitectura como la arquitectura anfitrión al procesar ficheros «symbols».
Use esta opción para generar un fichero «symbols» o un «diff» para cualquier
arquitectura, siempre y cuando sus binarios ya estén disponibles.
-d Activa el modo de depuración. Se muestran numerosos mensajes que explican las
acciones de dpkg-gensymbols.
-V Activa el modo verboso. El fichero «symbols» generado contiene símbolos obsoletos
en la forma de comentarios. Además, en modo plantilla los patrones de símbolo
anteceden a los comentarios que listan los símbolos reales que coinciden con el
patrón.
-?, --help
Muestra el modo de uso y termina.
--version
Muestra la versión y termina.
VÉASE TAMBIÉN
https://people.redhat.com/drepper/symbol-versioning
https://people.redhat.com/drepper/goodpractice.pdf
https://people.redhat.com/drepper/dsohowto.pdf
deb-symbols(5), dpkg-shlibdeps(1).
TRADUCTOR
Rudy Godoy <rudy@kernel-panik.org>, Rubén 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 Fernández-Sanguino, Rubén Porras,
Luis Uribe y Omar Campagne.