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]
           Definiëren welke controles moeten gebeuren bij het vergelijken van het gegenereerde
           symboolbestand met het sjabloonbestand dat als vertrekpunt gebruikt werd. Standaard is
           dat volgens niveau 1. Het verhogen van het niveau leidt tot meer controles, terwijl
           alle controles van lagere niveaus behouden blijven.

           Niveau 0
               Leidt nooit tot een mislukking.

           Niveau 1
               Leidt tot een mislukking als sommige symbolen verdwenen zijn.

           Niveau 2
               Leidt tot een mislukking als sommige nieuwe symbolen geïntroduceerd werden.

           Niveau 3
               Leidt tot een mislukking als sommige bibliotheken verdwenen zijn.

           Niveau 4
               Leidt tot een mislukking als sommige nieuwe bibliotheken geïntroduceerd werden.

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