diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
commit | b86570f63e533abcbcb97c2572e0e5732a96307b (patch) | |
tree | cabc83be691530ae685c45a8bc7620ccc0e1ebdf /man/nl/deb-src-symbols.pod | |
parent | Initial commit. (diff) | |
download | dpkg-upstream.tar.xz dpkg-upstream.zip |
Adding upstream version 1.20.13.upstream/1.20.13upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | man/nl/deb-src-symbols.pod | 419 |
1 files changed, 419 insertions, 0 deletions
diff --git a/man/nl/deb-src-symbols.pod b/man/nl/deb-src-symbols.pod new file mode 100644 index 0000000..7e0a780 --- /dev/null +++ b/man/nl/deb-src-symbols.pod @@ -0,0 +1,419 @@ + + ***************************************************** + * 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 + +deb-src-symbols - Uitgebreid sjabloonbestand van Debian voor gedeelde +bibliotheken + +=head1 OVERZICHT + +B<debian/>I<pakket>B<.symbols.>I<arch>, B<debian/symbols.>I<arch>, +B<debian/>I<pakket>B<.symbols>, B<debian/symbols> + +=head1 BESCHRIJVING + +De symboolbestand-sjablonen worden geleverd met Debian bronpakketten en de +indeling ervan is een superverzameling van de symboolbestanden, geleverd in +binaire pakketten, zie L<deb-symbols(5)>. + +=head2 Commentaar + +Commentaar wordt ondersteund in sjabloonsymboolbestanden. Elke regel met ‘#’ +als eerste teken is een commentaarregel, behalve als die regel begint met +‘#include’ (zie het onderdeel over B<Het gebruik van includes>). Regels die +beginnen met ‘#MISSING:’ zijn een bijzondere vorm van commentaar waarin +symbolen die verdwenen zijn, gedocumenteerd worden. + +=head2 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 +symboolbestand te moeten inschrijven, kunt u gebruik maken van de marker +I<#PACKAGE#>. Die zal tijdens de installatie van de symboolbestanden +vervangen worden door de echte pakketnaam. In tegenstelling tot de marker +I<#MINVER#>, zal I<#PACKAGE#> nooit te vinden zijn in een symboolbestand +binnenin een binair pakket. + +=head2 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 B<dpkg-gensymbols>. Ze lokken een +speciale behandeling van de symbolen uit. Zie het onderdeel B<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 B<(> +en eindigt met het sluiten ervan B<)> en moet minstens één tag +bevatten. Meerdere tags worden onderling gescheiden door een +B<|>-teken. Elke tag kan een facultatieve waarde hebben die van de naam van +de tag gescheiden wordt door het teken B<=>. Namen van tags en waarden +kunnen arbitraire tekenreeksen zijn, behalve dat zij niet de speciale tekens +B<)> B<|> B<=> mogen bevatten. De symboolnaam die na een tagopgave komt kan +facultatief tussen aanhalingstekens geplaatst worden, ofwel met B<'> of met +B<">, 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 aangehaald symbool"@Base 1.0 + (optioneel)getagd_niet-aangehaald_symbool@Base 1.0 1 + niet-getagd_symbool@Base 1.0 +Het eerste symbool in het voorbeeld werd I<getagd en aangehaald symbool> +genoemd en heeft twee tags: I<tag1> met als waarde I<ik werd gemarkeerd> en +I<tagnaam met spatie> die geen waarde heeft. Het tweede symbool met als naam +I<getagd_niet-aangehaald_symbool> werd enkel gemarkeerd met de tag die +I<optioneel> als naam heeft. Het laatste symbool is een voorbeeld van een +normaal niet-getagd symbool. + +Aangezien symbooltags een uitbreiding zijn van het +B<deb-symbols>(5)-systeem, kunnen zij enkel deel uitmaken van de +symboolbestanden die in broncodepakketten gebruikt worden (die bestanden +moeten dan gezien worden als sjablonen die gebruikt worden om de +symboolbestanden te bouwen die in de binaire pakketten zitten). Indien +B<dpkg-gensymbols> aangeroepen wordt zonder de optie B<-t> zal het +symboolbestanden produceren die compatibel zijn met het +B<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 (B<-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. + +=head2 Standaard symbooltags + +=over + +=item B<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 B<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 symboolbestand 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. + +=item B<arch=>I<architectuurlijst> + +=item B<arch-bits=>I<architectuur-bits> + +=item B<arch-endian=>I<architectuur-endianness> + +Deze tags laten iemand toe om de set architecturen waarvoor het symbool +verondersteld wordt te bestaan, te beperken. De tags B<arch-bits> en +B<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 B<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 symboolbestand 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 +symboolbestand. + +De indeling voor de I<architectuurlijst> is dezelfde als die welke gebruikt +wordt voor het veld B<Build-Depends> van I<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)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 I<architectuur-bits> is ofwel B<32> of B<64>. + + (arch-bits=32)32bits_specifiek_symbool@Base 1.0 + (arch-bits=64)64bits_specifiek_symbool@Base 1.0 +De waarde van I<architectuur-endianness> is ofwel B<little> of B<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 +=item B<allow-internal> + +dpkg-gensymbols hanteert een lijst van interne symbolen die niet zouden +mogen voorkomen in symboolbestanden 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 symboolbestand, moet u het +symbool markeren met de tag B<allow-internal>. Dit kan nodig zijn voor +sommige gereedschapskistbibliotheken van lagere orde zoals “libgcc”. + +=item B<ignore-blacklist> + +Een verouderde alias voor B<allow-internal> (sinds dpkg 1.20.1, ondersteund +sinds dpkg 1.15.3). + +=item B<c++> + +Geeft een I<c++>-symboolpatroon aan. Zie hierna in de subsectie B<Het +gebruik van symboolpatronen>. + +=item B<symver> + +Geeft een I<symver> (symboolversie) symboolpatroon aan. Zie hierna in de +subsectie B<Het gebruik van symboolpatronen>. + +=item B<regex> + +Geeft een I<regex>-symboolpatroon aan. Zie hierna in de subsectie B<Het +gebruik van symboolpatronen>. + +=back + +=head2 Het gebruik van symboolpatronen + +Anders dan een standaardbeschrijving van een symbool, kan een patroon +meerdere echte symbolen uit de bibliotheek dekken. B<dpkg-gensymbols> zal +proberen om elk patroon te vergelijken met elk reëel symbool waarvoor in het +symboolbestand I<geen> specifiek symbooltegenhanger 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 B<-c1> of een hoger +niveau een mislukking van B<dpkg-gensymbols> uitlokken. Indien een +dergelijke mislukking echter onwenselijk is, kan het patroon gemarkeerd +worden met de tag I<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 I<arch>. Raadpleeg het onderdeel B<Standaard symbooltags> hierboven +voor meer informatie. + +Patronen vormen een uitbreiding van het B<deb-symbols>(5)-systeem en zijn +daarom enkel geldig in symboolbestand-sjablonen. 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 I<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 B<dpkg-gensymbols> drie fundamentele +patroontypes: + +=over + +=item B<c++> + +Dit patroon wordt met de tag I<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 +B<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 +I<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 I<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 symboolbestand. + +=item B<symver> + +Dit patroon wordt door de tag I<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 I<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". + +=item B<regex> + +Patronen in de vorm van reguliere expressies worden aangegeven met de tag +I<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 +I<^>. Anders kan ze een overeenkomst opleveren met om het even welk deel van +de tekenreeks I<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 I<optional> overerven +van het patroon. + +=back + +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 I<c++>- en I<symver>-patronen) en generieke +patronen (I<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 I<c++>, dan I<symver>) de voorkeur boven +generieke patronen. Generieke patronen worden vergeleken in de volgorde +waarin zij aangetroffen worden in het symboolbestand-sjabloon tot er een +eerste succes volgt. Merk nochtans op dat het manueel herordenen van items +uit het sjabloonbestand niet aangeraden wordt, aangezien B<dpkg-gensymbols> +diffs (weergave van de veranderingen) genereert op basis van de +alfanumerieke volgorde van hun namen. + +=head2 Het gebruik van includes + +Als de set van geëxporteerde symbolen onderling verschilt tussen +verschillende architecturen, kan het inefficiënt worden om één enkel +symboolbestand te gebruiken. In die gevallen kan een include-opdracht op een +aantal wijzen nuttig blijken: + +=over + +=item * + +U kunt het gemeenschappelijke gedeelte afsplitsen in een extern bestand en +dat bestand opnemen in uw bestand I<pakket>.symbols.I<arch> met behulp van +een include-opdracht op de volgende manier: + + #include "I<pakketten>.symbols.common" + +=item * + +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 I<in-te-voegen-bestand> opgenomen worden, gemarkeerd zijn met I<tag> +... I<tagN>. U kunt van deze functionaliteit gebruik maken om een +gemeenschappelijk bestand I<pakket>.symbols te maken waarin +architectuurspecifieke symboolbestanden opgenomen worden: + + gemeenschappelijk_symbool1@Base 1.0 + (arch=amd64 ia64 alpha)#include "pakket.symbols.64bit" + (arch=!amd64 !ia64 !alpha)#include "pakket.symbols.32bit" + gemeenschappelijk_symbool2@Base 1.0 + +=back + +De symboolbestanden 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 + +=head1 ZIE OOK + +B<deb-symbols>(5), B<dpkg-shlibdeps>(1), B<dpkg-gensymbols>(1). + |