1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
*****************************************************
* GENERATED FILE, DO NOT EDIT *
* THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
*****************************************************
This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.
In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.
=encoding UTF-8
=head1 NOM
dpkg-gensymbols - Création des fichiers de symboles (information de dépendances de bibliothèques partagées)
=head1 SYNOPSIS
B<dpkg-gensymbols> [I<option>...]
=head1 DESCRIPTION
B<dpkg-gensymbols> analyse un répertoire temporaire de construction (par défaut debian/tmp), y recherche les bibliothèques et crée un fichier I<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 S<trouvé) :>
=over
=item *
debian/I<paquet>.symbols.I<arch>
=item *
debian/symbols.I<arch>
=item *
debian/I<paquet>.symbols
=item *
debian/symbols
=back
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 B<dpkg-gensymbols>.
Quand les fichiers de symboles créés sont différents de ceux fournis par le responsable, B<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 B<-c>).
=head1 TENUE À JOUR DES FICHIERS SYMBOLES
Le format interchangeable de base du fichier de symboles est décrit dans B<deb-symbols>(5) et est utilisé par les fichiers de symboles inclus dans les paquets binaires. Ils sont générés à partir des fichiers de symboles modèles avec un format basé sur le précédent décrit dans B<deb-src-symbols>(5) et inclus dans les paquets source.
Les fichiers de symboles deviennent réellement utiles lorsqu'ils permettent de suivre l'évolution du paquet sur plusieurs versions. En conséquence, le responsable doit les mettre à jour chaque fois qu'un nouveau symbole est ajouté afin que la version minimale associée corresponde à la réalité.
Pour effectuer cette opération correctement, le fichier de différences indiqué dans le journal de construction peut être utilisé, mais en plus, le mainteneur doit s'assurer que le comportement de ces symboles n'a pas changé d'une manière qui pourrait faire que tout ce qui utilise ces symboles et qui est lié à la nouvelle version cesse de fonctionner avec l'ancienne version.
Dans la plupart des cas, ce fichier de différences peut être appliqué tel quel au fichier debian/I<paquet>.symbols. Cela étant, quelques adaptations sont généralement S<nécessaires :> il est par exemple recommandé de retirer le numéro de révision Debian de la version minimale afin que les paquets rétro-portés, de numéro de version inférieur mais avec la même version amont continuent à répondre aux pré-requis. Si le numéro de révision Debian ne peut vraiment pas être retiré, car le nouveau symbole est la conséquence d'une modification propre à Debian, il est suggéré d'ajouter un suffixe S<« B<~> »> au numéro de version.
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.
Notez qu'il est possible d'introduire des commentaires dans les fichiers de symboles.
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 B<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).
=head2 Bonnes pratiques de gestion des bibliothèques
Une bibliothèque bien maintenue offre les possibilités S<suivantes :>
=over
=item *
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ées avec un changement de SONAME ;
=item *
idéalement, elle utilise le versionnage des symboles pour garantir la stabilité de l'interface applicative binaire (ABI) malgré ses modifications internes et l'extension de son API ;
=item *
elle n'exporte pas les symboles privés (afin de contourner cela, de tels symboles peuvent être étiquetés comme optionnels).
=back
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.
=head1 OPTIONS
=over
=item B<-P>I<répertoire-construction-paquet>
Analyse de I<répertoire-construction-paquet>, plutôt que debian/tmp.
=item B<-p>I<paquet>
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).
=item B<-v>I<version>
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.
=item B<-e>I<fichier-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 B<File::Glob>(3perl) pour plus d'informations) dans I<fichier-bibliothèque> pour établir une correspondance avec plusieurs bibliothèques avec un seul paramètre (afin d'éviter d'utiliser plusieurs options B<-e>).
=item B<-l>I<répertoire>
Ajoute I<répertoire> au début de la liste des répertoires où chercher des bibliothèques partagées privées (depuis S<dpkg 1.19.1).> Cette option peut être utilisée plusieurs fois.
S<B<Note :>> Utilisez cette option plutôt que le réglage de B<LD_LIBRARY_PATH>, parce que cette variable d'environnement est utilisée pour contrôler l'éditeur de liens d'exécution et se servir d'elle pour définir les chemins des bibliothèques partagées au moment de la construction peut être problématique, par exemple, lors d'une compilation croisée.
=item B<-I>I<nom-de-fichier>
Utilise I<nom-de-fichier> comme fichier de référence pour créer le fichier de symboles à intégrer dans le paquet lui-même.
=item B<-O>[I<nom-de-fichier>]
Affiche le fichier de symboles créé sur la sortie standard ou dans le I<nom-de-fichier>, si spécifié, plutôt que dans B<debian/tmp/DEBIAN/symbols> (ou I<répertoire-construction-paquet>B</DEBIAN/symbols> si B<-P> est présent). Si I<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.
=item B<-t>
Écrit le fichier de symboles en mode modèle plutôt que dans un format compatible avec B<deb-symbols>(5). La différence majeure réside dans le fait que les noms de symboles et les étiquettes sont écrits dans leur forme d'origine au lieu d'être interprétés, avec réduction des étiquettes en mode de compatibilité. De plus, certains symboles peuvent être omis lors de l'écriture d'un fichier B<deb-symbols>(5) standard (selon les règles de traitement des étiquettes) alors que tous les symboles sont écrits lors de la création d'un modèle de fichier de symboles.
=item B<-c>I<[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.
=over
=item S<Niveau 0>
Sans échec.
=item S<Niveau 1>
Échoue si certains symboles ont disparu.
=item S<Niveau 2>
Échoue si de nouveaux symboles ont été ajoutés.
=item S<Niveau 3>
Échoue si certaines bibliothèques ont disparu.
=item S<Niveau 4>
Échoue si des bibliothèques ont été ajoutées.
=back
Cette valeur peut être remplacée par la valeur de la variable d'environnement B<DPKG_GENSYMBOLS_CHECK_LEVEL>.
=item B<-q>
Fonctionne en mode silencieux et ne crée jamais de fichier de différences entre le fichier de symboles créé et le fichier modèle utilisé comme point de départ. N'affiche également aucun avertissement à propos de bibliothèques nouvelles ou disparues ou de symboles nouveaux ou disparus. Cette option ne désactive que l'affichage informatif, mais pas les contrôles eux-mêmes (voir l'option B<-c>).
=item B<-a>I<arch>
Définit I<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.
=item B<-d>
Active le mode bavard. De nombreux messages sont affichés pour expliquer ce que B<dpkg-gensymbols> fait.
=item B<-V>
Active le mode bavard. 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.
=item B<-?>, B<--help>
Afficher un message d'aide puis quitter.
=item B<--version>
Afficher le numéro de version puis quitter.
=back
=head1 ENVIRONNEMENT
=over
=item B<DPKG_GENSYMBOLS_CHECK_LEVEL>
Remplace le niveau de vérification de commande, même si l'argument en ligne de commande B<-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).
=item B<DPKG_COLORS>
Définit le mode de couleur (depuis S<dpkg 1.18.5).> Les valeurs actuellement acceptées sont B<auto> (par défaut), B<always> et B<never>.
=item B<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 S<dpkg 1.19.0).> Les valeurs permises S<sont :> B<0> et B<1> (par défaut).
=back
=head1 VOIR AUSSI
L<https://people.redhat.com/drepper/symbol-versioning>, L<https://people.redhat.com/drepper/goodpractice.pdf>, L<https://people.redhat.com/drepper/dsohowto.pdf>, B<deb-src-symbol>(5), B<deb-symbols>(5), B<dpkg-shlibdeps>(1).
=head1 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>.
|
