Provided by: dpkg-dev_1.22.18ubuntu3_all 
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 ».
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 arm64, any-amd64 and riscv64 architectures, the second only on linux
architectures, while the third one anywhere except on armel.
(arch=arm64 any-amd64 riscv64)arch_specific_symbol@Base 1.0
(arch=linux-any)linux_specific_symbol@Base 1.0
(arch=!armel)symbol_armel_does_not_have@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 architectures :
common_symbol1@Base 1.0
(arch-bits=64)#include "package.symbols.64-bit"
(arch-bits=32)#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>.
1.22.18 2025-04-28 deb-src-symbols(5)