GIT-PBUILDER(1)

📦
version 0.9.43 · 6 versions
, in ubuntu stonking

👑 GIT-PBUILDER(1) 👑 (User Contributed Perl Documentation)

okay bestie, sit down, hydrate, grab a strawberry 🍓, because we're about to talk about git-pbuilder — that's the section 1 perl manual page, she's serving wrapper energy and she's genuinely so good at her job. no cap.

✨ NAME ✨

git-pbuilder — a wrapper around cowbuilder/qemubuilder for gbp buildpackage. that's it, that's the name, she's lowkey modest 💅

✨ SYNOPSIS ✨

two whole ways to call her, queen of options:

DIST=distribution ARCH=architecture [BUILDER=(pbuilder|qemubuilder)] \
    git-pbuilder debbuild-options
DIST=distribution ARCH=architecture [BUILDER=(pbuilder|qemubuilder)] \
    git-pbuilder (update | create | login) cowbuilder-options

like yes, you're setting environment variables right there in the command line, she's giving main character energy, we love a flexible icon 🎀

✨ DESCRIPTION ✨

so git-pbuilder is a wrapper around pdebuild, and she was literally made for gbp buildpackage to use. by default she configures pdebuild to use cowbuilder, passes all the appropriate options through to debbuild, and sets the base path for cowbuilder based on the environment variable DIST and — if you set it — the environment variable ARCH.

you can swap in qemubuilder instead by setting BUILDER to "qemubuilder", and you can pick pbuilder by setting BUILDER to "pbuilder". choose your fighter 💅

the default tea ☕

if you set nothing at all, git-pbuilder assumes the target distribution is "sid", the same architecture as the cowbuilder default, and she uses /var/cache/pbuilder/base-sid.cow if it exists. if it doesn't exist? she falls back to trying /var/cache/pbuilder/base.cow. she checks, bestie, she's thorough.

set DIST and its value becomes the target distribution, and /var/cache/pbuilder/base-dist.cow gets used instead. 🦋

special little detail: if DIST is "etch" or "ebo", then --debian-etch-workaround also gets passed to cowbuilder. not me knowing all the lore 😭

set ARCH and its value becomes the target architecture, and /var/cache/pbuilder/base-dist-arch.cow gets used — with dist being set to "sid" if DIST wasn't set. ✨

qemubuilder era 🧚

if qemubuilder is the builder, there's no base directory at all. instead qemubuilder gets invoked with the --config option pointing at this file:

/var/cache/pbuilder/qemubuilder-arch-dist.conf

no base dir, just vibes and a config file 🌈

pbuilder era 🫶

if pbuilder is the builder, git-pbuilder looks for /var/cache/pbuilder/base-sid.tgz by default, and /var/cache/pbuilder/base.tgz if that one doesn't exist.

if DIST or ARCH are set, they get used to form the expected name of the tgz file in exactly the same way they're used to form the expected base directory for cowbuilder. and similar to cowbuilder, --debian-etch-workaround gets passed to pbuilder if — judging from the DIST setting — it looks like the target distribution is etch. consistency queen 👑

if git-pbuilder is invoked via a name that starts with "git-*-", then the part between the hyphens gets taken as the default name of the builder to use.

⚠️ but heads up: "pbuilder" is mapped to cowbuilder for backward compatibility. so if you actually want to use pbuilder, you have to explicitly set BUILDER. no shortcuts, sorry bestie 😭

the part after the last hyphen gets taken as the default distribution (if it contains no additional hyphen) or as the default distribution followed by the default architecture (if it contains a hyphen).

so you can absolutely create symlinks like "git-pbuilder-squeeze" pointing to git-pbuilder and use that name when you want a distribution of "squeeze", or "git-qemubuilder-sid-armel" to use qemubuilder to build for the "armel" architecture and the "sid" distribution. iconic behavior honestly 💅

explicit settings of BUILDER, DIST, or ARCH always override any guesses from the command name. (but note that gbp buildpackage doesn't pass on environment variables when run with --git-pbuilder — see below, bestie, don't say I didn't warn you 🙈)

passing arguments around 💖

any arguments get passed as-is to dpkg-buildpackage via the --debbuildopts option to pdebuild. if you want to pass arguments to the builder instead, put them in the environment variable GIT_PBUILDER_OPTIONS. different door, different keys 🔑

turning off the autoconf magic ✋

to disable all attempts to discover the base path, tarball, or configuration file, and to disable setting up the pbuilder options — and instead just rely on the settings in .pbuilderrc — set GIT_PBUILDER_AUTOCONF to "no". she'll stop being nosy, promise.

how you actually use her 📝

normally, one does not run this script directly. instead, it's used as the builder script for gbp buildpackage via the --git-pbuilder command-line option.

when you run it that way, you should use the --git-dist, --git-arch, --git-qemubuilder, --git-pbuilder-autoconf, and --git-pbuilder-options flags instead of setting the DIST, ARCH, BUILDER, GIT_PBUILDER_AUTOCONF, and GIT_PBUILDER_OPTIONS environment variables. see gbp-buildpackage(1) for more info, she's got the full lore 📚

update / create / login 🛠️

alternately, git-pbuilder may be called with an argument of "update", "create", or "login". in this case, she calls cowbuilder (or the configured builder as described above) using sudo, and passes the corresponding command to the builder — using the same logic as above to determine the base directory and distribution.

if the distribution (set in DIST) ends in "-backports", one of these gets added as an --othermirror parameter to the builder:

deb http://ftp.debian.org/debian $DIST main
deb http://backports.debian.org/debian-backports $DIST main

the first one gets used for most distributions, and the second one is for "squeeze-backports". bespoke mirror handling, we love to see it ✨

and if the distribution ends in "-lts", this gets added as an --othermirror parameter to the builder:

deb http://ftp.debian.org/debian $DIST main

all so you can build for Long Term Support releases. LTS girlies rise 🌸

any additional arguments to git-pbuilder get passed along to the builder. and because of how sudo works, invoking the builder with an action will not read the user's .pbuilderrc by default — so in this case, git-pbuilder will add an explicit --configfile option pointing to the user's .pbuilderrc if it exists. she's got your back, fr fr 🫶

⚠️ if you use git-pbuilder with one of these arguments, you must have the "sudo" package installed, and you must configure sudo to let the current user run the appropriate builder command. no sudo setup, no build, that's the rule bestie 💀

✨ ENVIRONMENT ✨

she reads a LOT of environment variables. here's every single one, no skips:

  • ARCH — sets the target architecture. for a cowbuilder builder, this sets the base path and it's also passed as the --architecture option. with qemubuilder, this controls the path to the configuration file. with pbuilder, this sets the tgz path and is passed as --architecture. one variable, three different jobs, versatile icon
  • BUILDER — sets the builder to use. the only supported settings are "cowbuilder" (the default), "qemubuilder", and "pbuilder". that's the whole list, don't try anything cute 😌
  • COWBUILDER_BASE — set this environment variable to change the default location for the cowbuilder base directories (/var/cache/pbuilder). 🐄
  • DIST — sets the target distribution. used primarily to determine the base path for cowbuilder or pbuilder, or the configuration file path for qemubuilder — but it's also used to determine whether to pass --debian-etch-workaround to cowbuilder or pbuilder. multitasking queen 👑
  • GIT_PBUILDER_AUTOCONF — if set to "no", disable the logic that constructs the base path, tarball, or configuration file, plus all other logic to determine the options to pass to the builder. instead, just run the configured builder and assume its configuration is handled elsewhere (such as in .pbuilderrc). this also suppresses setting --buildresult, so the user will need to ensure that the configuration still puts packages where gbp buildpackage expects them. heads up, bestie, you're on your own for that part
  • GIT_PBUILDER_DEBUG — set this environment variable to get additional debugging output, like how cowbuilder is invoked. peek behind the curtain ✨
  • GIT_PBUILDER_OPTIONS — add additional options for the builder. these options are passed as-is to cowbuilder, qemubuilder, or pbuilder via pdebuild. the contents of this variable will undergo shell expansion, so any arguments containing shell metacharacters or whitespace need to be quoted in the value of the environment variable. ⚠️ quote your stuff, she means it
  • GIT_PBUILDER_OUTPUT_DIR — where to put the result of the build. the default is ".." (the parent directory). this setting is ignored if GIT_PBUILDER_AUTOCONF is set to "no". she said what she said 💅
  • GIT_PBUILDER_PDEBUILDOPTIONS — add additional options for pdebuild itself (such as --use-pdebuild-internal). the contents of this variable will undergo shell expansion, so any arguments containing shell metacharacters or whitespace need to be quoted in the value of the environment variable. same warning, same energy ⚠️
  • PBUILDER_BASE — set this environment variable to change the default location for the pbuilder tgz files (/var/cache/pbuilder) when BUILDER is set to "pbuilder". 🫶

✨ FILES ✨

every path she might touch, in order:

  • /var/cache/pbuilder/base-sid.cow
  • /var/cache/pbuilder/base.cow

the default cowbuilder --basepath directories, searched for in that order, if neither DIST nor ARCH is set. 🦋

  • /var/cache/pbuilder/base-sid-$ARCH.cow — the cowbuilder --basepath directory used if ARCH is set and DIST is not set.
  • /var/cache/pbuilder/base-$DIST.cow — the cowbuilder --basepath directory used if DIST is set and ARCH is not.
  • /var/cache/pbuilder/base-$DIST-$ARCH.cow — the cowbuilder --basepath directory used if DIST and ARCH are both set. the full combo, slay 💅
  • /var/cache/pbuilder/base-sid.tgz
  • /var/cache/pbuilder/base.tgz
  • /var/cache/pbuilder/base-sid-$ARCH.tgz
  • /var/cache/pbuilder/base-$DIST.tgz
  • /var/cache/pbuilder/base-$DIST-$ARCH.tgz

similar to the above, the pbuilder --basetgz path used for various settings of DIST and ARCH if BUILDER is set to "pbuilder". 🎀

  • /var/cache/pbuilder/qemubuilder-$ARCH-$DIST.conf — the qemubuilder --config file used. $ARCH defaults to "armel" and $DIST defaults to "sid" if not set. 🧚

✨ SEE ALSO ✨

go read these too, she's not jealous, she wants you educated:

cowbuilder(8), dpkg-buildpackage(1), gbp-buildpackage(1), pbuilder(8), pdebuild(1), qemubuilder(8), sudo(8)

the latest version of this script is available from http://www.eyrie.org/~eagle/software/scripts/ ✨

✨ AUTHOR ✨

Russ Allbery <eagle@eyrie.org> — the author, the legend, the icon 👑

and that's the whole page bestie!! 💖 this one came from perl v5.40.1, dated 2026-05-26 — bye bestie, go build something gorgeous, iykyk 🎀

📦 where this page comes from