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
|
*****************************************************
* 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 NAAM
dpkg-gensymbols - symboolbestanden genereren (informatie over afhankelijkheidsrelaties met gedeelde bibliotheken)
=head1 OVERZICHT
B<dpkg-gensymbols> [I<optie>...]
=head1 BESCHRIJVING
B<dpkg-gensymbols> doorzoekt een tijdelijke bouwboom (standaard is dat debian/tmp) op zoek naar bibliotheken en genereert een I<symbols>-bestand dat ze beschrijft. Dit bestand wordt dan als het niet leeg is, geïnstalleerd in een onderliggende map van de bouwboom met de naam DEBIAN, zodat het uiteindelijk opgenomen geraakt in de controle-informatie van het pakket.
Bij het genereren van deze bestanden gebruikt het als invoer bepaalde symboolbestanden die door de beheerder aangeleverd worden. Het zoekt naar de volgende bestanden (en gebruikt het eerste dat gevonden wordt):
=over
=item *
debian/I<pakket>.symbols.I<arch>
=item *
debian/symbols.I<arch>
=item *
debian/I<pakket>.symbols
=item *
debian/symbols
=back
Het hoofddoel van deze bestanden is aan te geven welke de minimale versie is die behoort bij elk van de symbolen die door de bibliotheken aangeleverd worden. Gewoonlijk komt dit overeen met de eerste versie van het pakket dat in dat symbool voorzag, maar dit kan door de beheerder manueel verhoogd worden indien de ABI van het symbool uitgebreid werd zonder dat daardoor de neerwaartse compatibiliteit verbroken wordt. Het is de verantwoordelijkheid van de beheerder om deze bestanden up-to-date en accuraat te houden, maar B<dpkg-gensymbols> helpt hierbij.
Indien het gegenereerde symboolbestand verschilt van datgene wat de beheerder aanlevert, zal B<dpkg-gensymbols> de verschillen tussen de twee versies tonen in diff-formaat. Bovendien kan dit zelfs tot een mislukking leiden als de verschillen te significant zijn (u kunt aanpassen hoeveel verschil u kunt tolereren; zie de optie B<-c>).
Dit programma werd geïntroduceerd in dpkg 1.14.8.
=head1 HET ONDERHOUD VAN SYMBOOLBESTANDEN
De basisuitwisselingsindeling van het symboolbestand wordt beschreven in L<deb-symbols(5)>, hetgeen gebruikt wordt door de symboolbestanden uit de binaire pakketten. Deze worden gegenereerd uit sjabloonsymboolbestanden met een indeling gebaseerd op het eerste, beschreven in L<deb-src-symbols(5)> en opgenomen in broncodepakketten.
De symboolbestanden zijn pas echt nuttig als ze de evolutie van het pakket reflecteren doorheen verschillende releases. De beheerder moet ze dus iedere keer bijwerken wanneer een nieuw symbool toegevoegd wordt, zodat de minimale versie die eraan gekoppeld wordt, overeenkomt met de realiteit.
De diffs (weergave van de verschillen) die in de bouwlogs te vinden zijn, kunnen als startpunt genomen worden, maar daarbovenop moet de beheerder erop letten dat het gedrag van deze symbolen niet zodanig veranderd werd, dat iets dat van deze symbolen gebruik maakt en linkt met de nieuwe versie, niet stopt met werken met de oude versie.
In de meeste gevallen kan de diff rechtstreeks toegepast worden op het bestand debian/I<pakket>.symbols. Dit gezegd zijnde, zijn verdere aanpassingen meestal wel nodig: het wordt bijvoorbeeld aanbevolen om het Debian revisienummer weg te laten uit de minimale versie, zodat backports (nieuwere programmaversies die geschikt gemaakt worden voor een vroegere release) met een lager versienummer maar eenzelfde bovenstroomse versie nog steeds voldoen aan de gegenereerde afhankelijkheidsrelaties. Indien het Debian revisienummer niet weggelaten kan worden omdat het symbool echt via een Debian-specifieke aanpassing toegevoegd werd, moet men aan het versienummer het achtervoegsel ‘B<~>’ toevoegen.
Vooraleer een patch toe te passen op een symboolbestand, moet de beheerder grondig controleren of dat wel correct is. Publieke symbolen worden verondersteld niet te verdwijnen. Een patch zou dus idealiter enkel nieuwe regels mogen toevoegen.
Merk op dat u in symboolbestanden commentaar kunt invoegen.
Vergeet niet na te gaan of oudere symboolversies niet verhoogd moeten worden. Er bestaat geen manier voor B<dpkg-gensymbols> om in dit verband waarschuwingen te geven. Een diff (weergave van de verschillen) blindweg toepassen of ervan uitgaan dat er niets aangepast moet worden als er geen diff is zonder zelf op eventuele wijzigingen te controleren, kan leiden tot pakketten met verslapte afhankelijkheidsrelaties die onterecht laten veronderstellen dat ze met oudere pakketten kunnen samenwerken. Dit kan bij (gedeeltelijke) opwaarderingen leiden tot moeilijk te vinden bugs.
=head2 Goed beheer van bibliotheken
Een goed onderhouden bibliotheek heeft de volgende functionaliteit:
=over
=item *
haar API is stabiel (publieke symbolen worden nooit verwijderd, enkel worden nieuwe publieke symbolen toegevoegd) en zij ondergaat enkel op een incompatibele manier veranderingen als de SONAME verandert;
=item *
idealiter gebruikt zij symboolversienummering om ondanks interne wijzigingen en API-uitbreidingen ABI-stabiliteit te bekomen;
=item *
zij exporteert geen private symbolen (dergelijke symbolen kunnen de tag optional krijgen om dat te omzeilen).
=back
Bij het onderhoud van een symboolbestand is het gemakkelijk om het verschijnen en verdwijnen van symbolen op te merken. Maar het is moeilijker om incompatibele API- en ABI-wijzigingen op te merken. Daarom moet de beheerder het changelog-bestand van de toeleveraar grondig nakijken op situaties waarbij de regels van goed bibliotheekbeheer geschonden worden. Indien mogelijke problemen ontdekt worden, zou de toeleverende auteur erover ingelicht moeten worden, aangezien een reparatie op het niveau van de toeleveraar altijd te verkiezen valt boven een Debian-specifieke tijdelijke oplossing.
=head1 OPTIES
=over
=item B<-P>I<pakketbouwmap>
Zoek in I<pakketbouwmap> in plaats van in debian/tmp.
=item B<-p>I<pakket>
Definieer de pakketnaam. Is vereist als meer dan één binair pakket vermeld wordt in debian/control (of indien er geen bestand debian/control is).
=item B<-v>I<versie>
Definieer de pakketversie. Standaard is dat de versie die uit debian/changelog gehaald wordt. Is vereist indien het aanroepen gebeurt van buiten de boom van het broncodepakket.
=item B<-e>I<bibliotheekbestand>
Analyseer enkel de expliciet vermelde bibliotheken in plaats van alle publieke bibliotheken te zoeken. U kunt in I<bibliotheekbestand> gebruik maken van shell-patronen met het oog op padnaamexpansie (zie de man-pagina L<File::Glob> voor details) om met één enkel argument meerdere bibliotheken aan te duiden (anders heeft u meerdere malen B<-e> nodig).
=item B<-l>I<map>
Voeg I<map> vooraan toe aan de lijst van mappen waarin naar private gedeelde bibliotheken gezocht moet worden (sinds dpkg 1.19.1). Deze optie kan meermaals gebruikt worden.
B<Opmerking>: gebruik deze optie in de plaats van het instellen van B<LD_LIBRARY_PATH>, aangezien die omgevingsvariabele gebruikt wordt om de runtime linker aan te sturen. Daarvan misbruik maken om de paden van gedeelde bibliotheken in te stellen tijdens het bouwen van het programma, kan problematisch zijn, bijvoorbeeld bij het cross-compileren.
=item B<-I>I<bestandsnaam>
Gebruik I<bestandsnaam> als referentiebestand om het symboolbestand te genereren dat in het pakket zelf geïntegreerd wordt.
=item B<-O>[I<bestandsnaam>]
Het gegenereerde symboolbestand weergeven op de standaarduitvoer of schrijven naar I<bestandsnaam> als dat opgegeven werd, eerder dan naar B<debian/tmp/DEBIAN/symbols> (of I<pakketbouwmap>B</DEBIAN/symbols> indien B<-P> gebruikt werd). Indien I<bestandsnaam> reeds bestond, wordt de inhoud ervan gebruikt als basis voor het gegenereerde symboolbestand. U kunt van deze functionaliteit gebruik maken om een symboolbestand bij te werken zodat het in overeenstemming is met een nieuwere bovenstroomse versie van uw bibliotheek.
=item B<-t>
Het symboolbestand in sjabloonmodus opschrijven, eerder dan in de indeling die compatibel is met L<deb-symbols(5)>. Het grootste verschil is dat in de sjabloonmodus symboolnamen en tags geschreven worden in hun originele vorm in tegenstelling tot in de compatibele modus waarin de verwerkte symboolnamen ontdaan van hun tags gebruikt worden. Daarenboven kunnen bij het schrijven van een standaard L<deb-symbols(5)>-bestand sommige symbolen weggelaten worden (overeenkomstig de regels voor het verwerken van tags), terwijl in een symboolbestand-sjabloon steeds alle symbolen neergeschreven worden.
=item B<-c>I<[0-4]>
Definiëren welke controles moeten gebeuren bij het vergelijken van het gegenereerde symboolbestand met het sjabloonbestand dat als vertrekpunt gebruikt werd. Standaard is dat volgens niveau 1. Het verhogen van het niveau leidt tot meer controles, terwijl alle controles van lagere niveaus behouden blijven.
=over
=item Niveau 0
Leidt nooit tot een mislukking.
=item Niveau 1
Leidt tot een mislukking als sommige symbolen verdwenen zijn.
=item Niveau 2
Leidt tot een mislukking als sommige nieuwe symbolen geïntroduceerd werden.
=item Niveau 3
Leidt tot een mislukking als sommige bibliotheken verdwenen zijn.
=item Niveau 4
Leidt tot een mislukking als sommige nieuwe bibliotheken geïntroduceerd werden.
=back
Deze waarde kan vervangen worden door de omgevingsvariabele B<DPKG_GENSYMBOLS_CHECK_LEVEL>.
=item B<-q>
Stil blijven en nooit een diff (een overzicht van de verschillen) maken tussen het gegenereerde symboolbestand en het sjabloonbestand dat als vertrekpunt gebruikt werd en geen enkele waarschuwing tonen in verband met nieuwe/verloren bibliotheken of nieuwe/verloren symbolen. Deze optie schakelt enkel de informatieve uitvoer uit, maar niet de controles zelf (zie de optie B<-c>).
=item B<-a>I<arch>
Uitgaan van I<arch> als host-architectuur bij het verwerken van symboolbestanden. Gebruik deze optie om een symboolbestand of een diff (overzicht van de verschillen) voor een willekeurige architectuur te genereren op voorwaarde dat de binaire bestanden ervan reeds voorhanden zijn.
=item B<-d>
Debug-modus aanzetten. Talrijke berichten worden dan getoond om toe te lichten wat B<dpkg-gensymbols> doet.
=item B<-V>
De breedsprakige modus inschakelen. Het gegenereerde symboolbestand bevat dan verouderde symbolen in de vorm van commentaar. In sjabloonmodus worden daarenboven patroonsymbolen gevolgd door commentaar met daarin een opsomming van de echte symbolen die met het patroon overeenkwamen.
=item B<-?>, B<--help>
Info tonen over het gebruik en afsluiten.
=item B<--version>
De versie tonen en afsluiten.
=back
=head1 OMGEVING
=over
=item B<DEB_HOST_ARCH>
Sets the host architecture if the B<--arch> option has not be specified.
=item B<DPKG_GENSYMBOLS_CHECK_LEVEL>
Overschrijft het controleniveau van het commando, zelfs als het argument B<-c> opgegeven werd aan de commandoregel (merk op dat dit ingaat tegen de algemeen geldende afspraak dat commandoregel-argumenten voorrang hebben op omgevingsvariabelen).
=item B<DPKG_COLORS>
Stelt de kleurmodus in (sinds dpkg 1.18.5). Waarden die momenteel gebruikt mogen worden zijn: B<auto> (standaard), B<always> en B<never>.
=item B<DPKG_NLS>
Indien dit ingesteld is, zal het gebruikt worden om te beslissen over het activeren van moedertaalondersteuning, ook gekend als internationaliseringsondersteuning (of i18n) (sinds dpkg 1.19.0). Geldige waarden zijn: B<0> and B<1> (standaard).
=back
=head1 ZIE OOK
L<https://people.redhat.com/drepper/symbol-versioning>, L<https://people.redhat.com/drepper/goodpractice.pdf>, L<https://people.redhat.com/drepper/dsohowto.pdf>, L<deb-src-symbol(5)>, L<deb-symbols(5)>, L<dpkg-shlibdeps(1)>.
|
