När dessa filer skapas, används ett par symbolfiler från paketansvariga som indata. Programmet söker efter följande filer (och använder den första det finner):
Dessa filer är i huvudsak intressanta för att kunna tillhandahålla den minimala version associerad med varje symbol i biblioteken. Detta motsvarar normalt den första version av paketet som tillhandahöll symbolen, men det kan manuellt inkrementeras av de ansvariga om symbolens ABI utökas med bibehållen bakåtkompatibilitet. Det är den ansvarigas ansvar att hålla dessa filer àjourförda och korrekta, men dpkg-gensymbols kan hjälpa till med detta.
När den genererade symbolfilen skiljer sig mot den version som tillhandahållits av de paketansvariga kommer dpkg-gensymbols att skriva ut en differens mellan de två versionerna. Om ändringarna är för stora kommer programmet dessutom att misslyckas (du kan justera hur stora ändringar du kan tolerera, se flaggan -c).
Innan man applicerar en patch på symbolfilen bör de ansvariga dubbelchecka att den är korrekt. Publicerade symboler bör inte försvinna, så patchen bör ideellt sett bara lägga till nya rader.
Note that you can put comments in symbols files: any line with '#' as the first character is a comment except if it starts with '#include' (see section Using includes). Lines starting with '#MISSING:' are special comments documenting symbols that have disappeared.
Glöm inte att kontrollera om de gamla symbolversionerna måste ökas. Det finns inget sätt för dpkg-gensymbols att varna om detta. Att blint applicera diffen eller utgå från att inget har ändrats om diffen är tom, utan att se efter sådana ändringar, kan leda till att paket med lösa beroenden kan deklarera att de fungerar med äldre paket de inte kan fungera tillsammans med. Detta kommer introducera svårfunna problem vid (delvisa) uppgraderingar.{
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"@Bas 1.0
(optional)taggad_ociterad_symbol@Bas 1.0 1
ociterad_symbol@Bas 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.
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.
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.
The format of architecture-list is the same as the one used in the Build-Depends field of debian/control (except the enclosing square brackets []). For example, the first symbol from the list below will be considered only on alpha, any-amd64 and ia64 architectures, the second only on linux architectures, while the third one anywhere except on armel.
(arch=alpha any-amd64 ia64)64bit_specific_symbol@Base 1.0
(arch=linux-any)linux_specific_symbol@Base 1.0
(arch=!armel)symbol_armel_does_not_have@Base 1.0
The architecture-bits is either 32 or 64.
(arch-bits=32)32bit_specific_symbol@Base 1.0
(arch-bits=64)64bit_specific_symbol@Base 1.0
The architecture-endianness is either little or big.
(arch-endian=little)little_endian_specific_symbol@Base 1.0
(arch-endian=big)big_endian_specific_symbol@Base 1.0
Multiple restrictions can be chained.
(arch-bits=32|arch-endian=little)32bit_le_symbol@Base 1.0
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 skall 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:
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.
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.
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 t.ex "ng_mystack_new@Base" inte gör det. Det andra mönstret motsvarar alla symbolen som innehåller strängen "private" i sina namn och träffar kommer att ärva 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:
#include "paket.symbols.common"
(tag|...|tagN)#include "fil-att-inkludera"
Alla symboler som inkluderas från fil-att-inkludera kommer att anses som standard vara taggade med tag ... tagN. 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 SONAMNet 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
Ett välunderhållet bibliotek har följande funktioner:
När man underhåller symbolfilen är det lätt att upptäcka symboler som dyker upp och försvinner. Det är svårare att upptäcka inkompatibla API- och ABI-ändringar. Den paketansvarige bör därför noggrant läsa igenom uppströmsändringsloggen för fall då reglerna för god hantering av bibliotek bryts. Om ett möjligt fel upptäcks bör uppströmsförfattaren meddelas, då det alltid är bättre att problemet rättas uppströms än specifikt i Debian.
Observera: Använd den här flaggan istället för att sätta LD_LIBRARY_PATH, eftersom miljövariabeln används för att styra körtidslänkaren, och genom att utnyttja det för att ange sökvägen till delade bibliotek vid kompilering kan det uppstå problem, till exempel vid korskompilering.
Värdet kan överstyras med miljövariabeln DPKG_GENSYMBOLS_CHECK_LEVEL.