NAAM

       dpkg-gensymbols - symboolbestanden genereren (informatie over afhankelijkheidsrelaties met gedeelde
       bibliotheken)

OVERZICHT

       dpkg-gensymbols [optie...]

BESCHRIJVING

       dpkg-gensymbols doorzoekt een tijdelijke bouwboom (standaard is dat debian/tmp) op zoek naar bibliotheken
       en genereert een symbols-bestand dat ze beschrijft. Dit bestand wordt dan als het niet leeg is,
       geïnstalleerd in een onderliggende map van de bouwboom met de naam DEBIAN, zodat het uiteindelijk
       opgenomen geraakt in de controle-informatie van het pakket.

       Bij het genereren van deze bestanden gebruikt het als invoer bepaalde symboolbestanden die door de
       onderhouder aangeleverd worden. Het zoekt naar de volgende bestanden (en gebruikt het eerste dat gevonden
       wordt):

       •   debian/pakket.symbols.arch

       •   debian/symbols.arch

       •   debian/pakket.symbols

       •   debian/symbols

       Het hoofddoel van deze bestanden is aan te geven welke de minimale versie is die behoort bij elk van de
       symbolen die door de bibliotheken aangeleverd worden. Gewoonlijk komt dit overeen met de eerste versie
       van het pakket dat in dat symbool voorzag, maar dit kan door de onderhouder manueel verhoogd worden
       indien de ABI van het symbool uitgebreid werd zonder dat daardoor de neerwaartse compatibiliteit
       verbroken wordt. Het is de verantwoordelijkheid van de onderhouder om deze bestanden up-to-date en
       accuraat te houden, maar dpkg-gensymbols helpt hierbij.

       Indien het gegenereerde symboolbestand verschilt van datgene wat de onderhouder aanlevert, zal dpkg-
       gensymbols de verschillen tussen de twee versies tonen in diff-formaat. Bovendien kan dit zelfs tot een
       mislukking leiden als de verschillen te significant zijn (u kunt aanpassen hoeveel verschil u kunt
       tolereren; zie de optie -c).

HET ONDERHOUD VAN SYMBOOLBESTANDEN

       De basisuitwisselingsindeling van het symboolbestand wordt beschreven in deb-symbols(5), hetgeen gebruikt
       wordt door de symboolbestanden uit de binaire pakketten. Deze worden gegenereerd uit
       sjabloonsymboolbestanden met een indeling gebaseerd op het eerste, beschreven in deb-src-symbols(5) en
       opgenomen in broncodepakketten.

       De symboolbestanden zijn pas echt nuttig als ze de evolutie van het pakket reflecteren doorheen
       verschillende releases. De onderhouder moet ze dus iedere keer bijwerken wanneer een nieuw symbool
       toegevoegd wordt, zodat de minimale versie die eraan gekoppeld wordt, overeenkomt met de realiteit.

       De diffs (weergave van de verschillen) die in de bouwlogs te vinden zijn, kunnen als startpunt genomen
       worden, maar daarbovenop moet de onderhouder erop letten dat het gedrag van deze symbolen niet zodanig
       veranderd werd, dat iets dat van deze symbolen gebruik maakt en linkt met de nieuwe versie, niet stopt
       met werken met de oude versie.

       In de meeste gevallen kan de diff rechtstreeks toegepast worden op het bestand debian/pakket.symbols. Dit
       gezegd zijnde, zijn verdere aanpassingen meestal wel nodig: het wordt bijvoorbeeld aanbevolen om het
       Debian revisienummer weg te laten uit de minimale versie, zodat backports (nieuwere programmaversies die
       geschikt gemaakt worden voor een vroegere release) met een lager versienummer maar eenzelfde
       bovenstroomse versie nog steeds voldoen aan de gegenereerde afhankelijkheidsrelaties. Indien het Debian
       revisienummer niet weggelaten kan worden omdat het symbool echt via een Debian-specifieke aanpassing
       toegevoegd werd, moet men aan het versienummer het achtervoegsel ‘~’ toevoegen.

       Vooraleer een patch toe te passen op een symboolbestand, moet de onderhouder grondig controleren of dat
       wel correct is. Publieke symbolen worden verondersteld niet te verdwijnen. Een patch zou dus idealiter
       enkel nieuwe regels mogen toevoegen.

       Merk op dat u in symboolbestanden commentaar kunt invoegen.

       Vergeet niet na te gaan of oudere symboolversies niet verhoogd moeten worden. Er bestaat geen manier voor
       dpkg-gensymbols om in dit verband waarschuwingen te geven. Een diff (weergave van de verschillen)
       blindweg toepassen of ervan uitgaan dat er niets aangepast moet worden als er geen diff is zonder zelf op
       eventuele wijzigingen te controleren, kan leiden tot pakketten met verslapte afhankelijkheidsrelaties die
       onterecht laten veronderstellen dat ze met oudere pakketten kunnen samenwerken. Dit kan bij
       (gedeeltelijke) opwaarderingen leiden tot moeilijk te vinden bugs.

   Goed beheer van bibliotheken
       Een goed onderhouden bibliotheek heeft de volgende functionaliteit:

       •   haar API is stabiel (publieke symbolen worden nooit verwijderd, enkel worden nieuwe publieke symbolen
           toegevoegd) en zij ondergaat enkel op een incompatibele manier veranderingen als de SONAME verandert;

       •   idealiter gebruikt zij symboolversienummering om ondanks interne wijzigingen en API-uitbreidingen
           ABI-stabiliteit te bekomen;

       •   zij exporteert geen private symbolen (dergelijke symbolen kunnen de tag optional krijgen om dat te
           omzeilen).

       Bij het onderhoud van een symboolbestand is het gemakkelijk om het verschijnen en verdwijnen van symbolen
       op te merken. Maar het is moeilijker om incompatibele API- en ABI-wijzigingen op te merken. Daarom moet
       de onderhouder het changelog-bestand van de toeleveraar grondig nakijken op situaties waarbij de regels
       van goed bibliotheekbeheer geschonden worden. Indien mogelijke problemen ontdekt worden, zou de
       toeleverende auteur erover ingelicht moeten worden, aangezien een reparatie op het niveau van de
       toeleveraar altijd te verkiezen valt boven een Debian-specifieke tijdelijke oplossing.

OPTIES

       -Ppakketbouwmap
           Zoek in pakketbouwmap in plaats van in debian/tmp.

       -ppakket
           Definieer de pakketnaam. Is vereist als meer dan één binair pakket vermeld wordt in debian/control
           (of indien er geen bestand debian/control is).

       -vversie
           Definieer de pakketversie. Standaard is dat de versie die uit debian/changelog gehaald wordt. Is
           vereist indien het aanroepen gebeurt van buiten de boom van het broncodepakket.

       -ebibliotheekbestand
           Analyseer enkel de expliciet vermelde bibliotheken in plaats van alle publieke bibliotheken te
           zoeken. U kunt in bibliotheekbestand gebruik maken van shell-patronen met het oog op padnaamexpansie
           (zie de man-pagina File::Glob(3perl) voor details) om met één enkel argument meerdere bibliotheken
           aan te duiden (anders heeft u meerdere malen -e nodig).

       -lmap
           Voeg map vooraan toe aan de lijst van mappen waarin naar private gedeelde bibliotheken gezocht moet
           worden (sinds dpkg 1.19.1). Deze optie kan meermaals gebruikt worden.

           Opmerking: gebruik deze optie in de plaats van het instellen van LD_LIBRARY_PATH, aangezien die
           omgevingsvariabele gebruikt wordt om de runtime linker aan te sturen. Daarvan misbruik maken om de
           paden van gedeelde bibliotheken in te stellen tijdens het bouwen van het programma, kan problematisch
           zijn, bijvoorbeeld bij het cross-compileren.

       -Ibestandsnaam
           Gebruik bestandsnaam als referentiebestand om het symboolbestand te genereren dat in het pakket zelf
           geïntegreerd wordt.

       -O[bestandsnaam]
           Het gegenereerde symboolbestand weergeven op de standaarduitvoer of schrijven naar bestandsnaam als
           dat opgegeven werd, eerder dan naar debian/tmp/DEBIAN/symbols (of pakketbouwmap/DEBIAN/symbols indien
           -P gebruikt werd). Indien bestandsnaam reeds bestond, wordt de inhoud ervan gebruikt als basis voor
           het gegenereerde symboolbestand. U kunt van deze functionaliteit gebruik maken om een symboolbestand
           bij te werken zodat het in overeenstemming is met een nieuwere bovenstroomse versie van uw
           bibliotheek.

       -t  Het symboolbestand in sjabloonmodus opschrijven, eerder dan in de indeling die compatibel is met deb-
           symbols(5). Het grootste verschil is dat in de sjabloonmodus symboolnamen en tags geschreven worden
           in hun originele vorm in tegenstelling tot in de compatibele modus waarin de verwerkte symboolnamen
           ontdaan van hun tags gebruikt worden. Daarenboven kunnen bij het schrijven van een standaard deb-
           symbols(5)-bestand sommige symbolen weggelaten worden (overeenkomstig de regels voor het verwerken
           van tags), terwijl in een symboolbestand-sjabloon steeds alle symbolen neergeschreven worden.

       -c[0-4]
           Define the checks to do when comparing the generated symbols file with the template file used as
           starting point. By default the level is 1. Increasing levels do more checks and include all checks of
           lower levels.

           Level 0
               Never fails.

           Level 1
               Fails if some symbols have disappeared.

           Level 2
               Fails if some new symbols have been introduced.

           Level 3
               Fails if some libraries have disappeared.

           Level 4
               Fails if some libraries have been introduced.

           Deze waarde kan vervangen worden door de omgevingsvariabele DPKG_GENSYMBOLS_CHECK_LEVEL.

       -q  Stil blijven en nooit een diff (een overzicht van de verschillen) maken tussen het gegenereerde
           symboolbestand en het sjabloonbestand dat als vertrekpunt gebruikt werd en geen enkele waarschuwing
           tonen in verband met nieuwe/verloren bibliotheken of nieuwe/verloren symbolen. Deze optie schakelt
           enkel de informatieve uitvoer uit, maar niet de controles zelf (zie de optie -c).

       -aarch
           Uitgaan van arch als host-architectuur bij het verwerken van symboolbestanden. Gebruik deze optie om
           een symboolbestand of een diff (overzicht van de verschillen) voor een willekeurige architectuur te
           genereren op voorwaarde dat de binaire bestanden ervan reeds voorhanden zijn.

       -d  Debug-modus aanzetten. Talrijke berichten worden dan getoond om toe te lichten wat dpkg-gensymbols
           doet.

       -V  De breedsprakige modus inschakelen. Het gegenereerde symboolbestand bevat dan verouderde symbolen in
           de vorm van commentaar. In sjabloonmodus worden daarenboven patroonsymbolen gevolgd door commentaar
           met daarin een opsomming van de echte symbolen die met het patroon overeenkwamen.

       -?, --help
           Info tonen over het gebruik en afsluiten.

       --version
           De versie tonen en afsluiten.

OMGEVING

       DPKG_GENSYMBOLS_CHECK_LEVEL
           Overschrijft het controleniveau van het commando, zelfs als het argument -c opgegeven werd aan de
           commandoregel (merk op dat dit ingaat tegen de algemeen geldende afspraak dat commandoregel-
           argumenten voorrang hebben op omgevingsvariabelen).

       DPKG_COLORS
           Stelt de kleurmodus in (sinds dpkg 1.18.5). Waarden die momenteel gebruikt mogen worden zijn: auto
           (standaard), always en never.

       DPKG_NLS
           Indien dit ingesteld is, zal het gebruikt worden om te beslissen over het activeren van
           moedertaalondersteuning, ook gekend als internationaliseringsondersteuning (of i18n) (sinds dpkg
           1.19.0). Geldige waarden zijn: 0 and 1 (standaard).

ZIE OOK

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