dpkg-buildflags(1)

NAAM
dpkg-buildflags - geeft de bij pakketbouw te gebruiken bouwvlaggen terug

OVERZICHT
dpkg-buildflags [optie...] [commando]

BESCHRIJVING
dpkg-buildflags is gereedschap om de compilatievlaggen op te halen die tijdens het bouwen van Debian pakketten gebruikt moeten worden. De standaardvlaggen worden gedefinieerd door de leverancier, maar ze kunnen op verschillende manieren uitgebreid/vervangen worden:

1.  voor het hele systeem met /etc/dpkg/buildflags.conf;

2.  voor de huidige gebruiker met $XDG_CONFIG_HOME/dpkg/buildflags.conf, waarbij $XDG_CONFIG_HOME als standaardwaarde $HOME/.config heeft;

3.  tijdelijk door de gebruiker met omgevingsvariabelen (zie het onderdeel OMGEVING);

4.  dynamisch door de pakketonderhouder met omgevingsvariabelen die ingesteld worden via debian/rules (zie het onderdeel OMGEVING).

De configuratiebestanden kunnen twee types opdrachten bevatten:

SET vlag waarde
    Vervang de waarde van de vlag die vlag als naam heeft in waarde waarde.

STRIP vlag waarde
    Verwijder van de vlag die vlag als naam heeft alle bouwvlaggen die in waarde opgesomd worden.

APPEND vlag waarde
    Breid de vlag die vlag als naam heeft uit door er de opties aan toe te voegen die in waarde opgegeven worden. Er wordt een spatie geplaatst voor de waarde die toegevoegd wordt, indien de huidige waarde van de vlag niet leeg is.

PREPEND vlag waarde
    Breid de vlag die vlag als naam heeft uit door er vooraan de opties aan toe te voegen die in waarde opgegeven worden. Er wordt een spatie geplaatst achter de waarde die toegevoegd wordt, indien de huidige waarde van de vlag niet leeg is.

De configuratiebestanden kunnen commentaar bevatten op regels die beginnen met een hekje (#). Ook lege regels worden genegeerd.

COMMANDO'S

--dump
    Laat op standaarduitvoer alle compilatievlaggen en hun waarden zien. Dit geeft per regel één vlag en de waarde ervan weer met daartussenin een gelijkheidsteken (“vlag=waarde”). Dit is de standaardactie.

--list
    Geeft een lijst weer van vlaggen die door de huidige leverancier ondersteund wordt (één per regel). Zie het onderdeel ONDERSTEUNDE VLAGGEN voor meer informatie daarover.

--status
    Laat eventuele informatie zien die nuttig kan zijn om het gedrag te verklaren van dpkg-buildflags (sinds dpkg 1.16.5): relevante omgevingsvariabelen, huidige leverancier, toestand van alle functievlaggen. Geef ook de resulterende compileervlaggen met hun oorsprong weer. Het is de bedoeling dat dit uitgevoerd wordt vanuit debian/rules, zodat de bouwlog een duidelijk spoor van de gebruikte vlaggen kan bijhouden. Dit kan nuttig zijn om ermee verband houdende problemen te diagnosticeren.

--export=indeling
    Geef op standaarduitvoer commando's weer die gebruikt kunnen worden om alle compilatievlaggen te exporteren ten behoeve van een specifiek gereedschap. Indien de waarde indeling niet opgegeven werd, wordt sh verondersteld. Enkel compilatievlaggen die met een hoofdletter beginnen worden opgenomen. Van de andere wordt aangenomen dat ze niet bruikbaar zijn voor de omgeving. Ondersteunde indelingen:

    sh  Shell-opdrachten om alle compilatievlaggen in de omgeving in te stellen en te exporteren. Er worden aanhalingstekens geplaatst rond de vlagwaarden waardoor de uitvoer gereed is om door een shell geëvalueerd te worden.

    cmdline
        Argumenten om door te geven aan de commandoregel van een bouwprogramma om al de compilatievlaggen te gebruiken (sinds dpkg 1.17.0). De vlagwaarden worden volgens de shell-syntaxis tussen haakjes geplaatst.

    configure
        Dit is een verouderde alias voor cmdline.

    make
        Make-opdrachten om alle compilatievlaggen in de omgeving in te stellen en te exporteren. De uitvoer kan naar een makefile-fragment geschreven worden en geëvalueerd met behulp van een include-opdracht.

--get vlag
    Geef de waarde van de vlag weer op de standaarduitvoer. Sluit af met 0 bij een gekende vlag en sluit anders af met 1.

--origin vlag
    Geef de origine weer van de waarde die teruggegeven wordt door --get. Sluit af met 0 bij een gekende vlag en sluit anders af met 1. De origine kan één van de volgende waarden hebben:

    vendor
        de originele vlag die door de leverancier ingesteld werd, wordt teruggegeven;

    system
        de vlag werd ingesteld/gewijzigd door een systeemconfiguratie;

    user
        de vlag werd ingesteld/gewijzigd door een gebruikersspecifieke configuratie;

    env de vlag werd ingesteld/gewijzigd door een omgevingsspecifieke configuratie.

--query-features gebied
    Geef de functionaliteit weer die voor een opgegeven gebied geactiveerd is (sinds dpkg 1.16.2). Momenteel worden door Debian en zijn derivaten enkel de gebieden qa, reproducible, sanitize en hardening erkend. Zie het onderdeel FUNCTIONALITEITSGEBIEDEN voor meer details. Sluit af met 0 als het gebied gekend is, anders met 1.

    De uitvoer is in RFC822-indeling met één sectie per functie. Bijvoorbeeld:

      Feature: pie
      Enabled: no
      Feature: stackprotector
      Enabled: yes

--help
    Toon info over het gebruik en sluit af.

--version
    Toon de versie en sluit af.

ONDERSTEUNDE VLAGGEN

CFLAGS
    Opties voor de C-compiler. De door de leverancier ingestelde standaardwaarde bestaat uit -g en het standaardniveau van optimalisatie (gewoonlijk -O2, of -O0 indien de omgevingsvariabele DEB_BUILD_OPTIONS noopt aangeeft).

CPPFLAGS
    Opties voor de C-preprocessor. Standaardwaarde: leeg.

CXXFLAGS
    Opties voor de C++ compiler. Hetzelfde als CFLAGS.

OBJCFLAGS
    Opties voor de Objective C compiler. Hetzelfde als CFLAGS.

OBJCXXFLAGS
    Opties voor de Objective C++ compiler. Hetzelfde als CXXFLAGS.

GCJFLAGS
    Opties voor de GNU Java compiler (gcj). Een subset van CFLAGS.

FFLAGS
    Opties voor de Fortran 77 compiler. Een subset van CFLAGS.

FCFLAGS
    Opties voor de Fortran 9x compiler. Hetzelfde als FFLAGS.

LDFLAGS
    Opties die aan de compiler doorgegeven worden bij het linken van uitvoerbare programma's en gedeelde objecten (indien de linker rechtstreeks aangeroepen wordt, dan moeten -Wl en , van die opties verwijderd worden). Standaardwaarde: leeg.

In de toekomst kunnen nog andere vlaggen toegevoegd worden als daar behoefte aan ontstaat (bijvoorbeeld om andere talen te ondersteunen).

FUNCTIONALITEITSGEBIEDEN

Elke gebiedsfunctionaliteit kan in de gebiedswaarde van de omgevingsvariabelen DEB_BUILD_OPTIONS en DEB_BUILD_MAINT_OPTIONS ingeschakeld en uitgeschakeld worden met de schakelaars ‘+’ en ‘-’. Om bijvoorbeeld de hardening-functionaliteit “pie” te activeren en de functionaliteit “fortify” uit te schakelen, kunt u in debian/rules het volgende doen:

  export DEB_BUILD_MAINT_OPTIONS=hardening=+pie,-fortify

De bijzondere functionaliteit all (geldig in elk gebied) kan gebruikt worden om gelijktijdig alle gebiedsfunctionaliteit te activeren of uit te schakelen. Alles uitschakelen in het gebied hardening en enkel “format” en “fortify” activeren kunt u dus doen met:

  export DEB_BUILD_MAINT_OPTIONS=hardening=-all,+format,+fortify

  qa (kwaliteitsbevordering)
Er kunnen verschillende compilatieopties (die hierna beschreven worden) gebruikt worden om problemen in de broncode of het bouwsysteem te helpen detecteren.

bug This setting (disabled by default) adds any warning option that reliably detects problematic source code. The warnings are fatal. The only currently supported flags are CFLAGS and CXXFLAGS with flags set to -Werror=array-bounds, -Werror=clobbered, -Werror=implicit-function-declaration and -Werror=volatile-register-var.

canary
    Deze instelling (die standaard uitgeschakeld is) voegt loze kanarievogelopties toe aan de bouwvlaggen, zodat in de bouwlogs nagekeken kan worden hoe de bouwvlaggen doorgegeven worden en zodat het eventueel ontbreken van normale bouwvlaginstellingen ontdekt kan worden. Momenteel zijn de enige ondersteunde vlaggen CPPFLAGS, CFLAGS, OBJCFLAGS, CXXFLAGS en OBJCXXFLAGS, waarbij die vlaggen als -D__DEB_CANARY_vlag_willekeurige-id__ ingesteld worden, en LDFLAGS dat ingesteld wordt op -Wl,-z,deb-canary-willekeurige-id.

  sanitize (saneren)
Er kunnen verschillende compilatie-opties (die hierna beschreven worden) gebruikt worden om te helpen bij het gezond houden van een resulterend binair bestand op het vlak van geheugenvervuiling, geheugenlekkage, geheugengebruik na vrijgave, dataraces bij threads en bugs door ongedefinieerd gedrag.

address
    Deze instelling (standaard uitgeschakeld) voegt -fsanitize=address toe aan LDFLAGS en -fsanitize=address -fno-omit-frame-pointer aan CFLAGS en aan CXXFLAGS.

thread
    Deze instelling (standaard uitgeschakeld) voegt -fsanitize=thread toe aan CFLAGS, CXXFLAGS en LDFLAGS.

leak
    Deze instelling (standaard uitgeschakeld) voegt -fsanitize=leak toe aan LDFLAGS. Ze wordt automatisch uitgeschakeld als ofwel de address-functionaliteit of de thread-functionaliteit geactiveerd is, aangezien die dit impliceren.

undefined
    Deze instelling (standaard uitgeschakeld) voegt -fsanitize=undefined toe aan CFLAGS, CXXFLAGS en LDFLAGS.

  hardening (kwetsbaarheidsreductie)
Er kunnen verschillende compilatie-opties (die hierna beschreven worden) gebruikt worden om te helpen bij het versterken van een resulterend binair bestand tegen geheugenvervuilingsaanvallen of om bijkomende waarschuwingsberichten te geven tijdens het compileren. Behalve wanneer hierna anders aangegeven is, worden deze opties standaard geactiveerd voor architecturen die ze ondersteunen.

format
    Deze instelling (standaard geactiveerd) voegt -Wformat -Werror=format-security toe aan CFLAGS, CXXFLAGS, OBJCFLAGS en OBJCXXFLAGS. Dit zal waarschuwingen geven bij verkeerd gebruik van indelingstekenreeksen en zal mislukken als indelingsfuncties gebruikt worden op een manier die mogelijke veiligheidsproblemen tot gevolg kunnen hebben. Momenteel geeft dit een waarschuwing als een printf-functie of een scanf-functie aangeroepen wordt met een indelingstekenreeks die geen letterlijke tekenreeks is en er ook geen indelingsargumenten opgegeven werden, zoals bij printf(foo); in plaats van printf("%s", foo);. Dit kan een veiligheidslek zijn als de indelingstekenreeks afkomstig was van onbetrouwbare invoer en ‘%n’ bevat.

fortify
    Deze instelling (standaard geactiveerd) voegt -D_FORTIFY_SOURCE=2 toe aan CPPFLAGS. Tijdens het produceren van de code heeft de compiler een heleboel informatie over buffergroottes (waar mogelijk), en tracht een functieaanroep met een onveilige ongelimiteerde buffergrootte te vervangen door een functieaanroep met een gelimiteerde buffergrootte. Dit is in het bijzonder nuttig bij oude en slecht geschreven code. Daarnaast wordt het gebruik in het voor schrijven toegankelijk geheugen van indelingstekenreeksen die ‘%n’ bevatten, geblokkeerd. Indien een toepassing op een dergelijke indelingstekenreeks steunt, zal het er een alternatief voor moeten gebruiken. Merk op dat de code ook met -O1 of hoger gecompileerd moet worden opdat deze optie effect zou hebben. Indien de omgevingsvariabele DEB_BUILD_OPTIONS noopt bevat, dan wordt ondersteuning voor fortify uitgeschakeld. Dit is te wijten aan nieuwe waarschuwingen die gegeven worden door glibc 2.16 en hoger.

stackprotector
    Deze instelling (standaard geactiveerd als stackprotectorstrong niet gebruikt wordt) voegt -fstack-protector --param=ssp-buffer-size=4 toe aan CFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS en FCFLAGS. Dit voegt beveiligingscontroles tegen het overschrijven van de stack toe. Dit maakt dat bij veel mogelijke code-injectieaanvallen afgebroken wordt. In het beste geval wordt op die manier een kwetsbaarheid voor code-injectie omgebogen tot een denial-of-service (dienst niet beschikbaar) of een fictief probleem (afhankelijk van de toepassing). Deze functionaliteit vereist het linken van de code met glibc (of een andere aanbieder van __stack_chk_fail) en moet dus uitgeschakeld worden als er gebouwd wordt met -nostdlib of -ffreestanding of iets gelijkaardigs.

stackprotectorstrong
    Deze instelling (standaard geactiveerd) voegt -fstack-protector-strong toe aan CFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS en FCFLAGS. Dit is een sterkere variant van stackprotector, maar zonder noemenswaardig prestatieverlies. Het uitzetten van stackprotector schakelt ook deze functionaliteit uit. Deze functionaliteit stelt dezelfde vereisten als stackprotector en heeft daarenboven ook gcc 4.9 of een recentere versie nodig.

relro
    Deze instelling (standaard geactiveerd) voegt -Wl,-z,relro toe aan LDFLAGS. Tijdens het laden van het programma moet de linker in verschillende ELF-geheugensecties schrijven. Dit zet voor de programmalader een vlag zodat die deze secties alleen-lezen maakt alvorens de controle over te dragen aan het programma. Het meest noemenswaardige effect is dat dit aanvallen door het overschrijven van de Global Offset Table (GOT) voorkomt. Indien deze optie uitgeschakeld wordt, wordt ook bindnow uitgezet.

bindnow
    Deze instelling (standaard uitgeschakeld) voegt -Wl,-z,now toe aan LDFLAGS. Tijdens het laden van het programma worden alle dynamische symbolen omgezet, waardoor de volledige PLT (Procedure Linkage Table) als alleen lezen gemarkeerd kan worden (ten gevolge van relro hiervoor). Deze optie kan niet aangezet worden als relro niet geactiveerd is.

pie Deze instelling (standaard uitgeschakeld) voegt -fPIE toe aan CFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS en FCFLAGS, en -fPIE -pie aan LDFLAGS. Position Independent Executable (PIE - positie-onafhankelijk programma's) zijn nodig om voordeel te halen uit Address Space Layout Randomization (ASLR - de adresruimte rangschikken in toevallige volgorde), hetgeen door sommige kernelversies ondersteund wordt. Hoewel ASLR reeds voor datagebieden in de stack en de heap opgelegd kan worden (brk and mmap), moeten de codegebieden als positieonafhankelijk gecompileerd worden. Gedeelde bibliotheken doen dit reeds (-fPIC), waardoor zij automatisch ASLR krijgen, maar binaire .text-gebieden moeten als PIE gebouwd worden om ASLR te krijgen. Als dit gebeurt, worden aanvallen van het type ROP (Return Oriented Programming - op terugkeerwaarde georiënteerd programmeren) veel moeilijker aangezien er geen statische locaties meer zijn die bij een aanval van geheugenvervuiling als springplank gebruikt kunnen worden. Dit is niet compatibel met -fPIC. Daarom is bij het bouwen van gedeelde bibliotheken voorzichtigheid geboden. Static libraries can be used by programs or other shared libraries. Depending on the flags used to compile all the objects within a static library, these libraries will be usable by different sets of objects:

    none
        Cannot be linked into a PIE program, nor a shared library.

    -fPIE
        Can be linked into any program, but not a shared library.

    -fPIC
        Can be linked into any program and shared library.

    Unconditionally passing -fPIE, -fpie or -pie to a build-system using libtool is safe as these flags will get stripped when building shared libraries. Otherwise on projects that build both programs and shared libraries you might need to make sure that when building the shared libraries -fPIC is always passed last (so that it overrides any previous -PIE) to compilation flags such as CFLAGS, and -shared is passed last (so that it overrides any previous -pie) to linking flags such as LDFLAGS.

    Additionally, since PIE is implemented via a general register, some register starved architectures (but not including i386 anymore since optimizations implemented in gcc >= 5) can see performance losses of up to 15% in very text-segment-heavy application workloads; most workloads see less than 1%. Architectures with more general registers (e.g. amd64) do not see as high a worst-case penalty.

  reproducible (reproduceerbaar)
De hierna behandelde compilatieopties kunnen gebruikt worden om de bouwreproduceerbaarheid te helpen verbeteren of om bijkomende waarschuwingsberichten af te leveren tijdens het compileren. Behalve wanneer het hierna aangegeven wordt, worden deze opties standaard geactiveerd voor architecturen die ze ondersteunen.

timeless
    Deze instelling (standaard geactiveerd) voegt -Wdate-time toe aan CPPFLAGS. Dit leidt tot waarschuwingen als de macros __TIME__, __DATE__ en __TIMESTAMP__ gebruikt wordt.

fixdebugpath
    This setting (enabled by default) adds -fdebug-prefix-map=BUILDPATH=. to CFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS and FCFLAGS where BUILDPATH is set to the top-level directory of the package being built. This has the effect of removing the build path from any generated debug symbols.

OMGEVING
Er zijn twee sets omgevingsvariabelen die dezelfde operaties uitvoeren. De eerste (DEB_vlag_operatie) zou nooit gebruikt mogen worden binnen debian/rules. Die is bedoeld voor eventuele gebruikers die het bronpakket opnieuw willen bouwen met andere bouwvlaggen. De tweede set (DEB_vlag_MAINT_operatie) zou door pakketonderhouders enkel in debian/rules gebruikt moeten worden om de resulterende bouwvlaggen aan te passen.

DEB_vlag_SET
DEB_vlag_MAINT_SET
    Deze variabele kan gebruikt worden om de teruggegeven waarde voor de opgegeven vlag vlag af te dwingen.

DEB_vlag_STRIP
DEB_vlag_MAINT_STRIP
    Deze variabele kan gebruikt worden om in een lijst met witruimte als scheidingsteken opties op te geven die weggehaald zullen worden uit de set vlaggen die teruggegeven wordt voor de opgegeven vlag.

DEB_vlag_APPEND
DEB_vlag_MAINT_APPEND
    Deze variabele kan gebruikt worden om bijkomende opties toe te voegen aan de waarde die teruggegeven wordt voor de opgegeven vlag.

DEB_vlag_PREPEND
DEB_vlag_MAINT_PREPEND
    Deze variabele kan gebruikt worden om vooraan bijkomende opties toe te voegen aan de waarde die teruggegeven wordt voor de opgegeven vlag.

DEB_BUILD_OPTIONS
DEB_BUILD_MAINT_OPTIONS
    Deze variabelen kunnen door een gebruiker of een onderhouder gebruikt worden om diverse gebiedsfuncties die bouwvlaggen beïnvloeden, te activeren of uit te zetten. De variabele DEB_BUILD_MAINT_OPTIONS vervangt eventuele instellingen in de functionaliteitsgebieden DEB_BUILD_OPTIONS. Zie het onderdeel FUNCTIONALITEITSGEBIEDEN voor de details.

DEB_VENDOR
    This setting defines the current vendor. If not set, it will discover the current vendor by reading /etc/dpkg/origins/default.

DEB_BUILD_PATH
    This variable sets the build path (since dpkg 1.18.8) to use in features such as fixdebugpath so that they can be controlled by the caller. This variable is currently Debian and derivatives-specific.

BESTANDEN

  Configuratiebestanden

/etc/dpkg/buildflags.conf
    Configuratiebestand dat voor het hele systeem geldt.

$XDG_CONFIG_HOME/dpkg/buildflags.conf of
$HOME/.config/dpkg/buildflags.conf
    Configuratiebestand dat gebruikersafhankelijk is.

  Ondersteuning bij het maken van een pakket

/usr/share/dpkg/buildflags.mk
    Makefile-fragment dat alle vlaggen die door dpkg-buildflags ondersteund worden, laadt in variabelen (en eventueel exporteert) (sinds dpkg 1.16.1).

VOORBEELDEN
Om in een makefile bouwvlaggen door te geven aan een bouwcommando:

    $(MAKE) $(shell dpkg-buildflags --export=cmdline)
    ./configure $(shell dpkg-buildflags --export=cmdline)

Om in een shell-script of shell-fragment bouwvlaggen in te stellen, kan eval gebruikt worden om de uitvoer te interpreteren van en de vlaggen naar de omgeving te exporteren:

    eval "$(dpkg-buildflags --export=sh)" && make

of om de positieparameters in te stellen die aan een commando doorgegeven moeten worden:

    eval "set -- $(dpkg-buildflags --export=cmdline)"
    for dir in a b c; do (cd $dir && ./configure "$@" && make); done

  Het gebruik in debian/rules
Om de benodigde bouwvlaggen te bekomen die aan het bouwsysteem doorgegeven moeten worden, moet u vanuit het bestand debian/rules dpkg-buildflags aanroepen of buildflags.mk invoegen. Merk op dat oudere versies van dpkg-buildpackage (voor dpkg 1.16.1) deze vlaggen automatisch exporteerden. U zou hierop echter niet mogen betrouwen, aangezien dit het handmatig aanroepen van debian/rules defect maakt.

Voor pakketten met een autoconf-achtig bouwsysteem, kunt u de relevante opties rechtstreeks doorgeven aan configure of make(1), zoals hiervoor geïllustreerd werd.

Voor andere bouwsystemen, of indien u een meer fijnmazige controle nodig heeft over welke vlaggen waar doorgegeven worden, kunt u --get gebruiken. Of in de plaats daarvan kunt u buildflags.mk invoegen, dat zorgt voor het aanroepen van dpkg-buildflags en het opslaan van de bouwvlaggen in variabelen voor make.

Indien u alle bouwvlaggen naar de omgeving wenst te exporteren (waar ze door uw bouwsysteem opgepikt kunnen worden):

    DPKG_EXPORT_BUILDFLAGS = 1
    include /usr/share/dpkg/buildflags.mk

Als u bijkomende controle wenst over wat geëxporteerd wordt, kunt u de variabelen handmatig exporteren (aangezien er standaard geen enkele geëxporteerd wordt):

    include /usr/share/dpkg/buildflags.mk
    export CPPFLAGS CFLAGS LDFLAGS

En u kunt de vlaggen natuurlijk ook handmatig doorgeven aan commando's:

    include /usr/share/dpkg/buildflags.mk
    build-arch:
    	$(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)