pbuilderrc(5)

💖 pbuilderrc(5) — the config files for personal package builder, bestie 💖

okay so real talk: this is the pbuilderrc manual, from the pbuilder family, and it's the one that tells you how to configure your build life. it's long, so buckle up. part 1 starts now ✨

---

🌸 NAME 🌸

pbuilderrc — configuration files for personal package builder 💅

---

🦋 DESCRIPTION 🦋

/etc/pbuilderrc is where the default values live — the ones pbuilder reaches for whenever it gets invoked. no cap.

the file itself gets sourced by a shell script, so bestie, it must follow shell script conventions. it's not vibing like a config file, it's vibing like shell. periodt.

the environment variable PBUILDER_OPERATION holds the current operation mode of pbuilder, and you can use it to do conditional configuration. the possible values are:

• build
• clean
• create
• debuild
• dumpconfig
• execute
• login
• update

---

✨ FORMAT ✨

this is the main character section, so let's go one by one 👑

• APTCACHE=/var/cache/pbuilder/aptcache — where the packages that apt downloads get cached. set this to "" and caching is fully turned off. bye cache 💀
• APTCACHEHARDLINK=yes — whether apt cache handling uses hard links. flip it to no and hard linking is disabled, and the files get copied instead.

heads up: it's advised to set this to no if you're using user-mode-linux. fr fr.

• APTCONFDIR=/etc/apt — says where the apt configuration files get copied from. by default this value is empty, which lets the usual configuration options do their thing. setting this variable overrides other options, so watch it 👀
• ARCHITECTURE=dpkg --print-architecture`` — the build architecture, as described in dpkg-architecture(1). it's the architecture used when creating the chroot, and it defaults to the system one. the supported values are the ones debootstrap supports, iykyk.
• AUTOCLEANAPTCACHE=yes — always run with the --autocleanaptcache option. always. no exceptions.
• AUTO_DEBSIGN=yes — when this is set to yes, pdebuild will invoke the debsign command after building 🫶
• BASETGZ=/var/cache/pbuilder/base.tgz — the default location for the archived chroot image to be created and used. this gets overridden by the --basetgz option.
• BINDMOUNTS=directories-to-bind-mount[:internal-mountpoint] — when this is set, pbuilder will mount these directories using bind-mount. different directories are space separated, and a colon can optionally specify a mount destination inside the chroot.

do not bind-mount /. i'm serious, bestie 🙈

an example, copy it exactly:

BINDMOUNTS="/home /mnt/test /home/joe/repo:/var/repo"

• BUILDDIR=/build — the directory inside the chroot where the build happens. this directory will contain the build products; the source packages get unpacked in a subdirectory inside it, named $srcpkg-$ver, with $ver being the upstream part of the version, without epoch and debian revision.

attention! some directories — like /tmp — are not safe to use, because they can be world-writable, and external users can temper with the build process. not the vibe you want 😭

• BUILDPLACE=/var/cache/pbuilder/build/ — the default place where the chroot gets constructed. pbuilder will use the directory $BUILDPLACE$$, which means it uses the directory and the PID to figure out which directory to use. that should get you a unique directory for concurrent runs of pbuilder on one machine.

it's not guaranteed to happen on network shared drives, so be aware of that fact when you're playing with this option on NFS shared beowulf clusters. change it to something like /var/cache/pbuilder/build/$HOSTNAME/ when you're doing that kind of thing 🌈

also: pbuilder clean cleans up this directory. iconic.

• BUILDRESULT=/var/cache/pbuilder/result/ — the default directory that the build result gets copied over to after the building.

unlike the --buildresult command-line option, the path is not canonicalized, so you should specify a full path, not a relative path. noted 📝

• EATMYDATA=no — enable or disable the builtin eatmydata support. for this to work, the library of the same architecture as the one inside the chroot has to be installed on the host.
• CCACHEDIR= — where ccache keeps its cached compiler output. if this is specified, ccache will be installed upon pbuilder create or pbuilder update, /usr/lib/ccache will be prepended to the PATH, CCACHEDIR will be bind-mounted in the chroot, and CCACHE_DIR (the ccache variable) will be set to CCACHEDIR. note that files in CCACHEDIR are chowned to BUILDUSERID (1234 by default). ccache is disabled by default.
• BUILDRESULTUID=
• BUILDRESULTGID=

set the UID and GID of the files built as result. they probably need to be set to numeric UID values, so that it works the same inside the chroot and outside the chroot.

if sudo is used, the values specified by sudo are used. they are SUDO_UID and SUDO_GID. the default value is 0.

• BUILDSOURCEROOTCMD=fakeroot — this option is used on invocation of fakeroot for dpkg-buildpackage in pdebuild.
• BUILDUSERID=1234 — the uid to be used inside the chroot. it should ideally not collide with the user-id outside the chroot, so you avoid the user inside the chroot having access to processes owned by the user id outside the chroot. safety first 🎀
• BUILDUSERNAME=pbuilder — the user name of the user the build will run as. specifying this will enable the use of fakeroot inside pbuilder.

note that this will require fakeroot to be installed within the chroot, and fakeroot will automatically be installed. and -rfakeroot will be added to DEBBUILDOPTS. cute, it does it for you 💅

• COMPONENTS=main — the default distribution components to use. this option is space-delimited, so use quotes when listing multiple components. this option only affects when doing pbuilder create or when --override-config is specified for the pbuilder update option.
• COMPRESSPROG=gzip — the program to use for compression of the base.tgz. the default is to use gzip, and any program that can be used to compress data using a pipe can be used.
  • if set to "pigz", compression and decompression is gzip compatible but will use all available CPUs.
  • if set to "cat", there will be no compression at all (so compression/decompression will be a lot faster but takes much more space on the disk).
• export http_proxy=http://your-proxy:8080/ — defines the proxy for http connection 🌐
• export DEBIAN_BUILDARCH=athlon — uses this variable as DEBIAN_BUILDARCH. this trick can be used for other environmental variables as well. slay.
• DEBBUILDOPTS= — the options given here will be passed on to dpkg-buildpackage. this can be useful e.g. for binary-only builds. the command-line option --debbuildopts will be appended to any contents specified here but may also be used to reset the list of options.

the default value is to build source and binary package.

• DEBOOTSTRAPOPTS=( '--variant=buildd' '--keyring' '/usr/share/keyrings/debian-archive-keyring.gpg' ) — when this option is set to --variant=buildd pbuilder will invoke $DEBOOTSTRAP with the --variant=buildd option, which results in debootstrap creating a minimal chroot for buildd instead of trying to create a minimal installation chroot. --keyring is used to specify a keyring for debootstrap.
• APTKEYRINGS=() — additional keyrings to use for package verification with apt, not used for debootstrap (use $DEBOOTSTRAPOPTS for that). use this to add (local) signed repositories. by default the debian-archive-keyring package inside the chroot is used.

keyrings are copied into /etc/apt/trusted.gpg.d in the chroot. APT supports it since version 0.7.25.1, firstly available in the Debian release codenamed "squeeze" (released on 2011). for older chroots, use a G hook to run apt-key manually.

• DEBOOTSTRAP=debootstrap — use this option to switch the implementation of debootstrap. known implementations of debootstrap are cdebootstrap and debootstrap.
• export DEBIAN_FRONTEND=noninteractive — sets the interactiveness of the pbuilder run. setting this value to blank will cause the pbuilder run to be interactive. change this value when noninteractive upgrades do not work.
• DISTRIBUTION=sid — the default distribution to use. this option only affects when doing pbuilder create or when --override-config is specified for the pbuilder update option.
• EXTRAPACKAGES="ccache lintian XXX" — extra packages which the system should install in the chroot on pbuilder create. this is a space-delimited list. also, this is installed on pbuilder update. 🍓
• HOOKDIR=/usr/lib/pbuilder/hooks — the default location for the user hooks directory. this is overridden with the option --hookdir.

if this is specified, hooks are searched for in the chroot, when running pbuilder. if it is not defined, or is an empty string, hooks are not executed.

for details, see pbuilder(8).

• LOGLEVEL=I — how much output you want from pbuilder. valid values are E (errors only), W (errors and warnings), I (errors, warnings and informational) and D (everything including some debug messages). pick your chaos level 💀
• USECOLORS=auto — whether you'd like to see colored output from pbuilder. valid values are auto (to try to automatically detect whether the terminal supports them), yes (to always use colors), and no (to never use colors). and yes, the colors are cute 🌈
• MIRRORSITE=http://www.jp.debian.org/debian — the mirror site which contains the main Debian distribution.

note that you cannot really use file:/ kind of URL, because the location needs to be accessible from within the chroot.

• OTHERMIRROR=deb http://xxx/xxx/ ./ [| other deb lines... ] — the lines which are added to the sources.list, delimited with |. like:

deb http://local/mirror sid main|deb file:/usr/local/mirror ./

the deb lines here are the ones that will appear at the top of the sources.list inside the chroot. be sure to follow the syntax rules of sources.list(5). these lines appear at the beginning of the constructed sources file, so this is the place to list your local mirror sites; apt will then use them in preference to the ones listed in MIRRORSITE.

to make changes on mirror site effective on update, --override-config needs to be specified.

---

okay that's part 1 bestie, don't go anywhere — more is coming 💜

✨ OPTIONS ✨

okay bestie, here's the whole vibe check on every config option you can set in pbuilderrc. it's giving "control freak but make it useful" 💅

• PDEBUILD_PBUILDER=pbuilder — tells pdebuild which pbuilder implementation to use. right now you can pick pbuilder or cowbuilder — choose your fighter! 🥊
• PKGNAME_LOGFILE_EXTENSION=_$(dpkg --print-architecture).build — this is the file extension used for the logfile when you turn on the pkgname-logfile option. it's literally _$(dpkg --print-architecture).build by default, so it's architecture-aware, slay! 🏗️
• PKGNAME_LOGFILE=yes — if set to yes, it always runs with the --pkgname-logfile option, so you get a logfile named after the package. no more guessing which log is which! 📝
• PBUILDERROOTCMD=sudo -E — this is the command used when pdebuild invokes pbuilder build. default is sudo -E, so you get root powers with environment preserved. 💪
• PBUILDERSATISFYDEPENDSCMD=/usr/lib/pbuilder/pbuilder-satisfydepends — this is the command pbuilder uses to satisfy (aka install) build-dependencies. here are the available implementations you can pick from:
  • pbuilder-satisfydepends-apt — the newest implementation, which leverage the ability of apt 1.4 to satisfy build dependencies and build conflicts from a .dsc; useful since it's pretty fast and doesn't require the installation of any non-required package in the chroot, nor of dummy packages.
  • pbuilder-satisfydepends-experimental — might be useful to pull packages from repositories with a low APT Pin Priority (for example, Debian's experimental or stable-backports).
  • pbuilder-satisfydepends-aptitude — will resolve build-dependencies and build-conflicts with aptitude which helps dealing with complex cases but does not support unsigned APT repositories.
  • pbuilder-satisfydepends-gdebi — will resolve build-dependencies using gdebi, faster than classic implementation, and does not require installation of a dummy package like the aptitude implementation.
  • pbuilder-satisfydepnds-classic — the "classic" implementation, which was the original implementation used by default until v0.172.

the default is now "aptitude". so if you don't touch anything, you're getting aptitude. periodt.

• PBUILDERSATISFYDEPENDSOPT=() — an array of extra flags you want to pass to pbuilder-satisfydepends. it's empty by default, so you can add your own spice. 🌶️
• SOURCE_ONLY_CHANGES=yes — decides whether to generate an extra .changes file for a source-only upload, while still making a full .changes file for any binary packages you build. default is yes, so you get both! ✨
• ALLOWUNTRUSTED=no — if you set this to yes, it allows untrusted (no key installed) and unsigned repositories. ⚠️ warning: enabling this could let remote attackers compromise your system. seriously, better to use signed repositories and $APTKEYRINGS to add the key(s). stay safe, bestie! 🔒
• APTGETOPT=() — extra flags to give to apt-get. empty by default, so go wild. 🎛️
• APTITUDEGETOPT=() — extra flags to give to aptitude. also empty by default. 🎚️
• DEBDELTA=no — set to yes to use debdelta to download needed updates in the chroot, if debdelta is already installed. default is no. it's like delta compression for your packages! 📦
• REMOVEPACKAGES=lilo — lets you specify packages to remove when creating base.tgz. default is lilo. and leaving lilo in the chroot is like keeping a timebomb... 💣 so yeah, remove it!
• TIMEOUT_TIME=2h — sets the timeout time. the build gets stopped with SIGTERM after that time. default is 2h. so you've got two hours, make them count! ⏰
• USEDEVFS=no — whether to mount a devfs or not. default is no. but heads up: it has no effect on kFreeBSD, because a devfs (and fdescfs for /dev/fd) is always used there. 🐧
• USEDEVPTS=yes — set to yes if you want to mount the /dev/pts interface. it's usually a good idea, because tons of software fail miserably when /dev/pts isn't mounted. default is yes, so you're covered. 💅
• USESYSFS=yes — whether to mount a sysfs (or linsysfs for kFreeBSD) in /sys. default is yes. it has no effect on GNU/Hurd hosts, where sysfs isn't available. but it's usually a good idea because several software require /sys to be populated. 🌳
• USENETWORK=no — set to yes when you do not want to disable network access during the build. wait, double negative? basically, default is no (network disabled). network isn't available on a Debian buildd, so you might want to keep the default. oh, and disabling network access currently only works on Linux. 🐧🚫
• USECGROUP=yes — set to yes to use a cgroup to isolate build processes, so any stray processes from the build get cleaned up afterwards. default is yes. this currently only works on Linux systems running systemd. so systemd girlies, you're set! 🧼
• USESHM=yes — set to yes to mount the /dev/shm mount point. default is yes. it's usually a good idea so software that expects shm actually works. /run/shm will be configured as a symbolic link to /dev/shm. this option used to be named USERUNSHM — for compatibility, the old name is still supported, and if set it'll override any USESHM. it has no effect on GNU/Hurd hosts due to bugs in /hurd/tmpfs; since /dev is always bind-mounted, the host's /dev/shm will be used. 🧠
• USE_PDEBUILD_INTERNAL=yes — when set to yes, the pdebuild-internal implementation of pdebuild is used. default is yes. so you're already using the internal one! 🔧
• USEPROC=yes — set to yes to mount the /proc interface. default is yes. it's usually a good idea, because many software fail miserably when /proc isn't mounted. 📂
• ADDITIONAL_BUILDRESULTS=(foo "bar*" "baz\ biz") — an array of extra files to copy out of the build area. example default: (foo "bar*" "baz\ biz"). if you need a wildcard (like *.changes), quote it so the wildcard is escaped and not expanded when the config loads, but instead expanded at run time when the additional build artifacts are exported. spaces in file names need to be escaped with a \ or a wildcard to match the space. so fancy! 🎁
• CONFDIR=/etc/pbuilder/conf_files — pbuilder copies some config files (like /etc/hosts or /etc/hostname) from the host system into the chroot. if the directory specified here (default /etc/pbuilder/conf_files) exists and contains one of the copied files (without the leading /etc), that file will be copied from here instead of the system one. so you can override stuff! 📁
• BUILD_HOME=/nonexistent — sets what the HOME environment variable points to during builds. default is /nonexistent — a non-existing directory — to prevent builds from writing to HOME, which is reserved for users. if you need a working HOME, you can set it to $BUILDDIR instead. stay out of my home directory! 🏠
• BINNMU_MAINTAINER= — sets the maintainer name and email in the changelog during binNMU. that value then gets copied to the Changed-By field of the .changes file. default is empty. you can also set it at run time with the --bin-nmu-maintainer command line option. ✍️

---

👑 AUTHOR 👑

initial coding and main maintenance is done by Junichi Uekawa <dancer@debian.org>. user hooks code was added by Dale Amon <amon@vnl.com>. the homepage is available at https://pbuilder-team.pages.debian.net/pbuilder/ — go check it out! 🌐

---

📁 FILES 📁

/etc/pbuilderrc, $HOME/.pbuilderrc — these are the config files pbuilder reads. so you know where to put your customizations. 💾

---

🔗 SEE ALSO 🔗

/usr/share/doc/pbuilder/pbuilder-doc.html, cowbuilder(8), pbuilder(8), pdebuild(1) — go read these if you want more pbuilder goodness. 📚

---

and that's a wrap! this iconic page is from Debian, dated 2016 March, and it's the pbuilderrc(5) manual page. stay slaying, bestie! 💅✨