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

       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).

       Programmet introducerades i dpkg 1.14.8.

UNDERHÅLLA SYMBOLFILER

       Det grundläggande utväxlingsformatet för symbolfilen beskrivs i deb-symbols(5), vilket
       används av symbolfilerna som inkluderas i bärpaket. Dessa genereras från mallsymbolfiler
       med ett format som baseras på det tidigare nämnda, beskrivet i deb-src-symbols(5) och
       inkluderas i källkodspaket.

       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.

       Diffarna som inkluderas i byggloggarna kan användas som en startpunkt, men den
       paketansvarige måste dessutom se till att beteendet för symbolerna inte har ändrats på ett
       sätt som gör att något som använder symbolerna och länkar mot den nya versionen slutar
       fungera med den gamla versionen.Diffarna som finns i byggloggarna kan användas som
       startpunkt, men paketansvariga måste dessutom se till att beteendet på dessa symboler inte
       på något sätt har ändrat sig på ett sådant sätt att något som använder symbolerna och
       länkar mot den nya versionen slutar fungera med den gamla versionen.

       I de flesta fall kan differensfilen appliceras direkt på filen debian/paket.symbols. Med
       det i åtanke så behövs det oftast ytterligare justeringar: det rekommenderas till exempel
       att skippa Debianrevisionen från det minimala versionsnummer så att bakåtanpassningar med
       ett lägre versionsnummer, men med 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.

       Observera att du kan lägga in kommentarer i symbolfilerna

       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.{

   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 SONAME ä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).

       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.

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 för
           detaljer) i biblioteksfil för att träffa multipla bibliotek med ett enda argument
           (annars behöver du flera -e).

       -lkatalog
           Lägg till katalog till först i listan över kataloger som ska eftersökas efter privata
           delade bibliotek (sedan dpkg 1.19.1). Flaggan kan användas flera gånger.

           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.

       -Ifilnamn
           Använd filnamn som referensfil för att generera symbolfilen som integreras i själva
           paketet.

       -O[filnamn]
           Visa den genererade symbolfilen på standard ut eller spara som filnamn om det anges,
           istället för debian/tmp/DEBIAN/symbols (eller paketbyggkatalog/DEBIAN/symbols om -P
           användes). 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 ska 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å 0
               Misslyckas aldrig.

           Nivå 1
               Misslyckas om några symboler har försvunnit.

           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.

           Värdet kan överstyras med miljövariabeln DPKG_GENSYMBOLS_CHECK_LEVEL.

       -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.

MILJÖVARIABLER

       DEB_HOST_ARCH
           Sets the host architecture if the --arch option has not be specified.

       DPKG_GENSYMBOLS_CHECK_LEVEL
           Överstyr kommandokontrollnivån, även om kommandoradsflaggan -c gavs (observera att
           detta går mot den normala konventionen att kommandoardsflaggor har företräde över
           miljövariabler).

       DPKG_COLORS
           Väljer färgläge (sedan dpkg 1.18.5). För närvarande godtas följande värden: auto
           (förval), always och never.

       DPKG_NLS
           Om satt, används för att bestämma om lokalt språkstöd ska aktiveras, även känt som
           internationaliseringsstöd (eller i18n) (sedan dpkg 1.19.0). Tillåtna värden är: 0 och
           1 (förval).

SE ÄVEN

       <https://people.redhat.com/drepper/symbol-versioning>,
       <https://people.redhat.com/drepper/goodpractice.pdf>,
       <https://people.redhat.com/drepper/dsohowto.pdf>, deb-src-symbol(5), deb-symbols(5),
       dpkg-shlibdeps(1).

ÖVERSÄTTNING

       Peter Krefting och Daniel Nylander.