Provided by: dpkg-dev_1.22.6ubuntu6_all bug

NOM

       deb-src-symbols - Fichier de modèle des bibliothèques partagées étendues de Debian

SYNOPSIS

       debian/paquet.symbols.arch, debian/symbols.arch, debian/paquet.symbols, debian/symbols

DESCRIPTION

       Les modèles de fichiers de symboles sont fournis dans les paquets source de Debian et leur
       format est un sous-ensemble des fichiers de symboles fournis dans les paquets binaires,
       voir deb-symbols(5).

   Commentaires
       Comments are supported in template symbol files. Any line with ‘#’ as the first character
       is a comment except if it starts with ‘#include’ (see section "Using includes"). Lines
       starting with ‘#MISSING:’ are special comments documenting symbols that have disappeared.

   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 symbole
       Symbol tagging is useful for marking symbols that are special in some way. Any symbol can
       have an arbitrary number of tags associated with it. While all tags are parsed and stored,
       only some of them are understood by dpkg-gensymbols and trigger special handling of the
       symbols. See subsection "Standard symbol tags" for reference of these tags.

       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 symbole 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 symbole
       optional
           A symbol marked as optional can disappear from the library at any time and that will
           never cause dpkg-gensymbols to fail. However, disappeared optional symbols will
           continuously appear as MISSING in the diff in each new package revision. This behavior
           serves as a reminder for the maintainer that such a symbol needs to be removed from
           the symbol file or readded to the library. When the optional symbol, which was
           previously declared as MISSING, suddenly reappears in the next revision, it will be
           upgraded back to the “existing” status with its minimum version unchanged.

           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'instanciation C++ sont dans cette catégorie. Comme toute autre étiquette,
           celle-ci peut comporter une valeur arbitraire qui peut servir à indiquer pour quelle
           raison le symbole est optionnel.

       arch=liste-d'architectures
       arch-bits=octets-architecture
       arch-endian=boutisme-d'architecture
           Ces étiquettes permettent de restreindre la liste des architectures avec lesquelles le
           symbole est censé exister. Les étiquettes arch-bits et arch-endian sont prises en
           charge depuis dpkg 1.18.0. 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 ou ne correspond pas au boutisme et aux octets), il est rendu
           indépendant de l'architecture (c'est-à-dire que les étiquettes d'architecture,
           d'octets de l'architecture et de boutisme d'architecture sont abandonnées 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 ».

           Le format de liste-d'architectures est le même que le format utilisé dans les champs
           Build-Depends des fichiers debian/control (à l'exception des crochets d'inclusion []).
           Par exemple, le premier symbole de la liste qui suit sera pris en compte sur les
           architectures alpha, n'importe quelle amd64 et ia64, le second uniquement sur les
           architectures linux et le troisième partout sauf sur 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

           Les octets-architecture sont soit 32 soit 64.

             (arch-bits=32)32bit_specific_symbol@Base 1.0
             (arch-bits=64)64bit_specific_symbol@Base 1.0

           Le boutisme-d'architecture est soit little soit big.

             (arch-endian=little)little_endian_specific_symbol@Base 1.0
             (arch-endian=big)big_endian_specific_symbol@Base 1.0

           Plusieurs restrictions peuvent être chaînées.

             (arch-bits=32|arch-endian=little)32bit_le_symbol@Base 1.0

       allow-internal
           dpkg-gensymbols comporte une liste de symboles internes 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
           (depuis dpkg 1.20.1). 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 allow-
           internal. Cela peut être utile pour certaines bibliothèques de bas niveau telles que
           libgcc.

       ignore-blacklist
           Un alias obsolète pour allow-internal (depuis dpkg 1.20.1, pris en charge depuis
           dpkg 1.15.3).

       c++ Denotes c++ symbol pattern. See "Using symbol patterns" subsection below.

       symver
           Denotes symver (symbol version) symbol pattern. See "Using symbol patterns" subsection
           below.

       regex
           Denotes regex symbol pattern. See "Using symbol patterns" subsection below.

   Utilisation de motifs de symbole
       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 correspond 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++ This pattern is denoted by the c++ tag. It matches only C++ symbols by their demangled
           symbol name (as emitted by c++filt(1) utility). This pattern is very handy for
           matching symbols which mangled names might vary across different architectures while
           their demangled names remain the same. One group of such symbols is non-virtual thunks
           which have architecture specific offsets embedded in their mangled names. A common
           instance of this case is a virtual destructor which under diamond inheritance needs a
           non-virtual thunk symbol. For example, even if _ZThn8_N3NSB6ClassDD1Ev@Base on 32-bit
           architectures will probably be _ZThn16_N3NSB6ClassDD1Ev@Base on 64-bit ones, it can be
           matched with a single c++ pattern:

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

           Le nom non décoré ci-dessus peut être obtenu avec la commande suivante :

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

           Veuillez noter que, bien que le nom décoré soit unique dans la bibliothèque par
           définition, cela n'est pas forcément vrai pour le nom non décoré. Deux symboles réels
           différents peuvent avoir le même nom non décoré. 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.

           Please note that while old style wildcard patterns (denoted by "*@version" in the
           symbol name field) are still supported, they have been deprecated by new style syntax
           "(symver|optional)version". For example, "*@GLIBC_2.0 2.0" should be written as
           "(symver|optional)GLIBC_2.0 2.0" if the same behavior is needed.

       regex
           Les motifs d'expressions rationnelles sont indiqués par l'étiquette expression-
           rationnelle. 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
           « 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 brut est d'abord rétabli d’origine 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 rétablir d’origine. L'échec de
       n'importe quel motif basique 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 basique) et
       les motifs génériques (expression-rationnelle et toutes les combinaisons de motifs
       basiques 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 symboles, 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 alphanumé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 "I<paquets>.symbols.common"
           =item *

           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 I<fichier_à_inclure> seront considérés comme étiquetés par défaut avec I<etiq> ... I<etiqN>. Cela permet de créer un fichier I<paquet>.symbols commun qui inclut les fichiers de symboles spécifiques des S<architectures :>

             common_symbol1@Base 1.0
            (arch=amd64 ia64 alpha)#include "package.symbols.64-bit"
            (arch=!amd64 !ia64 !alpha)#include "package.symbols.32-bit"
             common_symbol2@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 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

VOIR AUSSI

       deb-symbols(5), dpkg-shlibdeps(1), dpkg-gensymbols(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>.