deb-src-symbols - Debians utökade mallfil för delade bibliotek
debian/paket.symbols.ark,
debian/symbols.ark,
debian/paket.symbols,
debian/symbols
Symbolfilmallar medföljer Debiankällkodspaket och dess format
är en övermängd av symbols-filen som sänds med
Debianbinärpaket, se
deb-symbols(5).
Kommentarer stöds i symbolmallfilerna. Alla rader med ”#”
som första tecken är kommentarer, såvida inte det
börjar med ”#include” (se stycket
Använda
inkluderingar). Rader som börjar med ”#MISSING:”
är speciella kommentarer som dokumenterar symboler som har
försvunnit.
I några sällsynta fall skiljer sig namnet på biblioteket
mellan arkitekturer. För att undvika att hårdkoda namnet
på paketet i symbolfilen kan du använda markören
#PACKAGE#. Den ersätts av det faktiska paketnamnet när
symbolfilen installeras. Till skillnad från
#MINVER#-markören kommer
#PACKAGE# aldrig att dyka upp i
en symbolfil i ett binärpaket.
Symboltaggning är nyttigt för att markera symboler som är
speciella på något sätt. Alla symboler kan ha ett
godtyckligt antal taggar associerade med sig. Medan alla taggar tolkas och
lagras är det bara ett par av dem som förstås av
dpkg-gensymbols och som utlöser specialhantering av symbolerna.
Se undersymbolen
Standardsymboltaggar för mer information om
dessa taggar.
Taggarna anges precis före symbolnamnet (inga blanksteg tillåts
mellan). Den börjar alltid med en vänsterparentes
(,
slutar med en högerparentes
), och måste innehålla
minst en tagg. Ytterligare taggar avdelas med tecknet
|. En tagg kan ha
ett värde, vilket separeras från taggnamnet med tecknet
=. Taggnamn och värden kan vara godtyckliga strängar,
förutom att de inte kan innehålla de speciella tecknen
)
| =. Symbolnamn som följer en taggangivelse kan, om
så önskas, citeras med antingen
' eller
"
för att tillåta blanksteg. Om inga taggar anges för
symbolen tolkas dock citattecken som en del av symbolnamnet, vilket
fortsätter till det första blanksteget.
(tag1=jag är markerad|taggnamn med blanksteg)"taggad citerad symbol"@Base 1.0
(optional)taggad_ociterad_symbol@Base 1.0 1
otaggad_symbol@Base 1.0
Den första symbolen i exemplet är heter
taggad citerad
symbol och har två taggar:
tag1 med värdet
jag
är markerad och
taggnamn med blanksteg som inte har
något värde. Den andra symbolen heter
taggad_ociterad_symbol och är bara taggad med taggen som heter
optional. Den sista symbolen är ett exempel på en normal,
otaggad symbol.
Eftersom symboltaggar er en utökning av formatet i
deb-symbols (5) kan de bara användas i
symbolfiler i källkodspaket (dessa filer är att anse som mallar
som används för att bygga symbolfilerna som finns i
binärpaketen). När
dpkg-gensymbols anropas utan flaggan
-t kommer det att mata ut symbolfiler kompatibla med
deb-symbols(5)-formatet: det hanterar symboler helt beroende på
vad som beskrivs av standardtaggarna och tar bort alla taggar från
utdata. I mall-läge (
-t) kommer däremot alla symboler
och deras taggar (både standard och okända) att behållas
i utdata och skrivas i sin originalform så som de lästes in.
- optional
- En symbol markerad som valfri (optional) kan
försvinna från bibliotektet när som helst och kommer
aldrig göra så att dpkg-gensymbols misslyckas.
Försvunna symboler kommer dock fortfarande visas som saknade
(MISSING) i differensen för varje ny paketversion. Detta beteende
fungerar som en påminnelse för de paketansvariga om att
symbolen måste tas bort från symbolfilen eller läggas
tillbaka till biblioteket. När en valfri symbol som tidigare
markerats som saknad (MISSING) plötsligt dyker upp igen i en senare
version kommer den att uppgraderas tillbaka till befintligstatus
(”existing”) med den minsta tillgängliga versionen
oförändrad.
Taggen är användbar för symboler som är privata
och vars försvinnande inte gör att ABI:et går
sönder. De flesta C++-mallinstansieringar faller till exempel in
under denna kategori. Som andra taggar kan den här även ha
ett godtyckligt värde: det kan användas för att
indikera varför symbolen är att anse som valfri.
-
arch=arkitekturlista
-
arch-bits=arkitekturlista
-
arch-endian=arkitektur-byteordning
- Dessaa taggar gör det möjligt att
begränsa vilken uppsättning arkitekturer symbolen är
tänkt att finnas för. Taggarna arch-bits och
arch-endian stöds sedan dpkg 1.18.0. När symbollistan
uppdateras med symboler som upptäcks i biblioteket behandlas alla
arkitekturspecifika symboler som inte gäller den aktuella
värdarkitekturen som om de inte fanns. Om en arkitekturspecifik
symbol som motsvarar den aktuella värdarkitekturen inte existerar i
biblioteket gäller de vanliga reglerna för saknade symboler,
och kan få dpkg-gensymbols att misslyckas. Å andra
sidan, om en arkitekturspecifik symbol hittas där den inte var
menad att finnas (då den aktuella värdarkitekturen inte
är listad i taggen eller inte motsvarar byteordningen eller antal
bitar), görs den arkitekturneutral (dvs. taggarna arch, arch-bits
och arch-endgian tas bort och symbolen kommer finnas med i differensen
på grund av denna ändring), men den anses inte som ny.
I det vanliga icke-mall-läget skrivs endast de arkitekturspecifika
symboler som motsvarar den aktuella värdarkitekturen till
symbolfilen. Å andra sidan skrivs alla arkitekturspecifika symboler
(inklusive de från andra arkitekturer) till symbolfilen i
mall-läget.
Formatet på arkitekturlista är detsamma som det som
används i Build-Depends-fältet i
debian/control (bortsett från de omslutande hakparenteserna
[]). Den första symbolen från listan nedan, till exempel,
kommer endast att tas med på arkitekturerna alpha, valfri-amd64,
ia64, den andra bara på linux-arkitekturer medan den tredje tas med
överallt förutom på armel.
(arch=alpha any-amd64 ia64)64bitarsspecifik_symbol@Base 1.0
(arch=linux-any)linuxspecifik_symbol@Base 1.0
(arch=!armel)symbol_armel_inte_har@Base 1.0
I<architecture-bits> är antingen B<32> eller B<64>.
(arch-bits=32)32bitarsspecifik_symbol@Base 1.0
(arch-bits=64)64bitarsspecifik_symbol@Base 1.0
architecture-byteordning är antingen little eller
big.
(arch-endian=little)little_endianspecifik_symbol@Base 1.0
(arch-endian=big)big_endianspecifik_symbol@Base 1.0
Flera begränsningar kan kedjas samman
(arch-bits=32|arch-endian=little)32bitars_le_symbol@Base 1.0
- allow-internal
- dpkg-gensymbols har en intern svartlista över
symboler som inte ska förekomma i symbolfiler eftersom de oftast
bara är sidoeffekter från implementationsdetaljer i
verktygskedjan (sedan dpkg 1.20.1). Om du, av någon orsak,
verkligen vill att en av dessa symboler ska tas med i symbolfilen
måste du tagga symbolen med allow-internal. Det kan vara
nödvändigt för
lågnivå-verktygskedjebibliotek som
”libgcc”.
- ignore-blacklist
- Ett alias för allow-internal som
avråds från (sedan dpkg 1.20.1, stöds sedan dpkg
1.15.3).
- c++
- Betecknar c++-symbolmönster. Se stycket
Använda symbolmönster nedan.
- symver
- Anger symver (symbolversion)-symbolmönstret.
Se stycket Använda symbolmönster nedan.
- regex
- Anger regex-symbolmönstret. Se stycket
Använda symbolmönster nedan.
Till skillnad från vanliga symbolspecifikationer kan ett mönster
täcka flera faktiska symboler från biblioteket.
dpkg-gensymbols kommer försöka matcha varje
mönster mot varje faktisk symbol som
inte har en motsvarande
specifik symbol definierad i symbolfilen. Så fort det första
mönster som motsvarar symbolen hittas kommer alla dess taggar och
egenskaper att användas som en basspecifikation för symbolen. Om
inget mönster motsvarar symbolen kommer den att tolkas som ny.
Ett mönster anses som tappat om det inte motsvarar några symboler
i biblioteket. Som standard kommer detta få
dpkg-genchanges att
misslyckas om
-c1 eller högre anges. Om ett sådant
misslyckande inte är önskvärt kan mönstret dock
märkas med taggen
optional. Om mönstret då inte
motsvarar någonting kommer det bara dyka upp i differensen som saknas
(MISSING). Mönstret kan dessutom, precis som andra symboler,
begränsas till specifika arkitekturer med hjälp av
arch-taggen. Se stycket
Standardsymboltaggar ovan för mer
information.
Mönster är en utökning av
deb-symbols(5)-formatet och är
därför endast tillåtna i symbolfilmallar. Syntax
för angivelse av mönster skiljer sig inte från den
för en specifik symbol. Symbolnamnsdelen av specifikationen fungerar
dock som ett uttryck som ska jämföras mot
namn@version
för den faktiska symbolen. För att skilja mellan olika sorters
mönster, taggas mönster normalt med en speciell tagg.
För närvarande stöder
dpkg-gensymbols tre
grundläggande mönstertyper:
- c++
- Detta mönster anges med taggen c++. Den
matchar enbart C++-symboler med deras avmanglade symbolnamn (som det
skrivs ut av c++filt(1)-verktyget). Det här mönstret
är väldigt nyttigt för att matcha symboler vars
manglade namn kan skilja sig mellan olika arkitekturer, medan deras
avmanglade namn är desamma. En grupp dylika symboler är
icke-virtuella ”thunks” som har arkitekturspecifika
offsetvärden inbyggda i sina manglade namn. En vanlig instans av
detta fall är en virtuell destruktör som under diamantarv
behöver en icke-virtuell ”thunk”-symbol. Även
om till exempel ZThn8_N3NSB6ClassDD1Ev@Base på
32-bitarsarkitekturer troligtvis är _ZThn16_N3NSB6ClassDD1Ev@Base
på64-bitarsarkitekturer, så kan de matchas med ett enda
c++-mönster:
libdummy.so.1 libdummy1 #MINVER#
[...]
(c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
[...]
Det avmanglade namnet ovan kan hämtas genom att utföra följande kommando:
$ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt
Observera att även om det manglade namnet per definition är
unikt i biblioteket gäller inte detta för avmanglade namn.
Flera distinkta verkliga symboler kan ha samma avmanglade namn. Det
gäller till exempel för icke-virtuella
”thunk”-symboler i konfigurationer med komplexa arv eller
för de flesta konstruktörer och destruktörer
(eftersom g++ normalt genererar två symboler för dem).
Eftersom dessa kollisioner sker på ABI-nivån bör de
dock inte sänka kvaliteten på symbolfilen.
- symver
- Detta mönster anges med taggen symver.
Välunderhållna bibliotek har versionshanterade symboler
där varje version motsvarar uppströmsversionen där
symbolen lades till. Om det är fallet kan du använda ett
symver-möster för att matcha alla symboler som
matchar den specifika versionen. Till exempel:
libc.so.6 libc6 #MINVER#
(symver)GLIBC_2.0 2.0
[...]
(symver)GLIBC_2.7 2.7
access@GLIBC_2.0 2.2
Alla symboler associerade med versionerna GLIBC_2.0 och GLIBC_2.7 kommer leda till den minimal version 2.0 respektive 2.7, med undantag av symbolen access@GLIBC_2.0. Den sistnämnda kommer leda till ett minsta beroende på libc6 version 2.2 trots att den motsvarar mönstret "(symver)GLIBC_2.0"-mönstret, eftersom specifika symboler gäller före mönster.
Observera att även om den gamla sortens jokerteckenmönster
(anges med "*@version" i symbolnamnfältet) fortfarande
stöds så rekommenderas de inte längre i och med den
nya sortens syntax "(symver|optional)version". Till exempel
bör "*@GLIBC_2.0 2.0" skrivas som
"(symver|optional)GLIBC_2.0 2.0" om samma beteende
behövs.
- regex
- Mönster med reguljära uttryck anges med
taggen regex. De matchar med det reguljära uttrycket
på perl-form som anges i symbolnamnsfältet. Ett
reguljärt uttryck matchar som det står, glöm
därför inte att inleda det med tecknet ^, annars
kommer det matcha godtycklig del av den verkliga symbolens
namn@version-sträng. Till exempel:
libdummy.so.1 libdummy1 #MINVER#
(regex)"^mystack_.*@Base$" 1.0
(regex|optional)"private" 1.0
Symboler som "mystack_new@Base", "mystack_push@Base", "mystack_pop@Base" osv. kommer att träffas av det första mönstret medan "ng_mystack_new@Base" inte gör det. Det andra mönstret motsvarar alla symboler som innehåller strängen "private" i sina namn och träffar kommer att ärva I<optional>-taggen från mönstret.
Grundläggande mönster som anges ovan kan kombineras där det
är vettigt. I så fall behandlas de i den ordning taggarna anges.
Till exempel kommer både:
(c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
(regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
att träffa symbolerna "_ZN3NSA6ClassA7Private11privmethod1Ei@Base" och "_ZN3NSA6ClassA7Private11privmethod2Ei@Base". När det första mönstret jämförs avmanglas först symbolen som en C++-symbol, varefter det avmanglade namnet jämförs med det reguljära uttrycket. När det andra mönstret jämförs, å andra sidan, jämförs det reguljära uttrycket mot det råa symbolnamnet, varefter symbolen testas för att se om det är av C++-typ genom att försöka avmangla det. Om ett grundläggande mönster misslyckas kommer hela uttrycket att misslyckas. Därför kommer, till exempel "__N3NSA6ClassA7Private11privmethod\dEi@Base" inte att träffas av något av mönstrena eftersom det inte är en giltig C++-symbol.
I allmänhet delas alla mönster in i två grupper. alias
(grundläggande
c++ och
symver) och generella
mönster (
regex, samtliga kombinationer av multipla
grundläggande mönster). Det går snabbt att träffa
grundläggande aliasbaserade mönster (
O(1)) medan generella
mönster är O(N) (N - antal generella mönster) för
varje symbol. Det rekommenderas därför inte att använda
för många generella mönster.
När flera mönster träffar samma verkliga symbol
föredras alias (först
c++, sedan
symver)
framför generella mönster. Generella mönster
träffas i den ordning de upptäcktes i symbolfilmallen fram till
den första lyckade träffen. Observera dock att manuell
omsortering av poster i mallfilen inte rekommenderas då
dpkg-gensymbols genererar differensfiler baserad på den
alfanumeriska sorteringsordningen av dess namn.
När uppsättningen av exporterade symboler skiljer sig mellan
arkitekturer kan det vara ineffektivt att använda en enda symbolfil. I
dessa fall kan ett inkluderingsdirektiv vara nyttigt på flera
sätt:
- •
- Du kan faktorisera de gemensamma delarna i en extern fil
och inkludera den filen i din paket.symbols.arkitektur-fil
genom att använda ett inkluderingsdirektiv som detta:
#include "I<paket>.symbols.common"
- •
- Inkluderingsdirektivet kan även taggas som alla
andra symboler:
(tagg|...|taggN)#include "fil-att-inkludera"
Alla symboler som inkluderas från fil-att-inkludera kommer att
anses som standard vara taggade med tagg ... taggN. Du kan
använda denna funktion för att skapa en gemensam
paket.symbols-fil som inkluderar arkitekturspecifika filer:
gemensam_symbol1@Base 1.0
(arch=amd64 ia64 alpha)#include "paket.symbols.64bit"
(arch=!amd64 !ia64 !alpha)#include "paket.symbols.32bit"
gemensam_symbol2@Base 1.0
Symbolfilerna läses radvis, och inkluderingsdirektiv utförs
så fort de upptäcks. Det betyder att innehållet i den
inkluderade filen kan överstyra allt innehåll som förekom
före inkluderingsdirektivet och att innehåll efter direktivet
kan överstyra allt från den inkluderade filen. Alla symboler
(även andra #include-direktiv) i den inkluderade filen kan ange
ytterligare taggar eller överstyra värden för de
ärvda taggarna i sin taggspecifikation. Det finns dock inte
något sätt för en symbol att ta bort någon av sina
ärvda taggar.
En inkluderad fil kan repetera huvudraden som innehåller SONAME:t
för biblioteket. I så fall överstyr den en eventuell
huvudrad som lästs in tidigare. Det är vanligtvis dock
bäst att undvika att duplicera huvudrader. Ett sätt att
göra det är som följer:
#include "libnågonting1.symbols.common"
arkitekturspecifik_symbol@Base 1.0
=head1 SE ÄVEN
deb-symbols(5),
dpkg-shlibdeps(1),
dpkg-gensymbols(1).
Peter Krefting och Daniel Nylander.