Manpages

NOM

dpkg-gensymbols - Création des fichiers de symboles (information de 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é) :

L’intérêt principal de ces fichiers est de fournir la version minimale associée à chaque symbole fourni par les bibliothèques. En général, cela correspond à la première version du paquet qui a fourni ce symbole, mais cette valeur peut être augmentée manuellement par le responsable si l’interface binaire applicative ( ABI ) du symbole est étendue sans casser la compatibilité avec les versions précédentes. La tenue à jour de ces fichiers est à la charge du responsable du paquet, avec l’aide de dpkg-gensymbols.

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 versions. 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 base interchange format of the symbols file is described in deb-symbols(5), which is used by the symbols files included in binary packages. These are generated from template symbols files with a format based on the former, described in deb-src-symbols(5) and included in source packages.

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.

The diffs contained in the build logs can be used as a starting point, but the maintainer, additionally, has to make sure that the behaviour of those symbols has not changed in a way that would make anything using those symbols and linking against the new version, stop working with the old version.

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.

Note that you can put comments in symbols files.

N’oubliez pas de vérifier si les anciennes versions des symboles ne doivent pas être incrémentées. Il n’y a pas de moyen pour que dpkg-gensymbols prévienne de cela. Appliquer aveuglement le fichier de différences ou supposer qu’il n’y a rien à changer, s’il n’y a pas de fichier de différences, sans vérifier s’il y a ces modifications, peut faire que des paquets, avec des dépendances lâches, prétendent qu’ils peuvent fonctionner avec des paquets plus anciens avec lesquels ils ne peuvent fonctionner. Cela introduira des bogues difficiles à trouver avec des mises à niveau (partielles).

Bonnes pratiques de gestion des bibliothèques
Une bibliothèque bien maintenue offre les possibilités suivantes :

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

N’analyse que les bibliothèques explicitement mentionnées au lieu de rechercher toutes les bibliothèques publiques. Les motifs du shell peuvent être utilisés pour l’expansion des chemins d’accès (voir la page de manuel de File::Glob(3perl) pour plus d’informations) dans fichier-bibliothèque pour établir une correspondance avec plusieurs bibliothèques avec un seul paramètre (afin d’éviter d’utiliser plusieurs options -e).

-lrépertoire

Ajoute répertoire au début de la liste des répertoires où chercher des bibliothèques partagées privées (depuis dpkg 1.19.1). Cette option peut être utilisée plusieurs fois.

Note: Use this option instead of setting LD_LIBRARY_PATH , as that environment variable is used to control the run-time linker and abusing it to set the shared library paths at build-time can be problematic when cross-compiling for example.

-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[nom-de-fichier]

Affiche le fichier de symboles créé sur la sortie standard ou dans le nom-de-fichier, si spécifié, plutôt que dans debian/tmp/DEBIAN/symbols (ou répertoire-construction-paquet/DEBIAN/symbols si -P est présent). Si nom-de-fichier existe déjà, son contenu sera utilisé comme base pour le fichier créé. Cette fonctionnalité permet de mettre à jour le fichier de symboles pour qu’il corresponde à une nouvelle version amont de la bibliothèque.

-c[0-4]

Définit les contrôles à effectuer lors de la comparaison du fichier de symboles créé 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.

Cette valeur peut être remplacée par la valeur de la variable d’environnement DPKG_GENSYMBOLS_CHECK_LEVEL .

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

-?, --help

Affiche un message d’aide puis quitte.

--version

Affiche le numéro de version puis quitte.

ENVIRONNEMENT

DPKG_GENSYMBOLS_CHECK_LEVEL

Remplace le niveau de vérification de commande, même si l’argument en ligne de commande -c a été donné (notez que cela va à l’encontre de la convention générale qui veut que les arguments en ligne de commande ont la préséance sur les variables d’environnement).

DPKG_COLORS

Définit le mode de couleur (depuis dpkg 1.18.5). Les valeurs actuellement acceptées sont auto (par défaut), always et never.

DPKG_NLS

Si cette variable est définie, elle sera utilisée pour décider l’activation de la prise en charge des langues ( NLS – Native Language Support), connu aussi comme la gestion de l’internationalisation (ou i18n) (depuis dpkg 1.19.0). Les valeurs permises sont : 0 et 1 (par défaut).

VOIR AUSSI

https://people.redhat.com/drepper/symbol-versioning

https://people.redhat.com/drepper/goodpractice.pdf

https://people.redhat.com/drepper/dsohowto.pdf

deb-src-symbol(5), deb-symbols(5), dpkg-shlibdeps(1).

TRADUCTION

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