Provided by:
dpkg-dev_1.16.0.3ubuntu5_all 
NAMN
dpkg-gensymbols - generera symbolfiler (information om delade
bibliotek)
SYNOPS
dpkg-gensymbols [flaggor]
BESKRIVNING
dpkg-gensymbols soker genom en temporart byggtrad (som standard
debian/tmp) efter bibliotek och skapar en symbols-fil som beskriver
dem. Denna fil kommer sedan, savida den inte ar tom, att installeras i
DEBIAN-underkatalogen i byggtradet sa att den hamnar i
styrinformationen i paketet.
Nar dessa filer skapas, anvands ett par symbolfiler fran paketansvariga
som indata. Programmet soker efter foljande filer (och anvander den
forsta det finner):
o debian/paket.symbols.arkitektur
o debian/symbols.arkitektur
o debian/paket.symbols
o debian/symbols
Dessa filer ar i huvudsak intressanta for att kunna tillhandahalla den
minimala version associerad med varje symbol i biblioteken. Detta
motsvarar normalt den forsta version av paketet som tillhandaholl
symbolen, men det kan manuellt inkrementeras av de ansvariga om
symbolens ABI utokas med bibehallen bakatkompatibilitet. Det ar den
ansvarigas ansvar att halla dessa filer ajourforda och korrekta, men
dpkg-gensymbols kan hjalpa till.
Nar den genererade symbolfilen skiljer sig mot den version som
tillhandahallits av de paketansvariga kommer dpkg-gensymbols att skriva
ut en differens mellan de tva versionerna. Om andringarna ar for stora
kommer programmet dessutom att misslyckas (du kan justera hur stora
andringar du kan tolerera, se flaggan -c).
UNDERHoALLA SYMBOLFILER
Symbolfilerna ar bara riktigt nyttiga om de motsvarar hur paketet har
utvecklats over flera versioner. De paketansvariga maste darfor
uppdatera dem varje gang en ny symbol laggs till sa att dess
associerade minimala version motsvarar verkligheten. For att gora detta
pa ett riktigt satt finns det differensfiler i byggloggarna. I de
flesta fall kan differensfilen appliceras direkt pa filen debian/paket.
Med det i atanke sa behovs det oftast ytterligare justeringar: det
rekommenderas att skippa Debianrevisionen fran det minimala
versionsnummer sa att den bakatanpassningar med ett lagre
versionsnummer, men fran samma uppstromsversion, fortfarande uppfyller
de genererade beroendena. Om Debianrevisionen inte kan tas bort pa
grund av att en symbol faktiskt lades till av en Debianspecifik andring
sa bor ett "~" laggs till i slutet av versionen.
Innan man applicerar en patch pa symbolfilen bor de ansvariga
dubbelchecka att den ar korrekt. Publicerade symboler bor inte
forsvinna, sa patchen bor ideellt sett bara lagga till nya rader.
Anv"anda #PACKAGE#-substituering
I nagra sallsynta fall skiljer sig namnet pa biblioteket mellan
arkitekturer. For att undvika att hardkoda namnet pa paketet i
symbolfilen kan du anvanda markoren #PACKAGE#. Den ersatts av det
faktiska paketnamnet nar symbolfilen installeras. Till skillnad fran
#MINVER#-markoren kommer #PACKAGE# aldrig att dyka upp i en symbolfil i
ett binarpaket.
Anv"anda symboltaggar
Symboltaggning ar nyttigt for att markera symboler som ar speciella pa
nagot satt. Alla symboler kan ha ett godtyckligt antal taggar
associerade med sig. Medan alla taggar tolkas och lagras ar det bara
ett par av dem som forstas av dpkg-gensymbols och som utloser
specialhantering av symbolerna. Se undersymbolen Standardsymboltaggar
for mer information om dessa taggar.
Taggarna anges precis fore symbolnamnet (inga blanksteg tillats
mellan). Den borjar alltid med en vansterparentes (, slutar med en
hogerparentes ), och maste innehalla minst en tagg. Ytterligare taggar
avdelas med tecknet |. En tagg kan ha ett varde, vilket separeras fran
taggnamnet med tecknet =. Taggnamn och varden kan vara godtyckliga
strangar, forutom att de inte kan innehalla de speciella tecknen ) | =.
Symbolnamn som foljer en taggangivelse kan, om sa onskas, citeras med
antingen ' eller " for att tillata blanksteg. Om inga taggar anges for
symbolen tolkas dock citattecken som en del av symbolnamnet, vilket
fortsatter till det forsta blanksteget.
(tag1=jag ar markerad|taggnamn med blanksteg)"taggad citerad
symbol"@Bas 1.0
(optional)taggad_ociterad_symbol@Bas 1.0 1
ociterad_symbol@Bas 1.0
Den forsta symbolen i exemplet ar heter taggad citerad symbol och har
tva taggar: tag1 med vardet jag "ar markerad och taggnamn med blanksteg
som inte har nagot varde. Den andra symbolen heter
taggad_ociterad_symbol och ar bara taggad med taggen som heter
optional. Den sista symbolen ar ett exempel pa en normal, otaggad
symbol.
Eftersom symboltaggar er en utokning av formatet i deb-symbols(5) kan
de bara anvandas i symbolfiler i kallkodspaket (dessa filer ar att anse
som mallar som anvands for att bygga symbolfilerna som finns i
binarpaketen). Nar dpkg-gensymbols anropas utan flaggan -t kommer det
att mata ut symbolfiler kompatibla med deb-symbols(5)-formatet: det
hanterar symboler helt beroende pa vad som beskrivs av standardtaggarna
och tar bort alla taggar fran utdata. I mall-lage (-t) kommer daremot
alla symboler och deras taggar (bade standard och okanda) att behallas
i utdata och skrivas i sin originalform sa som de lastes in.
Standardsymboltaggar
optional
En symbol markerad som valfri (optional) kan forsvinna fran
bibliotektet nar som helst och kommer aldrig gora sa att
dpkg-gensymbols misslyckas. Forsvunna symboler kommer dock
fortfarande visas som saknade (MISSING) i differensen for varje
ny paketversion. Detta beteende fungerar som en paminnelse for
de paketansvariga om att symbolen maste tas bort fran
symbolfilen eller laggas tillbaka till biblioteket. Nar en
valfri symbol som tidigare markerats som saknad (MISSING)
plotsligt dyker upp igen i en senare version kommer den att
uppgraderas tillbaka till befintligstatus ("existing") med den
minsta tillgangliga versionen oforandrad.
Taggen ar anvandbar for symboler som ar privata och vars
forsvinnande inte gor att ABI:et gar sonder. De flesta
C++-mallinstansieringar faller till exempel in under denna
kategori. Som andra taggar kan den har aven ha ett godtyckligt
varde: det kan anvandas for att indikera varfor symbolen ar att
anse som valfri.
arch=arkitekturlista
Denna tag gor det mojligt att begransa vilken uppsattning
arkitekturer symbolen ar tankt att finnas for. Nar symbollistan
uppdateras med symboler som upptacks i biblioteket behandlas
alla arkitekturspecifika symboler som inte galler den aktuella
vardarkitekturen som om de inte fanns. Om en arkitekturspecifik
symbol som motsvarar den aktuella vardarkitekturen inte
existerar i biblioteket galler de vanliga reglerna for saknade
symboler, och kan fa dpkg-gensymbols att misslyckas. A andra
sidan, om en arkitekturspecifik symbol hittas dar den inte var
menad att finnas (da den aktuella vardarkitekturen inte ar
listad i taggen), gors den arkitekturneutral (dvs. "arch"-taggen
tas bort och symbolen kommer finnas med i differensen pa grund
av denna andring), men den anses inte som ny.
I det vanliga icke-mall-laget skrivs endast de
arkitekturspecifika symboler som motsvarar den aktuella
vardarkitekturen till symbolfilen. A andra sidan skrivs alla
arkitekturspecifika symboler (inklusive de fran andra
arkitekturer) till symbolfilen i mall-laget.
Formatet pa arkitekturlista ar detsamma som det som anvands i
Build-Depends-faltet i debian/control (bortsett fran de
omslutande hakparenteserna []). Den forsta symbolen fran listan
nedan, till exempel, kommer endast att tas med pa arkitekturerna
alpha, amd64, kfreebsd-amd64 och ia64, medan den andra tas med
overallt forutom pa armel.
(arch=alpha amd64 kfreebsd-amd64
ia64)en_64bit-specifik_symbol@Base 1.0
(arch=!armel)symbol_armel_inte_har@Base 1.0
ignore-blacklist
dpkg-gensymbols har en intern svartlista over symboler som inte
skall forekomma i symbolfiler eftersom de oftast bara ar
sidoeffekter fran implementationsdetaljer i verktygskedjan. Om
du, av nagon orsak, verkligen vill att en av dessa symboler
skall tas med i symbolfilen maste du tagga symbolen med
ignore-blacklist. Det kan vara nodvandigt for
lagniva-verktygskedjebibliotek som libgcc.
c++ Betecknar c++-symbolmonster. Se stycket Anv"anda symbolm"onster
nedan.
symver Anger symver (symbolversion)-symbolmonstret. Se stycket Anv"anda
symbolm"onster nedan.
regex Anger regex-symbolmonstret. Se stycket Anv"anda symbolm"onster
nedan.
Anv"anda symbolm"onster
Till skillnad fran vanliga symbolspecifikationer kan ett monster tacka
flera faktiska symboler fran biblioteket. dpkg-gensymbols kommer
forsoka matcha varje monster mot varje faktisk symbol som inte har en
motsvarande specifik symbol definierad i symbolfilen. Sa fort det
forsta monster som motsvarar symbolen hittas kommer alla dess taggar
och egenskaper att anvandas som en basspecifikation for symbolen. Om
inget monster motsvarar symbolen kommer den att tolkas som ny.
Ett monster anses som tappat om det inte motsvarar nagra symboler i
biblioteket. Som standard kommer detta fa dpkg-genchanges att
misslyckas om -c1 eller hogre anges. Om ett sadant misslyckande inte ar
onskvart kan monstret dock markas med taggen optional. Om monstret da
inte motsvarar nagonting kommer det bara dyka upp i differensen som
saknas (MISSING). Monstret kan dessutom, precis som andra symboler,
begransas till specifika arkitekturer med hjalp av arch-taggen. Se
stycket Standardsymboltaggar ovan for mer information.
Monster ar en utokning av deb-symbols(5)-formatet och ar darfor endast
tillatna i symbolfilmallar. Syntax for angivelse av monster skiljer sig
inte fran den for en specifik symbol. Symbolnamnsdelen av
specifikationen fungerar dock som ett uttryck som skall jamforas mot
namn@version for den faktiska symbolen. For att skilja mellan olika
sorters monster, taggas monster normalt med en speciell tagg.
For narvarande stoder dpkg-gensymbols tre grundlaggande monstertyper:
c++
Detta monster anges med taggen c++. Den matchar enbart C++-symboler
med deras avmanglade symbolnamn (som det skrivs ut av
c++filt(1)-verktyget). Det har monstret ar valdigt nyttigt for att
matcha symboler vars manglade namn kan skilja sig mellan olika
arkitekturer, medan deras avmanglade namn ar desamma. En grupp
dylika symboler ar icke-virtuella "thunks" som har
arkitekturspecifika offsetvarden inbyggda i sina manglade namn. En
vanlig instans av detta fall ar en virtuell destruktor som under
diamantarv behover en icke-virtuell "thunk"-symbol. Aven om till
exempel ZThn8_N3NSB6ClassDD1Ev@Base pa 32-bitarsarkitekturer
troligtvis ar _ZThn16_N3NSB6ClassDD1Ev@Base pa64-bitarsarkitekturer,
sa kan de matchas med ett enda c++-monster:
libdummy.so.1 libdummy1 #MINVER#
[...]
(c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
[...]
Det avmanglade namnet ovan kan hamtas genom att utfora foljande
kommando:
$ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt
Observera att aven om det manglade namnet per definition ar unikt i
biblioteket galler inte detta for avmanglade namn. Flera distinkta
verkliga symboler kan ha samma avmanglade namn. Det galler till
exempel for icke-virtuella "thunk"-symboler i konfigurationer med
komplexa arv eller for de flesta konstruktorer och destruktorer
(eftersom g++ normalt genererar tva symboler for dem). Eftersom
dessa kollisioner sker pa ABI-nivan bor de dock inte sanka
kvaliteten pa symbolfilen.
symver
Detta monster anges med taggen symver. Valunderhallna bibliotek har
versionshanterade symboler dar varje version motsvarar
uppstromsversionen dar symbolen lades till. Om det ar fallet kan du
anvanda ett symver-moster for 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 sistnamnda kommer leda
till ett minsta beroende pa libc6 version 2.2 trots att den
motsvarar monstret "(symver)GLIBC_2.0"-monstret, eftersom specifika
symboler galler fore monster.
Observera att aven om den gamla sortens jokerteckenmonster (anges
med "*@version" i symbolnamnfaltet) fortfarande stods sa
rekommenderas de inte langre i och med den nya sortens syntax
"(symver|optional)version". Till exempel bor "*@GLIBC_2.0 2.0"
skrivas som "(symver|optional)GLIBC_2.0 2.0" om samma beteende
behovs.
regex
Monster med reguljara uttryck anges med taggen regex. De matchar med
det reguljara uttrycket pa perl-form som anges i symbolnamnsfaltet.
Ett reguljart uttryck matchar som det star, glom darfor inte att
inleda det med tecknet ^, annars kommer det matcha godtycklig del av
den verkliga symbolens namn@version-strang. 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 traffas av det forsta monstret
medan t.ex "ng_mystack_new@Base" inte gor det. Det andra monstret
motsvarar alla symbolen som innehaller strangen "private" i sina
namn och traffar kommer att arva optional-taggen fran monstret.
Grundlaggande monster som anges ovan kan kombineras dar det ar vettigt.
I sa fall behandlas de i den ordning taggarna anges. Till exempel
kommer bade
(c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
(regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
att traffa symbolerna "_ZN3NSA6ClassA7Private11privmethod1Ei@Base" och
"_ZN3NSA6ClassA7Private11privmethod2Ei@Base". Nar det forsta monstret
jamfors avmanglas forst symbolen som en C++-symbol, varefter det
avmanglade namnet jamfors med det reguljara uttrycket. Nar det andra
monstret jamfors, a andra sidan, jamfors det reguljara uttrycket mot
det raa symbolnamnet, varefter symbolen testas for att se om det ar av
C++-typ genom att forsoka avmangla det. Om ett grundlaggande monster
misslyckas kommer hela uttrycket att misslyckas. Darfor kommer, till
exempel "__N3NSA6ClassA7Private11privmethod\dEi@Base" inte att traffas
av nagot av monstrena eftersom det inte ar en giltig C++-symbol.
I allmanhet delas alla monster in i tva grupper. alias (grundlaggande
c++ och symver) och generella monster (regex, samtliga kombinationer av
multipla grundlaggande monster). Det gar snabbt att traffa
grundlaggande aliasbaserade monster (O(1)) medan generella monster ar
O(N) (N - antal generella monster) for varje symbol. Det rekommenderas
darfor inte att anvanda for manga generella monster.
Nar flera monster traffar samma verkliga symbol foredras alias (forst
c++, sedan symver) framfor generella monster. Generella monster traffas
i den ordning de upptacktes i symbolfilmallen fram till den forsta
lyckade traffen. Observera dock att manuell omsortering av poster i
mallfilen inte rekommenderas da dpkg-gensymbols genererar
differensfiler baserad pa den alfanumeriska sorteringsordningen av dess
namn.
Anv"anda inkluderingar
Nar uppsattningen av exporterade symboler skiljer sig mellan
arkitekturer kan det vara ineffektivt att anvanda en enda symbolfil. I
dessa fall kan ett inkluderingsdirektiv vara nyttigt pa flera satt:
o Du kan faktorisera de gemensamma delarna i en extern fil och
inkludera den filen i din paket.symbols.arkitektur-fil genom att
anvanda ett inkluderingsdirektiv som detta:
#include "paket.symbols.common"
o Inkluderingsdirektivet kan aven taggas som alla andra symboler:
(tag|..|tagN)#include "fil_att_inkludera"
Alla symboler som inkluderas fran fil_att_inkludera kommer att
anses som standard vara taggade med tag .. tagN. Du kan anvanda
denna funktion for 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 lases radvis, och inkluderingsdirektiv utfors sa fort de
upptacks. Det betyder att innehallet i den inkluderade filen kan
overstyra allt innehall som forekom fore inkluderingsdirektivet och att
innehall efter direktivet kan overstyra allt fran den inkluderade
filen. Alla symboler (aven andra #include-direktiv) i den inkluderade
filen kan ange ytterligare taggar eller overstyra varden for de arvda
taggarna i sin taggspecifikation. Det finns dock inte nagot satt for en
symbol att ta bort nagon av sina arvda taggar.
En inkluderad fil kan repetera huvudraden som innehaller SONAMNet for
biblioteket. I sa fall overstyr den en eventuell huvudrad som lasts in
tidigare. Det ar vanligtvis dock bast att undvika att duplicera
huvudrader. Ett satt att gora det ar som foljer:
#include "libnagonting1.symbols.common"
arkitekturspecifik_symbol@Base 1.0
God hantering av bibliotek
Ett valunderhallet bibliotek har foljande funktioner:
o dess API ar stabilt (publika symboler tas aldrig bort, endast nya
publika symboler laggs till) och inkompatibla andringar gors endast
nar SONAMNet andras;
o ideellt anvander det en versionhanterade symboler for att
uppratthalla ABI-stabilitet trots interna andringar och
API-utokningar;
o det exporterar inte privata symboler (sadana symboler kan taggas
med "optional" for att ga runt detta).
Nar man underhaller symbolfilen ar det latt att upptacka symboler som
dyker upp och forsvinner. Det ar svarare att upptacka inkompatibla API-
och ABI-andringar. Den paketansvarige bor darfor noggrant lasa igenom
uppstromsandringsloggen for fall da reglerna for god hantering av
bibliotek bryts. Om ett mojligt fel upptacks bor uppstromsforfattaren
meddelas, da det alltid ar battre att problemet rattas uppstroms an
specifikt i Debian.
FLAGGOR
-Ppaketbyggkatalog
Sok paketbyggkatalog istallet for debian/tmp.
-ppaket
Definiera paketnamnet. Kravs om mer an ett binarpaket listas i
debian/control (eller om det inte finns nagon
debian/control-fil).
-vversion
Definiera paketversion. Standardvardet ar versionen som hamtas
fran debian/changelog. Kravs om programmet anropas utanfor ett
kallkodspakettrad.
-ebiblioteksfil
Analyserar endast bibliotek som listats explicit istallet for
att hitta alla publika bibliotek. Du kan anvanda ett reguljart
uttryck i biblioteksfil for att traffa multipla bibliotek med
ett enda argument (annars behover du flera -e).
-Ifilnamn
Anvand filnamn som referensfil for att generera symbolfilen som
integreras i sjalva paketet.
-O Skriv den genererade symbolfilen pa standard ut, i stallet for
att lagra den i paketets byggtrad.
-Ofilnamn
Lagra den genererade symbolfilen som filnamn. Om filnamn redan
existerar kommer dess innehall att anvandas som bas for den
genererade symbolfilen. Du kan anvanda den har funktionen for
att uppdatera en symbolfil sa att den motsvarar en nyare
uppstromsversion av ditt bibliotek.
-t Skriv symbolfilen i mall-lage istallet for i formatet
kompatibelt med deb-symbols(5). Huvudskillnaden ar att
symbolnamn och taggar skrivs i sin originalform i mall-laget,
till skillnad fran de efterbehandlade symbolnamnen med borttagna
taggar som skrivs i det kompatibla laget. Dessutom kan vissa
symboler uteslutas nar 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 utforas nar den genererade
symbolfilen jamfors med den mallfil som anvands som startpunkt.
Som standard ar nivan 1. Genom att oka nivan utfors flera
kontroller, inklusive alla kontroller pa lagre niva. Niva 2
misslyckas om nya symboler har introducerats. Niva 3 misslyckas
om nagra bibliotek har forsvunnit. Niva 4 misslyckas om nagra
bibliotek har introducerats.
Vardet kan overstyras med miljovariabeln
DPKG_GENSYMBOLS_CHECK_LEVEL.
-q Hall tyst och generera aldrig en differens mellan den genererade
symbolfilen och mallfilen som anvandes som startpunkt eller visa
varningar om nya/forlorade bibliotek eller nya/forlorade
symboler. Den har flaggan tar endast bort informationsutdata,
inte sjalva kontrolleran (se flaggan -c).
-aarkitektur
Anta arkitektur som vardarkitektur vid hantering av symbolfiler.
Anvand den har flaggan for att generera en symbolfil eller
differens for valfri arkitektur sa lange dess binarer ar
tillgangliga.
-d Aktiverar felsokningslage. Flera meddelanden visas for att
forklara vad dpkg-gensymbols gor.
-V Aktivera pratsamt lage. Den genererade symbolfilen innehaller ej
langre rekommenderade symboler som kommentarer. I mall-lage
foljs dessutom monstersymboler av kommentarer som visar vilka
verkliga symboler som har traffats av monstret.
-h, --help
Visar hjalpskarm och avslutar.
--version
Visar version och avslutar.
SE "AVEN
http://people.redhat.com/drepper/symbol-versioning
http://people.redhat.com/drepper/goodpractice.pdf
http://people.redhat.com/drepper/dsohowto.pdf
deb-symbols(5), dpkg-shlibdeps(1).
F"ORFATTARE
Upphovsrattsskyddat (C) 2007-2009 Raphael Hertzog
Detta ar fri programvara; se GNU General Public License version 2 eller
senare for kopieringsvillkor. Det finns INGEN GARANTI.
"OVERS"ATTNING
Peter Krefting och Daniel Nylander.