Utilisation du remplacement de #PACKAGE#¶

Utilisation des étiquettes de symbole¶

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.

Comme les étiquettes de symbole sont une extension du format de deb-symbols(5), elles ne peuvent apparaître que dans les fichiers de symboles des paquets source (ces fichiers peuvent ensuite être vus comme des modèles permettant de construire les fichiers de symboles inclus dans les paquets binaires). Lorsque dpkg-gensymbols est lancé sans l'option -t, il affiche les fichiers de symboles compatibles avec le format deb-symbols(5) : il traite entièrement les symboles d'après les exigences des étiquettes standard et supprime les étiquettes dans sa sortie. Au contraire, dans le mode modèle (« template », option -t), tous les symboles et leurs étiquettes (standard et inconnues) sont conservés dans la sortie et écrits dans leur forme d'origine.

É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 behaviour 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=architecture-list

arch-bits=architecture-bits

arch-endian=architecture-endianness

These tags allow one to restrict the set of architectures where the symbol is supposed to exist. The arch-bits and arch-endian tags are supported since dpkg 1.18.0. When the symbols list is updated with the symbols discovered in the library, all arch-specific symbols which do not concern the current host architecture are treated as if they did not exist. If an arch-specific symbol matching the current host architecture does not exist in the library, normal procedures for missing symbols apply and it may cause dpkg-gensymbols to fail. On the other hand, if the arch-specific symbol is found when it was not supposed to exist (because the current host architecture is not listed in the tag or does not match the endianness and bits), it is made arch neutral (i.e. the arch, arch-bits and arch-endian tags are dropped and the symbol will appear in the diff due to this change), but it is not considered as new.

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

The architecture-bits is either 32 or 64.

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

The architecture-endianness is either little or big.

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

Multiple restrictions can be chained.

(arch-bits=32|arch-endian=little)32bit_le_symbol@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 motifs de symbole plus loin.

symver

Indique un motif de symbole symver (version de symbole). Voir la sous-section Utilisation des motifs de symboles plus loin.

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¶

Un motif est considéré comme perdu si aucun symbole ne lui correspond dans la bibliothèque. Par défaut, cela provoquera un échec de dpkg-gensymbols s'il est utilisé avec l'option -c1 (ou une valeur plus élevée). Cependant, si l'échec n'est pas souhaité, le motif peut être marqué comme optionnel avec l'étiquette optional. Dans ce cas, si le motif ne correspond à rien, il sera simplement mentionné dans le fichier de différences comme MISSING (manquant). De plus, comme pour tout autre symbole, le motif peut être limité à des architectures données avec l'étiquette arch. Veuillez consulter la sous-section Étiquettes standard de symbole pour plus d'informations.

Les motifs sont une extension du format de deb-symbols(5) en ce sens qu'ils ne sont valables que dans les modèles de fichiers de symboles. Cependant, la partie comportant le nom de symbole est utilisée comme une expression à faire correspondre à name@version du symbole réel. Afin de faire la distinction entre les différents types de motifs, un motif sera usuellement marqué avec une étiquette spéciale.

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 complets 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 32 bits est identique à _ZThn16_N3NSB6ClassDD1Ev@Base sur une architecture 64 bits, 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 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¶

• 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 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¶

• 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.