Provided by: dpkg-dev_1.19.7ubuntu3.2_all 
NAAM
dpkg-gensymbols - genereer symbolenbestanden (informatie over afhankelijkheidsrelaties met
gedeelde bibliotheken)
OVERZICHT
dpkg-gensymbols [optie...]
BESCHRIJVING
dpkg-gensymbols doorzoekt een tijdelijke bouwboom (standaard is dat debian/tmp) op zoek
naar bibliotheken en genereert een 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 symbolenbestanden
die door de onderhouder aangeleverd worden. Het zoekt naar de volgende bestanden (en
gebruikt het eerste dat gevonden wordt):
• debian/pakket.symbols.arch
• debian/symbols.arch
• debian/pakket.symbols
• debian/symbols
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 onderhouder 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 onderhouder om deze bestanden up-to-date en accuraat te
houden, maar dpkg-gensymbols helpt hierbij.
Indien het gegenereerde symbolenbestand verschilt van datgene wat de onderhouder
aanlevert, zal 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 -c).
HET ONDERHOUD VAN SYMBOLENBESTANDEN
De symbolenbestanden zijn pas echt nuttig als ze de evolutie van het pakket reflecteren
doorheen verschillende releases. De onderhouder 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 onderhouder
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/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 toeleveraarsversie
(upstream version) 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 ‘~’ toevoegen.
Vooraleer een patch toe te passen op een symbolenbestand, moet de onderhouder 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 commentaar kunt opnemen in symbolenbestanden: elke regel met ‘#’ als eerste
teken is een commentaarregel, behalve als die regel begint met ‘#include’ (zie het
onderdeel over Het gebruik van includes). Regels die beginnen met ‘#MISSING:’ zijn een
bijzondere vorm van commentaar waarin symbolen die verdwenen zijn, gedocumenteerd worden.
Vergeet niet na te gaan of oudere symboolversies niet verhoogd moeten worden. Er bestaat
geen manier voor 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.
Substitutie van #PACKAGE# gebruiken
In enkele zeldzame gevallen verschilt de naam van de bibliotheek naargelang de
architectuur. Om de naam van het pakket niet rechtstreeks in het symbolenbestand te moeten
inschrijven, kunt u gebruik maken van de marker #PACKAGE#. Die zal tijdens de installatie
van de symbolenbestanden vervangen worden door de echte pakketnaam. In tegenstelling tot
de marker #MINVER#, zal #PACKAGE# nooit te vinden zijn in een symbolenbestand binnenin een
binair pakket.
Symbooltags gebruiken
Het gebruik van symbooltags is nuttig om symbolen te markeren die op een of andere manier
bijzonder zijn. Aan elk symbool kan een arbitrair aantal tags gekoppeld worden. Hoewel
alle tags ontleed en opgeslagen worden, worden slechts een aantal ervan herkend door
dpkg-gensymbols. Ze lokken een speciale behandeling van de symbolen uit. Zie het onderdeel
Standaard symbooltags voor een voorstelling van deze tags.
Tags worden vlak voor de symboolnaam opgegeven (tussenin mag er geen witruimte zijn). Een
opgave begint steeds met het openen van een haakje ( en eindigt met het sluiten ervan ) en
moet minstens één tag bevatten. Meerdere tags worden onderling gescheiden door een
|-teken. Elke tag kan een facultatieve waarde hebben die van de naam van de tag gescheiden
wordt door het teken =. Namen van tags en waarden kunnen arbitraire tekenreeksen zijn,
behalve dat zij niet de speciale tekens ) | = mogen bevatten. De symboolnaam die na een
tagopgave komt kan facultatief tussen aanhalingstekens geplaatst worden, ofwel met ' of
met ", waardoor hij witruimte mag bevatten. Evenwel, indien er voor het symbool geen tags
opgegeven werden, zullen de aanhalingstekens behandeld worden als onderdeel van de naam
van het symbool die eindigt bij de eerste spatie.
(tag1=ik werd gemarkeerd|tagnaam met spatie)"getagd en aangehaald symbool"@Base 1.0
(optional)getagd_niet-aangehaald_symbool@Base 1.0 1
niet-getagd_symbool@Base 1.0
Het eerste symbool in het voorbeeld werd getagd en aangehaald symbool genoemd en heeft
twee tags: tag1 met als waarde ik werd gemarkeerd en tagnaam met spatie die geen waarde
heeft. Het tweede symbool met als naam getagd_niet-aangehaald_symbool werd enkel
gemarkeerd met de tag die optional als naam heeft. Het laatste symbool is een voorbeeld
van een normaal niet-gemarkeerd symbool.
Aangezien symbooltags een uitbreiding zijn van het deb-symbols(5)-systeem, kunnen zij
enkel deel uitmaken van de symbolenbestanden die in broncodepakketten gebruikt worden (die
bestanden moeten dan gezien worden als sjablonen die gebruikt worden om de
symbolenbestanden te bouwen die in de binaire pakketten zitten). Indien dpkg-gensymbols
aangeroepen wordt zonder de optie -t zal het symbolenbestanden produceren die compatibel
zijn met het deb-symbols(5)-systeem: er gebeurt een volledige verwerking van de symbolen
in overeenstemming met de vereisten van hun standaardtags en de uitvoer wordt ontdaan van
alle tags. In sjabloonmodus (-t) daarentegen blijven in de uitvoer alle symbolen en hun
tags (zowel de standaardtags als de niet-gekende) behouden en worden ze in hun originele
vorm neergeschreven zoals ze geladen werden.
Standaard symbooltags
optional
Een symbool dat als optional (facultatief) gemarkeerd is, kan om het even wanneer
uit de bibliotheek verdwijnen en dat feit zal nooit een mislukking van
dpkg-gensymbols tot gevolg hebben. Nochtans zullen verdwenen facultatieve symbolen
permanent als MISSING (ontbrekend) aangegeven worden in de diff (weergave van de
veranderingen) bij elke nieuwe pakketrevisie. Dit gedrag dient als een
geheugensteuntje voor de onderhouder dat een dergelijk symbool verwijderd moet
worden uit het symbolenbestand of terug toegevoegd aan de bibliotheek. Indien een
facultatief symbool dat eerder als MISSING opgetekend stond in een volgende revisie
plots opnieuw terug opduikt, zal het terug opgewaardeerd worden naar de status
“existing” (bestaand) zonder wijziging van zijn minimumversie.
Deze tag is nuttig voor private symbolen waarvan de verdwijning geen ABI-breuk
veroorzaakt. De meeste van de C++-sjabloon-instantiaties vallen bijvoorbeeld onder
deze categorie. Zoals elke andere tag kan ook deze een arbitraire waarde hebben:
die kan gebruikt worden om aan te geven waarom het symbool als facultatief
beschouwd wordt.
arch=architectuurlijst
arch-bits=architectuur-bits
arch-endian=architectuur-endianness
Deze tags laten iemand toe om de set architecturen waarvoor het symbool
verondersteld wordt te bestaan, te beperken. De tags arch-bits en arch-endian
worden sinds dpkg 1.18.0 ondersteund. Als de symbolenlijst bijgewerkt wordt met de
symbolen die in de bibliotheek gevonden worden, worden alle architectuurspecifieke
symbolen die van geen belang zijn voor de huidige hostarchitectuur, behandeld alsof
ze niet bestaan. Indien een architectuurspecifiek symbool dat betrekking heeft op
de huidige hostarchitectuur, ontbreekt in de bibliotheek, zijn de normale
procedures die gelden voor ontbrekende symbolen, van toepassing en dit kan het
mislukken van dpkg-gensymbols tot gevolg hebben. Anderzijds, indien het
architectuurspecifieke symbool aangetroffen wordt als het er niet verondersteld
wordt te zijn (omdat de huidige hostarchitectuur niet vermeld wordt in de tag of
niet overeenkomt met de endianness of de bits), dan wordt het architectuurneutraal
gemaakt (d.w.z. dat de tags arch, arch-bits en arch-endian weggelaten worden en het
symbool omwille van deze verandering in de diff (weergave van de veranderingen)
opgenomen zal worden), maar het wordt niet als nieuw beschouwd.
Als in de standaardmodus (niet-sjabloonmodus) gewerkt wordt, worden van de
architectuurspecifieke symbolen enkel die in het symbolenbestand opgeschreven die
overeenkomen met de huidige hostarchitectuur. Als daarentegen in de sjabloonmodus
gewerkt wordt, worden steeds alle architectuurspecifieke symbolen (ook die voor
vreemde architecturen) opgeschreven in het symbolenbestand.
De indeling voor de architectuurlijst is dezelfde als die welke gebruikt wordt voor
het veld Build-Depends van debian/control (behalve de omsluitende vierkante haakjes
[]). Met het eerste symbool uit de onderstaande lijst zal bijvoorbeeld enkel
rekening gehouden worden bij de architecturen alpha, any-amd64 en ia64, met het
tweede enkel op linux-architecturen en met het derde overal behalve op armel.
(arch=alpha any-amd64 ia64)een_64bits_specifiek_symbool@Base 1.0
(arch=linux-any)linux_specifiek_symbool@Base 1.0
(arch=!armel)symbool_dat_armel_niet_heeft@Base 1.0
De waarde van architectuur-bits is ofwel 32 of 64.
(arch-bits=32)32bits_specifiek_symbool@Base 1.0
(arch-bits=64)64bits_specifiek_symbool@Base 1.0
De waarde van architectuur-endianness is ofwel little of big.
(arch-endian=little)little_endian_specifiek_symbool@Base 1.0
(arch-endian=big)big_endian_specifiek_symbool@Base 1.0
Meerdere beperkingen kunnen aaneengeregen worden.
(arch-bits=32|arch-endian=little)32bits_le_symbool@Base 1.0
ignore-blacklist
dpkg-gensymbols hanteert een interne zwarte lijst van symbolen die niet zouden
mogen voorkomen in symbolenbestanden omdat ze gewoonlijk slechts een neveneffect
zijn van details in de wijze waarop de gereedschapskist (toolchain) geïmplementeerd
wordt. Indien u om een of andere reden echt wilt dat een van deze symbolen
opgenomen wordt in het symbolenbestand, moet u het symbool markeren met de tag
ignore-blacklist. Dit kan nodig zijn voor sommige gereedschapskistbibliotheken van
lagere orde zoals libgcc
c++ Geeft een c++-symboolpatroon aan. Zie hierna in de subsectie Het gebruik van
symboolpatronen.
symver Geeft een symver (symboolversie) symboolpatroon aan. Zie hierna in de subsectie Het
gebruik van symboolpatronen.
regex Geeft een regex-symboolpatroon aan. Zie hierna in de subsectie Het gebruik van
symboolpatronen.
Het gebruik van symboolpatronen
Anders dan een standaardbeschrijving van een symbool, kan een patroon meerdere echte
symbolen uit de bibliotheek dekken. dpkg-gensymbols zal proberen om elk patroon te
vergelijken met elk reëel symbool waarvoor in het symbolenbestand geen specifiek
symboolpendant gedefinieerd werd. Telkens wanneer een eerste overeenkomst met een patroon
gevonden wordt, worden alle tags en eigenschappen ervan gebruikt als basisspecificatie
voor het symbool. Indien er met geen enkel patroon een overeenkomst gevonden wordt, zal
het symbool als nieuw beschouwd worden.
Een patroon wordt als verloren beschouwd als het met geen enkel symbool uit de bibliotheek
overeenkomt. Standaard zal dit onder -c1 of een hoger niveau een mislukking van
dpkg-gensymbols uitlokken. Indien een dergelijke mislukking echter onwenselijk is, kan het
patroon gemarkeerd worden met de tag optional. Als het patroon in dat geval geen
overeenkomst oplevert, zal het enkel in de diff (weergave van de wijzigingen) als MISSING
(ontbrekend) vermeld worden. Zoals elk ander symbool kan ook een patroon beperkt worden
tot specifieke architecturen met de tag arch. Raadpleeg het onderdeel Standaard
symbooltags hierboven voor meer informatie.
Patronen vormen een uitbreiding van het deb-symbols(5)-systeem en zijn daarom enkel geldig
in symbolenbestandsjablonen. De syntaxis voor het opgeven van patronen verschilt niet van
die voor een specifiek symbool. Het onderdeel symboolnaam van de specificatie fungeert
echter als een expressie die vergeleken wordt met naam@versie van het echte symbool. Om
het onderscheid te maken tussen verschillende types patronen, wordt een patroon doorgaans
gemarkeerd met een speciale tag
Op dit ogenblik ondersteunt dpkg-gensymbols drie fundamentele patroontypes:
c++
Dit patroon wordt met de tag c++ aangeduid. Het zoekt enkel een overeenkomst met
C++-symbolen aan de hand van hun ontwarde (demangled) symboolnaam (zoals die
weergegeven wordt door het hulpprogramma c++filt(1)). Dit patroon is zeer handig om
symbolen te vinden waarvan de verhaspelde naam op verschillende architecturen anders
kan zijn, terwijl hun ontwarde naam gelijk blijft. Een groep van dergelijke symbolen is
non-virtual thunks die architectuurspecifieke geheugenplaatsen ingebed hebben in hun
verhaspelde naam. Een courant voorkomend voorbeeld hiervan is een virtuele destructor
die onder een diamantovererving een niet-virtueel thunk-symbool nodig heeft.
Bijvoorbeeld, zelfs als _ZThn8_N3NSB6ClassDD1Ev@Base op 32-bits-architecturen wellicht
_ZThn16_N3NSB6ClassDD1Ev@Base zal zijn op 64-bits-architecturen, kunnen zij met één
enkel c++-patroon aangeduid worden:
libdummy.so.1 libdummy1 #MINVER#
[...]
(c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
[...]
De bovenstaande ontwarde naam kan verkregen worden door het volgende commando uit te
voeren:
$ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt
Merk op dat een verhaspelde naam per definitie uniek is in de bibliotheek, maar dat dit
niet noodzakelijk het geval is voor ontwarde namen. Een aantal verschillende echte
symbolen kan dezelfde ontwarde naam hebben. Dat is bijvoorbeeld het geval met
niet-virtuele thunk-symbolen in complexe overervingsconfiguraties of met de meeste
constructors en destructors (vermits g++ voor hen doorgaans twee echte symbolen
genereert). Vermits deze collisies zich op het ABI-niveau voordoen, verminderen zij
evenwel niet de kwaliteit van het symbolenbestand.
symver
Dit patroon wordt door de tag symver aangegeven. Goed onderhouden bibliotheken hebben
symbolen met versienummers, waarbij elke versie overeenkomt met de toeleveraarsversie
waar het symbool toegevoegd werd. Indien dat het geval is, kunt u een symver-patroon
gebruiken om eventuele symbolen aan te duiden die gekoppeld zijn aan de specifieke
versie. Bijvoorbeeld:
libc.so.6 libc6 #MINVER#
(symver)GLIBC_2.0 2.0
[...]
(symver)GLIBC_2.7 2.7
access@GLIBC_2.0 2.2
Alle symbolen die horen bij de versies GLIBC_2.0 en GLIBC_2.7 zullen resulteren in de
respectieve minimale versies 2.0 en 2.7, met uitzondering van het symbool
access@GLIBC_2.0. Dit laatste zal resulteren in een minimale vereiste van libc6 versie
2.2 en dit ondanks het feit dat het valt binnen het bereik van het patroon
"(symver)GLIBC_2.0". De reden hiervoor is dat specifieke symbolen voorrang hebben op
patronen.
Merk op dat hoewel patronen met jokertekens volgens de oude stijl (in het veld
symboolnaam aangegeven door "*@version") nog steeds ondersteund worden, zij vervangen
werden door een syntaxis volgens de nieuwe stijl "(symver|optional)version". Als
hetzelfde effect gewenst wordt moet bijvoorbeeld "*@GLIBC_2.0 2.0" geschreven worden
als "(symver|optional)GLIBC_2.0 2.0".
regex
Patronen in de vorm van reguliere expressies worden aangegeven met de tag regex. Zij
zoeken naar een overeenkomst met de in het veld symboolnaam vermelde perl reguliere
expressie. Een reguliere expressie wordt als zodanig vergeleken. Daarom mag u niet
vergeten ze te laten beginnen met het teken ^. Anders kan ze een overeenkomst opleveren
met om het even welk deel van de tekenreeks naam@versie van het echte symbool.
Bijvoorbeeld:
libdummy.so.1 libdummy1 #MINVER#
(regex)"^mystack_.*@Base$" 1.0
(regex|optional)"private" 1.0
Symbolen zoals "mystack_new@Base", "mystack_push@Base", "mystack_pop@Base" enz. zullen
door het eerste patroon gevonden worden, terwijl "ng_mystack_new@Base" bijvoorbeeld
niet. Het tweede patroon zal een overeenkomst opleveren met alle symbolen die in hun
naam de tekenreeks "private" hebben en de gevonden symbolen zullen de tag optional
overerven van het patroon.
De hierboven vermelde basispatronen kunnen met elkaar gecombineerd worden als dat zinvol
is. In dat geval worden zij verwerkt in de volgorde waarin de tags opgegeven werden.
Bijvoorbeeld beide onderstaande patronen
(c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
(regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
zullen de symbolen "_ZN3NSA6ClassA7Private11privmethod1Ei@Base" en
"_ZN3NSA6ClassA7Private11privmethod2Ei@Base" vinden. Bij het vergelijken met het eerste
patroon wordt het rauwe symbool eerst ontward als een C++-symbool en vervolgens wordt de
ontwarde naam vergeleken met de reguliere expressie. Bij het vergelijken met het tweede
patroon daarentegen, wordt de reguliere expressie vergeleken met de rauwe symboolnaam en
vervolgens wordt nagegaan of het een C++-symbool is door het te proberen ontwarren. Als
een basispatroon een mislukking oplevert, betekent dit het mislukken van het hele patroon.
Om die reden zal "__N3NSA6ClassA7Private11privmethod\dEi@Base" bijvoorbeeld met geen van
beide patronen een overeenkomst opleveren, aangezien het geen geldig C++-symbool is.
Over het algemeen genomen kunnen alle patronen in twee groepen onderverdeeld worden:
aliassen (basale c++- en symver-patronen) en generieke patronen (regex, alle combinaties
van meerdere basale patronen). Het vergelijken met basale patronen van het alias-type
verloopt snel (O(1)), terwijl dat bij generieke patronen voor elk symbool O(N) is (waarbij
N het aantal generieke patronen is). Daarom wordt aangeraden om geen overdadig gebruik te
maken van generieke patronen.
Indien meerdere patronen een overeenkomst opleveren met hetzelfde echte symbool, krijgen
aliassen (eerst c++, dan symver) de voorkeur boven generieke patronen. Generieke patronen
worden vergeleken in de volgorde waarin zij aangetroffen worden in het
symbolenbestandsjabloon tot er een eerste succes volgt. Merk nochtans op dat het manueel
herordenen van items uit het sjabloonbestand niet aangeraden wordt, aangezien
dpkg-gensymbols diffs (weergave van de veranderingen) genereert op basis van de
alfanumerieke volgorde van hun namen.
Het gebruik van includes
Als de set van geëxporteerde symbolen onderling verschilt tussen verschillende
architecturen, kan het inefficiënt worden om één enkel symbolenbestand te gebruiken. In
die gevallen kan een include-opdracht op een aantal wijzen nuttig blijken:
• U kunt het gemeenschappelijke gedeelte afsplitsen in een extern bestand en dat bestand
opnemen in uw bestand pakket.symbols.arch met behulp van een include-opdracht op de
volgende manier:
#include "pakketten.symbols.common"
• Net zoals om het even welk symbool kan ook een include-opdracht tags krijgen:
(tag|...|tagN)#include "in-te-voegen-bestand"
Als gevolg daarvan zal er standaard van uitgegaan worden dat alle symbolen die uit
in-te-voegen-bestand opgenomen worden, gemarkeerd zijn met tag ... tagN. U kunt van
deze functionaliteit gebruik maken om een gemeenschappelijk bestand pakket.symbols te
maken waarin architectuurspecifieke symbolenbestanden opgenomen worden:
gemeenschappelijk_symbool1@Base 1.0
(arch=amd64 ia64 alpha)#include "pakket.symbolen.64bits"
(arch=!amd64 !ia64 !alpha)#include "pakket.symbolen.32bits"
gemeenschappelijk_symbool2@Base 1.0
De symbolenbestanden worden regel per regel gelezen en include-opdrachten worden verwerkt
van zodra ze tegengekomen worden. Dit betekent dat de inhoud van het ingevoegde bestand
eventueel zaken kan vervangen die voor de include-opdracht stonden en dat zaken die na de
opdracht komen, eventueel inhoud uit het ingevoegde bestand kunnen vervangen. Elk symbool
(of zelfs een andere #include-opdracht) uit het ingevoegde bestand kan bijkomende tags
opgeven of via zijn tag-vermeldingen waarden van de overgeërfde tags vervangen. Er bestaat
nochtans geen manier waarop een symbool eventueel overgeërfde tags zou kunnen verwijderen.
Een ingevoegd bestand kan de kopregel die de SONAME van de bibliotheek bevat, herhalen. In
dat geval vervangt het een eventueel eerder ingelezen kopregel. Het is over het algemeen
nochtans best om het dupliceren van kopregels te vermijden. Een manier om dat te doen is
de volgende:
#include "libding1.symbols.common"
arch_specifiek_symbool@Base 1.0
Goed beheer van bibliotheken
Een goed onderhouden bibliotheek heeft de volgende functionaliteit:
• 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;
• idealiter gebruikt zij symboolversienummering om ondanks interne wijzigingen en
API-uitbreidingen ABI-stabiliteit te bekomen;
• zij exporteert geen private symbolen (dergelijke symbolen kunnen de tag optional
krijgen om dat te omzeilen).
Bij het onderhoud van een symbolenbestand 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 onderhouder 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.
OPTIES
-Ppakketbouwmap
Zoek in pakketbouwmap in plaats van in debian/tmp.
-ppakket
Definieer de pakketnaam. Is vereist als meer dan één binair pakket vermeld wordt in
debian/control (of indien er geen bestand debian/control is).
-vversie
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.
-ebibliotheekbestand
Analyseer enkel de expliciet vermelde bibliotheken in plaats van alle publieke
bibliotheken te zoeken. U kunt in bibliotheekbestand gebruik maken van
shell-patronen met het oog op padnaamexpansie (zie de man-pagina File::Glob(3perl)
voor details) om met één enkel argument meerdere bibliotheken aan te duiden (anders
heeft u meerdere malen -e nodig).
-lmap Voeg 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.
Opmerking: gebruik deze optie in de plaats van het instellen van 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.
-Ibestandsnaam
Gebruik bestandsnaam als referentiebestand om het symbolenbestand te genereren dat
in het pakket zelf geïntegreerd wordt.
-O[bestandsnaam]
Geef het gegenereerde symbolenbestand uit weer op de standaarduitvoer of schrijf
het naar bestandsnaam als dat opgegeven werd, eerder dan naar
debian/tmp/DEBIAN/symbols (of pakketbouwmap/DEBIAN/symbols indien -P gebruikt
werd). Indien bestandsnaam reeds bestond, wordt de inhoud ervan gebruikt als basis
voor het gegenereerde symbolenbestand. U kunt van deze functionaliteit gebruik
maken om een symbolenbestand bij te werken zodat het in overeenstemming is met een
nieuwere toeleveraarsversie van uw bibliotheek.
-t Schrijf het symbolenbestand in sjabloonmodus eerder dan in de indeling die
compatibel is met 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
deb-symbols(5)-bestand sommige symbolen weggelaten worden (overeenkomstig de regels
voor het verwerken van tags), terwijl in een symbolenbestandsjabloon steeds alle
symbolen neergeschreven worden.
-c[0-4]
Definieer de controles die moeten gebeuren bij het vergelijken van het gegenereerde
symbolenbestand 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. Niveau 0
leidt nooit tot een mislukking. Niveau 1 mislukt als er symbolen verdwenen zijn.
Niveau 2 geeft een mislukking als nieuwe symbolen geïntroduceerd werden. Niveau 3
mislukt als er bibliotheken verdwenen zijn. Niveau 4 geeft een mislukking als
nieuwe bibliotheken geïntroduceerd werden.
Deze waarde kan vervangen worden door de omgevingsvariabele
DPKG_GENSYMBOLS_CHECK_LEVEL.
-q Gedraag u rustig en genereer nooit een diff (een overzicht van de verschillen)
tussen het gegenereerde symbolenbestand en het sjabloonbestand dat als vertrekpunt
gebruikt werd en toon geen enkele waarschuwing 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 -c).
-aarch Ga uit van arch als hostarchitectuur bij het verwerken van symbolenbestanden.
Gebruik deze optie om een symbolenbestand of een diff (overzicht van de
verschillen) voor een willekeurige architectuur te genereren op voorwaarde dat de
binaire bestanden ervan reeds voorhanden zijn.
-d Zet debug-modus aan. Talrijke berichten worden dan getoond om toe te lichten wat
dpkg-gensymbols doet.
-V Schakel de breedsprakige modus in. Het gegenereerde symbolenbestand 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.
-?, --help
Toon info over het gebruik en sluit af.
--version
Toon de versie en sluit af.
OMGEVING
DPKG_GENSYMBOLS_CHECK_LEVEL
Overschrijft het controleniveau van het commando, zelfs als het argument -c
opgegeven werd aan de commandoregel (merk op dat dit ingaat tegen de algemeen
geldende afspraak dat commandoregel-argumenten voorrang hebben op
omgevingsvariabelen).
DPKG_COLORS
Stelt de kleurmodus in (sinds dpkg 1.18.5). Waarden die momenteel gebruikt mogen
worden zijn: auto (standaard), always en never.
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: 0 and 1 (standaard).
ZIE OOK
https://people.redhat.com/drepper/symbol-versioning
https://people.redhat.com/drepper/goodpractice.pdf
https://people.redhat.com/drepper/dsohowto.pdf
deb-symbols(5), dpkg-shlibdeps(1).