dpkg-gensymbols(1)

NOM
dpkg-gensymbols - création des fichiers de symboles (information destinée aux dépendances de bibliothèques partagées)

SYNOPSIS
dpkg-gensymbols [option...]

DESCRIPTION
dpkg-gensymbols analyse un répertoire temporaire de construction (par défaut debian/tmp), y recherche les bibliothèques et crée un fichier symbols qui les décrit. Si ce fichier n'est pas vide, il est installé dans le sous-répertoire DEBIAN du répertoire de construction afin de pouvoir être inclus dans les informations de contrôle du paquet.

Lors de la création de ces fichiers, il utilise en entrée certains fichiers de symboles fournis par le responsable. Il recherche les fichiers suivants (en utilisant le premier trouvé) :

•   debian/paquet.symbols.arch

•   debian/symbols.arch

•   debian/paquet.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.

Quand les fichiers de symboles créés sont différents de ceux fournis par le responsable, dpkg-gensymbols affichera les différences entre les deux fichiers. Si ces différences sont trop importantes, le programme peut même se terminer en échec (le nombre de différences tolérées peut être réglé avec l'option -c).

TENUE À JOUR DES FICHIERS SYMBOLES
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 "~".

Avant d'appliquer le correctif au fichier de symboles, le responsable doit contrôler qu'il est correct. Les symboles publics sont supposés ne jamais disparaître et le correctif ne devrait donc qu'ajouter des lignes.

Veuillez noter qu'il est possible de placer des commentaires dans les fichiers de symboles : toute ligne commençant par « # » est un commentaire sauf si elle commence par « #include » (voir la section utilisation des inclusions). Les lignes commençant par « #MISSING: » sont des commentaires spéciaux qui indiquent les symboles qui peuvent avoir disparu.

  Utilisation du remplacement de #PACKAGE#

Dans de rares cas, le nom de la bibliothèque dépend de l'architecture. Afin d'éviter de coder le nom du paquet en dur dans le fichier de symboles, il est possible d'utiliser le marqueur #PACKAGE#. Il sera remplacé par le vrai nom du paquet lors de l'installation des fichiers de symboles. À la différence du marqueur #MINVER#, #PACKAGE# n'apparaîtra jamais dans le fichier de symboles d'un paquet binaire.

  Utilisation des étiquettes de symboles

L'étiquetage des symboles (« symbol tagging ») est utile pour marquer des symboles qui sont particuliers d'une manière ou d'une autre. Tout symbole peut avoir un nombre quelconque d'étiquettes associées. Bien que toutes les étiquettes soient analysées et conservées, seules certaines d'entre elles sont comprises par dpkg-gensymbols et déclenchent un traitement spécifique des symboles. Veuillez consulter la sous-section Étiquettes standard de symboles pour une référence complète à propos de ces étiquettes.

L'indication de l'étiquette vient juste avant le nom du symbole (sans espace). Elle commence toujours par une parenthèse ouvrante (, se termine avec une parenthèse fermante ) et doit contenir au moins une étiquette. Les étiquettes multiples doivent être séparées par le caractère |. Chaque étiquette peut comporter optionnellement une valeur, séparée du nom de l'étiquette par le caractère =. Les noms et valeurs des étiquettes sont des chaînes quelconques qui ne doivent pas comporter les caractères ) | et =. Les noms de symboles qui suivent une étiquette peuvent optionnellement être mis entre guillemets avec les caractères ' ou " afin d'y autoriser la présence d'espaces. Cependant, si aucune étiquette n'est utilisée, les guillemets sont alors traités comme une partie du nom du symbole, qui s'arrête alors au premier espace.

 (étiq1=je suis marqué|étiquette avec espace)"symbole comportant des espaces"@Base 1.0
 (optional)symbole_non_protégé@Base 1.0 1
 symbole_non_étiqueté@Base 1.0

Le premier symbole de cet exemple est appelé symbole comportant des espaces et utilise deux étiquettes : étiq1 avec la valeur je suis marqué et étiquette avec espace sans valeur. Le deuxième symbole, appelé symbole_non_protégé ne comporte que l'étiquette optional. Le dernier symbole est un exemple de symbole normal sans étiquette.

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.

  Étiquettes standard de symboles

optional
    Un symbole marqué comme optionnel peut disparaître de la bibliothèque à tout moment et ne provoquera pas l'échec de dpkg-gensymbols. Cependant, les symboles optionnels disparus apparaîtront en permanence comme manquants dans le fichier de différences, à chaque nouvelle version du paquet. Ce comportement sert de rappel au responsable qu'un tel symbole doit être supprimé du fichier de symboles ou bien réajouté à la bibliothèque. Un tel symbole optionnel, précédemment déclaré comme manquant (« MISSING »), peut réapparaître soudainement dans la version suivante en étant remis à l'état existant (« existing »), sans modification de sa version minimale. Cette étiquette est utile pour les symboles qui sont privés car leur disparition ne provoque pas de changement d'interface applicative (ABI). Par exemple, la plupart des modèles d'instantiation C++ sont dans cette catégorie. Comme toute autre étiquette, celle-ci peut comproter une valeur arbitraire qui peut servir à indiquer pour quelle raison le symbole est optionnel.

arch=liste d'architectures
    Cette étiquette permet de restreindre la liste des architectures avec lesquelles le symbole est censé exister. Lorsque la liste des symboles est mise à jour avec ceux découverts dans la bibliothèque, tous les symboles spécifiques d'architectures qui ne concernent pas l'architecture en cours sont ignorés. Si un symbole propre à l'architecture en cours n'existe pas dans la bibliothèque, les processus normaux pour des symboles manquants s'appliquent jusqu'à éventuellement provoquer l'échec de dpkg-gensymbols. D'un autre côté, si le symbole propre à une architecture est trouvé alors qu'il n'est pas censé exister (parce que l'architecture courante n'est pas mentionnée dans l'étiquette), il est rendu indépendant de l'architecture (l'étiquette d'architecture est abandonnée et le symbole apparaît dans le fichier de différences) mais non considéré comme nouveau. (NdT : une aspirine peut être nécessaire après la lecture de ce paragraphe) Dans le mode de fonctionnement par défaut (pas en mode « modèle »), seuls les symboles spécifiques de certaines architectures qui correspondent à l'architecture courante sont écrits dans le fichier de symboles. Au contraire, tous les symboles spécifiques d'architectures (y compris ceux des architectures différentes) seront écrits dans le fichier de symboles, dans le mode « modèle ». 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)un_symbole_spécifique_64bit@Base 1.0
     (arch=linux-any)un_symbole_spécifique_linux@Base 1.0
     (arch=!armel)un_symbole_inexistant_sur_armel@Base 1.0

ignore-blacklist
    dpkg-gensymbols comporte une liste interne de symboles ignorés qui ne devraient pas apparaître dans les fichiers de symboles car ils sont en général uniquement des effets de bord de détails de mise en ?uvre de la chaîne d'outils de construction. Si, pour une raison précise, vous voulez vraiment inclure un de ces symboles dans le fichier, vous pouvez imposer qu'il soit ignoré, avec ignore-blacklist. Cela peut être utile pour certaines bibliothèques de bas niveau telles que libgcc.

c++ Indique un motif de symbole c++. Voir la sous-section Utilisation de canevas de symboles plus loin.

symver
    Indique un motif de symbole symver (version de symbole).

regex
    Indique un motif de symbole basé sur des expressions rationnelles. Voir la sous-section Utilisation des motifs de symboles plus loin.

  Utilisation des motifs de symboles

Au contraire d'une indication normale de symbole, un motif permet de couvrir des symboles multiples de la bibliothèque. dpkg-gensymbols essaie de faire correspondre chaque motif à chaque symbole qui n'est pas explicitement défini dans le fichier de symboles. Dès qu'un motif est trouvé qui corresponde au symbole, l'ensemble de ses étiquettes et propriétés sont utilisées comme spécification de base du symbole. Si aucun des motifs ne correspond, le symbole sera considéré comme nouveau. 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. Actuellement, dpkg-gensymbols gère trois types de base de motifs :

c++ Ce motif est repéré par l'étiquette c++. Il ne sera comparé qu'aux symboles C++ avec leur nom de symbole complet (demangled) tel qu'affiché avec l'utilitaire c++filt. Ce motif est très pratique pour faire correspondre les symboles dont les noms raccourcis (mangled) peuvent différer selon les architectures bien que leurs noms complet restent les mêmes. Un tel groupe de symboles sont les non-virtual thunks pour lesquels les décalages (offsets) spécifiques d'architectures sont inclus dans leur nom court. Une manifestation usuelle de ce cas est le destructeur virtuel qui, dans le contexte d'un « problème du diamant », a besoin d'un symbole de transition spécial (ou « thunk ») non virtuel. Par exemple, même si _ZThn8_N3NSB6ClassDD1Ev@Base sur une architecture 32bit est identique à _ZThn16_N3NSB6ClassDD1Ev@Base sur une architecture 64bit, les deux peuvent être indiqués avec le même motif c++ :

    libdummy.so.1 libdummy1 #MINVER#
     [...]
     (c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
     [...]

    Le nom complet ci-dessus peut être obtenu avec la commande suivante :

     $ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt

    Veuillez noter que, bien que le nom complet soit unique dans la bibliothèque par définition, cela n'est pas forcément vrai pour le nom raccourci. Deux symboles réels différents peuvent avoir le même nom raccourci. C'est par exemple le cas avec les symboles « thunk » non virtuels dans des configurations d'héritage complexes ou avec la plupart des constructeurs et destructeurs (puisque g++ crée usuellement deux symboles réels pour eux). Cependant, comme ces collisions se produisent au niveau de l'interface applicative binaire (ABI), elles ne devraient pas dégrader la qualité du fichier de symboles.

symver
    Ce motif est indiqué par l'étiquette symver. Les bibliothèques bien gérées utilisent des symboles versionnés où chaque version correspond à la version amont à laquelle le symbole a été ajouté. Si c'est le cas, il est possible d'utiliser un motif symver pour faire correspondre chaque symbole associé à la version spécifique. Par exemple :

    libc.so.6 libc6 #MINVER#
     (symver)GLIBC_2.0 2.0
     [...]
     (symver)GLIBC_2.7 2.7
     access@GLIBC_2.0 2.2

    Tous les symboles associés avec les versions GLIBC_2.0 et GLIBC_2.7 conduiront respectivement à des versions minimales de 2.0 et 2.7, à l'exception du symbole access@GLIBC_2.0. Ce dernier amène à une dépendance minimale sur la version 2.2 de libc6 bien qu'il soit dans le scope de « (symvar)GLIBC_2.0 ». Cela est dû au fait que les symboles spécifiques prennent le pas sur les motifs.

    Veuillez noter que les anciens motifs avec caractères génériques (indiqués sous la forme « *@version ») dans le champ de nom de symbole sont toujours gérés. La nouvelle syntaxe « (symver|optional)version » doit toutefois leur être préférée. Par exemple, « *@GLIBC_2.0 2.0 » devrait être écrit sous la forme « (symver|optional)GLIBC_2.0 2.0 » si un comportement analogue est recherché.

regex
    Les motifs d'expressions rationnelles sont indiqués par l'étiquette regex. La correspondance se fait avec une expression rationnelle Perl sur le champ de nom de symbole. La correspondance est faite telle quelle et il ne faut donc pas oublier le caractère ^, sinon la correspondance est faite sur n'importe quelle partie du symbole réel name@version. Par exemple :

    libdummy.so.1 libdummy1 #MINVER#
     (regex)"^mystack_.*@Base$" 1.0
     (regex|optional)"private" 1.0

    Les symboles tels que « mystack_new@Base », « mystack_push@Base », « mystack_pop@Base », etc. seront en correspondance avec le premier motif alors que, par exemple, « ng_mystack_new@Base » ne le sera pas. Le deuxième motif correspondra pour tous les symboles qui comportent la chaîne « private » dans leur nom et les correspondances hériteront de l'étiquette optional depuis le motif.

Les motifs de base indiqués précédemment peuvent être combinés au besoin. Dans ce cas, ils sont traités dans l'ordre où les étiquettes sont indiquées. Par exemple, les deux motifs

 (c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
 (regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0

Seront en correspondance avec les symboles « _ZN3NSA6ClassA7Private11privmethod1Ei@Base" » et « _ZN3NSA6ClassA7Private11privmethod2Ei@Base ». Lors de la correspondance avec le premier motif, le symbole complet est d'abord décodé en tant que symbole C++, puis comparé à l'expression rationnelle. D'un autre côté, lors de la correspondance avec le deuxième motif, l'expression rationnelle est comparée au nom de symbole brut, puis le symbole est testé en tant que symbole C++ en tentant de le décoder. L'échec de n'importe quel motif de base provoquera l'échec de l'ensemble du motif. Ainsi, par exemple, « __N3NSA6ClassA7Private11privmethod\dEi@Base » ne correspondra à aucun des motifs car ce n'est pas un symbole C++ valable (NdT : j'ai l'impression de traduire du Klingon !).

En général, les motifs sont divisés en deux groupes : les alias (c++ et symver de base) et les motifs génériques (regex et toutes les combinaisons de motifs de base multiples). La correspondance de motifs basés sur des alias est rapide (O(1)) alors que les motifs génériques sont O(N) (N étant le nombre de motifs génériques) pour chaque symbole. En conséquence, il est déconseillé d'abuser des motifs génériques.

Lorsque plusieurs motifs correspondent pour le même symbole réel, les alias (d'abord c++, puis symver) sont privilégiés par rapport aux motifs génériques. Ceux-ci sont essayés dans l'ordre où ils apparaissent dans le modèle de fichier de symbole, en s'arrêtant à la première correspondance. Veuillez noter, cependant, que la modification manuelle de l'ordre des entrées de fichiers n'est pas recommandée car dpkg-gensymbols crée des fichiers de différences d'après l'ordre alphabético-numérique de leur nom.

  Utilisation des inclusions

Lorsqu'un jeu de symboles exportés varie selon les architectures, il est souvent peu efficace d'utiliser un seul fichier de symboles. Pour couvrir ces cas, une directive d'inclusion peut devenir utile dans certains cas.

•   Il est possible de factoriser la partie commune dans un fichier externe donné et l'inclure dans le fichier paquet.symbols.arch avec une directive « include » utilisée de la manière suivante : #include "paquets.symbols.common"

•   La directive d'inclusion peut également être étiquetée comme tout autre symbole : (étiquette|...|étiquetteN)#include "fichier_à_inclure" Le résultat sera que tous les symboles inclus depuis fichier_à_inclure seront considérés comme étiquetés par défaut avec etiq ... etiqN. Cela permet de créer un fichier paquet.symbols commun qui inclut les fichiers de symboles spécifiques des architectures :
      symbole_commun1@Base 1.0
     (arch=amd64 ia64 alpha)#include "package.symbols.64bit"
     (arch=!amd64 !ia64 !alpha)#include "package.symbols.32bit"
      symbole_commun2@Base 1.0

Les fichiers de symboles sont lus ligne par ligne et les directives d'inclusion sont traitées dès qu'elles sont trouvées. En conséquence, le contenu du fichier d'inclusion peut remplacer une définition qui précède l'inclusion et que ce qui suit l'inclusion peut remplacer une définition qu'elle ajoutait. Tout symbole (ou même une autre directive d'inclusion) dans le fichier inclus peut définir des étiquettes supplémentaires ou remplacer les valeurs d'étiquettes héritées, dans sa définition d'étiquettes. Cependant, pour un symbole donné, il n'existe pas de méthode permettant de remplacer une de ses étiquettes héritées.

Un fichier inclus peut reprendre la ligne d'en-tête qui contient le « SONAME » de la bibliothèque. Dans ce cas, cela remplace toute ligne d'en-tête précédente. Il est cependant déconseillé de dupliquer les lignes d'en-tête. Une façon de le faire est la méthode suivante :

#include "libmachin1.symbols.common"
 symboles_specifique_architecture@Base 1.0

  Bonnes pratiques de gestion des bibliothèques

Une bibliothèque bien maintenue offre les possibilités suivantes :

•   son interface de programmation (API) est stable (les symboles publics ne sont jamais supprimés et les changements ne concernent que des ajouts de nouveaux symboles publics) et les modifications provoquant une incompatibilité doivent être combinés avec un changement de SONAME ;

•   idéalement, elle utilise le versionnement des symboles pour garantir la stabilité de l'interface applicative binaire (ABI) malgré ses modifications internes et l'extension de son API ;

•   elle n'exporte pas les symboles privés (afin de contourner cela, de tels symboles peuvent être étiquetés comme optionnels)

En maintenant le fichier de symboles, il est facile d'en voir apparaître et disparaître. Cependant, il est plus difficile de contrôler la présence d'éventuelles modifications d'API ou ABI. En conséquence, le responsable doit contrôler soigneusement le journal des modifications amont, à la recherche de cas où une saine gestion des bibliothèques peut avoir été omise. Si des problèmes potentiels sont découverts, l'auteur amont doit être averti(e) car une correction en amont est meilleure qu'un travail spécifique au paquet Debian.

OPTIONS

-Prépertoire-construction-paquet
    Analyse de répertoire-construction-paquet, plutôt que debian/tmp.

-ppaquet
    Définit le nom du paquet. Requis si plus d'un paquet binaire est indiqué dans debian/control (ou s'il n'y a pas de fichier debian/control).

-vversion
    Définit la version du paquet. La valeur par défaut est la version extraite de debian/changelog. Ce paramètre est requis si le programme est lancé en dehors de l'arborescence source d'un paquet.

-efichier-bibliothèque
    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).

-Inom-de-fichier
    Utilise nom-de-fichier comme fichier de référence pour créer le fichier de symboles à intégrer dans le paquet lui-même.

-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]
    Définit les contrôles à effectuer lors de la comparaison des symboles créés en utilisant le fichier de modèle comme point de départ. Le niveau par défaut est 1. Plus le niveau est augmenté, plus le nombre de contrôles effectués est important. Chaque niveau de contrôle comporte les contrôles effectués pour les niveaux inférieurs. Le niveau 0 n'échoue jamais. Le niveau 1 échoue si certains symboles ont disparu. Le niveau 2 échoue si de nouveaux symboles ont été ajoutés. Le niveau 3 échoue si certaines bibliothèques ont disparu. Le niveau 4 échoue si des bibliothèques ont été ajoutées. 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).

-aarch
    Définit arch comme architecture lors du traitement des fichiers de symboles. Cette option permet de créer un fichier de symboles ou un fichier de différences pour n'importe quelle architecture, à condition que les fichiers binaires correspondants soient déjà disponibles.

-d  Active le mode verbeux. De nombreux messages sont affichés pour expliquer ce que dpkg-gensymbols fait.

-V  Active le mode verbeux. Le fichier de symboles créé contiendra les symboles dépréciés sous forme de commentaires. De plus, en mode modèle, les motifs de symboles seront suivis de commentaires affichant les symboles réels qui correspondent au motif.

-?, --help
    Affiche un message d'aide puis quitte.

--version
    Affiche le numéro de version puis quitte.

VOIR AUSSI
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).

TRADUCTION
Ariel VARDI <ariel.vardi@freesbee.fr>, 2002. Philippe Batailler, 2006. Nicolas François, 2006. Veuillez signaler toute erreur à <debian-l10n-french@lists.debian.org>.