table of contents
dpkg-gensymbols(1) | Herramientas de dpkg | dpkg-gensymbols(1) |
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
MANTENER FICHEROS «SYMBOLS»¶
Los ficheros «symbols» son realmente útiles sólo cuando reflejan la evolución del paquete a lo largo de varias publicaciones. Por ello, el desarrollador tiene que actualizarlos cada vez que se añada un símbolo nuevo, para que así la mínima versión asociada concuerde con la realidad. Para hacer esto apropiadamente puede utilizar los «diff» contenidos en los registros de construcción. En la mayoría 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 número de revisión de Debian de la versión mínima para que así aquellas adaptaciones hacia atrás («backports») con un número de versión menor, pero con la misma versión que la fuente original, puedan satisfacer las dependencias generadas. Si no se puede eliminar la revisión de Debian porque el símbolo se añadió debido a un cambio específico de Debian puede afijar «~» a la versión. 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. Debido a que las etiquetas de símbolos son una extensión del formato deb-symbols(5) sólo pueden formar parte de los ficheros «symbols» de paquetes fuente (estos ficheros deberían aparecer como plantillas usadas para generar los ficheros «symbols» integrados en paquetes binarios). Cuando ejecuta dpkg-gensymbols con la opción -t, enviará por la salida ficheros «symbols» compatibles con el formato deb-symbols(5): procesa completamente los símbolos de acuerdo a los requerimientos de sus etiquetas estándar, y elimina todas las etiquetas de la salida. Por otra parte, en el modo plantilla ( -t), todos los símbolos y etiquetas (estándar y desconocidos) se muestran por la salida, y se escriben en su forma original a medida que se cargan.
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.
- 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.
(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.- 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.
[...]
(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.
(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
(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.
(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:
- •
- Al igual que con cualquier símbolo, puede etiquetar la
directiva «include»:
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
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).
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
- Sólo analiza las bibliotecas listadas explícitamente, en lugar de buscar todas las bibliotecas públicas. Puede utilizar patrones de intérprete de órdenes regular utilizadas para la expansión de nombre de ruta (para más detalles consulte la página de manual «File::Glob») 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 estándar el fichero «symbols» generado, en lugar de almacenarlo en el árbol de construcción del paquete.
- -Ofichero
- Guarda el fichero de símbolos generado como fichero. Si el fichero ya existe su contenido se usará como base para el fichero «symbols» generado. Puede utilizar esta característica para actualizar un fichero «symbols» para que coincida con una versión más 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 más notable es que en modo plantilla los nombres de símbolo y etiquetas se escriben en su forma original, en lugar de los nombres de símbolo post-procesados con las etiquetas eliminadas en modo compatible. Además, puede que se omitan algunos símbolos al escribir un fichero estándar de deb-symbols(5) (de acuerdo a las reglas de procesamiento de etiquetas), mientras que siempre se insertan todos los símbolos 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 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.
- -q
- No muestra informes y nunca genera un «diff» entre el fichero «symbols» generado y el fichero de plantilla tomado como base, ni muestra ningún aviso relativo a bibliotecas nuevas o ausentes, o símbolos nuevos o ausentes. Esta opción solo desactiva la salida informativa, pero no las comprobaciones (consulte la opción -c).
- -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¶
http://people.redhat.com/drepper/symbol-versioningTRADUCTOR¶
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>.22 de abril del 2012 | Proyecto Debian |