table of contents
dpkg-gensymbols(1) | dpkg-verktygen | dpkg-gensymbols(1) |
NAMN¶
dpkg-gensymbols - generera symbolfiler (information om delade bibliotek)SYNOPS¶
dpkg-gensymbols [flagga...]BESKRIVNING¶
dpkg-gensymbols söker genom en temporärt byggträd (som standard debian/tmp) efter bibliotek och skapar en symbols-fil som beskriver dem. Denna fil kommer sedan, såvida den inte är tom, att installeras i DEBIAN-underkatalogen i byggträdet så att den hamnar i styrinformationen i paketet. 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):- •
- debian/paket.symbols.arkitektur
- •
- debian/symbols.arkitektur
- •
- debian/paket.symbols
- •
- debian/symbols
UNDERHÅLLA SYMBOLFILER¶
Symbolfilerna är bara riktigt nyttiga om de motsvarar hur paketet har utvecklats över flera versioner. De paketansvariga måste därför uppdatera dem varje gång en ny symbol läggs till så att dess associerade minimala version motsvarar verkligheten. För att göra detta på ett riktigt sätt finns det differensfiler i byggloggarna. I de flesta fall kan differensfilen appliceras direkt på filen debian/ paket. Med det i åtanke så behövs det oftast ytterligare justeringar: det rekommenderas att skippa Debianrevisionen från det minimala versionsnummer så att den bakåtanpassningar med ett lägre versionsnummer, men från samma uppströmsversion, fortfarande uppfyller de genererade beroendena. Om Debianrevisionen inte kan tas bort på grund av att en symbol faktiskt lades till av en Debianspecifik ändring så bör ett "~" läggs till i slutet av versionen. 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. Obsevera att du kan skriva kommentarer i symbols-filer: 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.Använda #PACKAGE#-substituering¶
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.Använda symboltaggar¶
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.
Standardsymboltaggar¶
- 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.
- arch=arkitekturlista
- Denna tag gör det möjligt att begränsa
vilken uppsättning arkitekturer symbolen är tänkt att
finnas för. 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), görs den
arkitekturneutral (dvs. "arch"-taggen tas bort och symbolen
kommer finnas med i differensen på grund av denna ändring), men
den anses inte som ny.
(arch=alpha any-amd64 ia64)a_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
- ignore-blacklist
- dpkg-gensymbols har en intern svartlista över symboler som inte skall förekomma i symbolfiler eftersom de oftast bara är sidoeffekter från implementationsdetaljer i verktygskedjan. Om du, av någon orsak, verkligen vill att en av dessa symboler skall tas med i symbolfilen måste du tagga symbolen med ignore-blacklist. Det kan vara nödvändigt för lågnivå-verktygskedjebibliotek som libgcc.
- 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.
Använda symbolmönster¶
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.- 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.
[...]
(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.
(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 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
(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.
(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.
Använda inkluderingar¶
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:
- •
- Inkluderingsdirektivet kan även taggas som alla andra
symboler:
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
arkitekturspecifik_symbol@Base 1.0
God hantering av bibliotek¶
Ett välunderhållet bibliotek har följande funktioner:- •
- dess API är stabilt (publika symboler tas aldrig bort, endast nya publika symboler läggs till) och inkompatibla ändringar görs endast när SONAMNet ändras;
- •
- ideellt använder det en versionhanterade symboler för att upprätthålla ABI-stabilitet trots interna ändringar och API-utökningar;
- •
- det exporterar inte privata symboler (sådana symboler kan taggas med "optional" för att gå runt detta).
FLAGGOR¶
- -Ppaketbyggkatalog
- Sök paketbyggkatalog istället för debian/tmp.
- -ppaket
- Definiera paketnamnet. Krävs om mer än ett binärpaket listas i debian/control (eller om det inte finns någon debian/control-fil).
- -vversion
- Definiera paketversion. Standardvärdet är versionen som hämtas från debian/changelog. Krävs om programmet anropas utanför ett källkodspaketträd.
- -ebiblioteksfil
- Analyserar endast bibliotek som listats explicit istället för att hitta alla publika bibliotek. Du kan använda ett jokertecken för filnamn (se manualsidan File::Glob) i biblioteksfil för att träffa multipla bibliotek med ett enda argument (annars behöver du flera -e).
- -Ifilnamn
- Använd filnamn som referensfil för att generera symbolfilen som integreras i själva paketet.
- -O
- Skriv den genererade symbolfilen på standard ut, i stället för att lagra den i paketets byggträd.
- -Ofilnamn
- Lagra den genererade symbolfilen som filnamn. Om filnamn redan existerar kommer dess innehåll att användas som bas för den genererade symbolfilen. Du kan använda den här funktionen för att uppdatera en symbolfil så att den motsvarar en nyare uppströmsversion av ditt bibliotek.
- -t
- Skriv symbolfilen i mall-läge istället för i formatet kompatibelt med deb-symbols(5). Huvudskillnaden är att symbolnamn och taggar skrivs i sin originalform i mall-läget, till skillnad från de efterbehandlade symbolnamnen med borttagna taggar som skrivs i det kompatibla läget. Dessutom kan vissa symboler uteslutas när en vanlig deb-symbols(5)-fil skrivs (i enlighet med tagghanteringsreglerna) medan alla symboler alltid skrivs till symbolfilsmallen.
- -c[0-4]
- Definiera vilka kontroller som skall utföras när
den genererade symbolfilen jämförs med den mallfil som
används som startpunkt. Som standard är nivån 1. Genom att
öka nivån utförs flera kontroller, inklusive alla
kontroller på lägre nivå. Nivå 2 misslyckas om nya
symboler har introducerats. Nivå 3 misslyckas om några bibliotek
har försvunnit. Nivå 4 misslyckas om några bibliotek har
introducerats.
- -q
- Håll tyst och generera aldrig en differens mellan den genererade symbolfilen och mallfilen som användes som startpunkt eller visa varningar om nya/förlorade bibliotek eller nya/förlorade symboler. Den här flaggan tar endast bort informationsutdata, inte själva kontrolleran (se flaggan -c).
- -aarkitektur
- Anta arkitektur som värdarkitektur vid hantering av symbolfiler. Använd den här flaggan för att generera en symbolfil eller differens för valfri arkitektur så länge dess binärer är tillgängliga.
- -d
- Aktiverar felsökningsläge. Flera meddelanden visas för att förklara vad dpkg-gensymbols gör.
- -V
- Aktivera pratsamt läge. Den genererade symbolfilen innehåller ej längre rekommenderade symboler som kommentarer. I mall-läge följs dessutom mönstersymboler av kommentarer som visar vilka verkliga symboler som har träffats av mönstret.
- -?, --help
- Visar hjälpskärm och avslutar.
- --version
- Visar version och avslutar.
SE ÄVEN¶
http://people.redhat.com/drepper/symbol-versioningÖVERSÄTTNING¶
Peter Krefting och Daniel Nylander.2012-04-22 | Debianprojektet |