DEBUILD(1)

📦
version 2.26.11ubuntu1 · 2 versions
, in fedora 43, fedora 44, ubuntu resolute, ubuntu stonking

okay bestie, sit down, hydrate, and let's talk about debuild — your new main character in the General Commands Manual (section 1, obviously) 💅✨

🎀 NAME 🎀

debuild — build a Debian package 💖

✨ SYNOPSIS ✨

debuild [debuild options] [dpkg-buildpackage options] [--lintian-opts lintian options]
debuild [debuild options] -- binary|binary-arch|binary-indep|clean ...

🌸 DESCRIPTION 🌸

So here's the tea, bestie: debuild creates all the files you need to actually upload a Debian package. Iconic behaviour, honestly.

Here's the order it does things, and no it does not skip steps:

  1. It runs dpkg-buildpackage first.
  2. Then it runs lintian on the .changes file that got created — assuming lintian is installed, bestie, don't come for it if it's not there.
  3. Finally it signs the appropriate files — using debsign(1) for that instead of dpkg-buildpackage(1) itself, and all the relevant key-signing options get passed on. 🫶

Signing gets skipped if the distribution is UNRELEASED — unless dpkg-buildpackage's --force-sign option is used. Not me pointing that out, it's just true.

You can pass parameters to both dpkg-buildpackage and lintian, and the ones for the latter are flagged with the --lintian-opts option. The allowable options in this case are --lintian and --no-lintian, to force or skip the lintian step respectively. The default is to run lintian.

There are also a bunch of options for setting and preserving environment variables — full rundown in the ENVIRONMENT VARIABLES section below, don't worry, we get there 👑

In this method of running debuild, we also save a build log to the file ../<package>_<version>_<arch>.build. Yes, with the actual values substituted, obviously. 💀

An alternative way of using debuild is to use one or more of the parameters binary, binary-arch, binary-indep and clean. In that case, debuild will attempt to gain root privileges and then run debian/rules with the given parameters.

A --rootcmd=gain-root-command or -rgain-root-command option may be used to specify a method of gaining root privileges. The gain-root-command is likely to be one of fakeroot, sudo or super. See below for further discussion of this point 👇

Again, the environment preservation options may be used. And in this case, debuild will also attempt to run dpkg-checkbuilddeps first. You can explicitly request that or switch it off using the options -D and -d respectively.

👀 Also note: if either of these or a -r option is specified in the configuration file option DEBUILD_DPKG_BUILDPACKAGE_OPTS, then it will be recognised even in this method of invocation of debuild.

debuild also reads the devscripts configuration files as described below. This allows default options to be given. Slay.

🦋 Directory name checking 🦋

In common with several other scripts in the devscripts package, debuild will climb the directory tree until it finds a debian/changelog file before attempting to build the package.

As a safeguard against stray files causing potential problems, it will examine the name of the parent directory once it finds the debian/changelog file, and check that the directory name corresponds to the package name. Precisely how it does this is controlled by two configuration file variables DEVSCRIPTS_CHECK_DIRNAME_LEVEL and DEVSCRIPTS_CHECK_DIRNAME_REGEX, and their corresponding command-line options --check-dirname-level and --check-dirname-regex.

DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:

  • 0 — Never check the directory name. 🙈
  • 1 — Only check the directory name if we have had to change directory in our search for debian/changelog. This is the default behaviour.
  • 2 — Always check the directory name. 👑

The directory name is checked by testing whether the current directory name (as determined by pwd(1)) matches the regex given by the configuration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the command line option --check-dirname-regex regex.

Here regex is a Perl regex (see perlre(3perl)), which will be anchored at the beginning and the end. If regex contains a '/', then it must match the full directory path. If not, then it must match the full directory name. If regex contains the string 'PACKAGE', this will be replaced by the source package name, as determined from the changelog.

The default value for the regex is: 'PACKAGE(-.+)?' — thus matching directory names such as PACKAGE and PACKAGE-version. Fr fr, that's the whole vibe check. 💜

🌈 ENVIRONMENT VARIABLES 🌈

Okay so this part matters a LOT. Environment variables can affect the building of a package, often unintentionally, so debuild sanitises the environment by removing all environment variables except for:

  • TERM
  • HOME
  • LOGNAME
  • GNUPGHOME
  • PGPPATH
  • GPG_AGENT_INFO
  • GPG_TTY
  • DBUS_SESSION_BUS_ADDRESS
  • FAKEROOTKEY
  • DEBEMAIL
  • DEB_*
  • the (C, CPP, CXX, LD and F)FLAGS variables and their _APPEND counterparts
  • the locale variables LANG and LC_*

TERM is set to `dumb' if it is unset, and PATH is set to "/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11". No cap.

If a particular environment variable is required to be passed through untouched to the build process, this may be specified by using a --preserve-envvar envvar (which can also be written as -e envvar option).

The environment may be left untouched by using the --preserve-env option. However, even in this case, the PATH will be set to the sane value described above. The only way to prevent PATH from being reset is to specify a --preserve-envvar PATH option.

⚠️ But you are warned that using programs from non-standard locations can easily result in the package being broken, as it will not be able to be built on standard systems. That's not a vibe, bestie, that's a bug report waiting to happen 😭

Note that one may add directories to the beginning of the sanitised PATH, using the --prepend-path option. This is useful when one wishes to use tools such as ccache or distcc for building. 🔥

It is also possible to avoid having to type something like FOO=bar debuild -e FOO by writing debuild -e FOO=bar or the long form debuild --set-envvar FOO=bar. Obsessed with convenience. 🎀

👑 SUPERUSER REQUIREMENTS 👑

debuild needs to be run as superuser to function properly. There are three fundamentally different ways to do this:

  1. The first, and preferable, method — use some root-gaining command. The best one to use is probably fakeroot(1), since it does not involve granting any genuine privileges. super(1) and sudo(1) are also possibilities. If no -r (or --rootcmd) option is given (and recall that dpkg-buildpackage also accepts a -r option) and neither of the following methods is used, then -rfakeroot will silently be assumed. ✨
  2. The second method — use some command such as su(1) to become root, and then to do everything as root. Note, though, that lintian will abort if it is run as root or setuid root; this can be overcome using the --allow-root option of lintian if you know what you are doing. 👀
  3. The third possible method — have debuild installed as setuid root. This is not the default method, and will have to be installed as such by the system administrator.

It must also be realised that anyone who can run debuild as root or setuid root has full access to the whole machine. This method is therefore not recommended, but will work.

debuild could be installed with mode 4754, so that only members of the owning group could run it. A disadvantage of this method would be that other users would then not be able to use the program. There are many other variants of this option involving multiple copies of debuild, or the use of programs such as sudo or super to grant root privileges to users selectively.

If the sysadmin wishes to do this, she should use the dpkg-statoverride program to change the permissions of /usr/bin/debuild. This will ensure that these permissions are preserved across upgrades. 💅

🪝 HOOKS 🪝

okay bestie so debuild is literally a whole event planner and it has hooks — lil moments where you can slip in your own command while dpkg-buildpackage is doing its thing. 💅

quick note before we dive in: the hooks from dpkg-buildpackage all the way down to lintian (inclusive) get passed through to dpkg-buildpackage using its matching --hook-name option. iykyk.

here's the whole roster, no skips:

  • dpkg-buildpackage-hook — runs before dpkg-buildpackage even starts, by calling dpkg-checkbuilddeps.

runs inside the unpacked source.

corresponds to dpkg's init hook.

  • clean-hook — runs before dpkg-buildpackage runs debian/rules clean to clean the source tree. (it runs even if the tree isn't being cleaned because -nc is used, bestie.)

runs inside the unpacked source.

corresponds to dpkg's preclean hook.

  • dpkg-source-hook — runs after cleaning the tree and before running dpkg-source. (runs even if dpkg-source isn't being called because -b, -B, or -A is used.)

runs inside the unpacked source.

corresponds to dpkg's source hook.

  • dpkg-build-hook — runs after dpkg-source and before calling debian/rules build. (runs even if this is a source-only build, so debian/rules build isn't being called at all.)

runs inside the unpacked source.

corresponds to dpkg's build hook.

  • dpkg-binary-hook — runs between debian/rules build and debian/rules binary(-arch). only runs if a binary package is actually being built.

runs inside the unpacked source.

corresponds to dpkg's binary hook.

  • dpkg-genchanges-hook — runs after the binary package is built and before calling dpkg-genchanges.

runs inside the unpacked source.

corresponds to dpkg's changes hook.

  • final-clean-hook — runs after dpkg-genchanges and before the final debian/rules clean. (runs even if we're not cleaning the tree post-build, which is the default.)

runs inside the unpacked source.

corresponds to dpkg's postclean hook.

  • lintian-hook — runs (once) before calling lintian. (runs even if we're not calling lintian.)

runs from the parent directory of the unpacked source.

corresponds to dpkg's check hook.

  • signing-hook — runs after calling lintian and before any signing takes place. (runs even if we're not signing anything.)

runs from the parent directory of the unpacked source.

corresponds to dpkg's sign hook, but it's run by debuild. ✨

  • post-dpkg-buildpackage-hook — runs after everything has finished. periodt.

runs from the parent directory of the unpacked source.

corresponds to dpkg's done hook, but it's run by debuild.

now the how, because this part is giving main character energy. 🌟

you can specify a hook command either in the configuration file, like:

DEBUILD_SIGNING_HOOK='foo'

(note that the hyphens change into underscores, bestie!! don't forget or it won't work 😭) — or as a command line option like --signing-hook-foo.

the command gets certain percent substitutions made on it, and these are non-negotiable lore:

  • %% gets replaced by a single % sign
  • %p gets replaced by the package name
  • %v gets replaced by the package version number
  • %s gets replaced by the source version number
  • %u gets replaced by the upstream version number
  • neither %s nor %u will contain an epoch
  • %a will be 1 if the immediately following action is to be performed and 0 if not (for example, in the dpkg-source hook, %a becomes 1 if dpkg-source is to be run and 0 if not)

then it gets handed to the shell to deal with, so it can include redirections and stuff. for example, to only run the dpkg-source hook if dpkg-source is to be run, the hook could be something like:

if [ %a -eq 1 ]; then ...; fi
⚠️ please take care with hooks, bestie — misuse of them can lead to packages which FTBFS (fail to build from source). they can be useful for taking snapshots of things or the like, but be careful. 🙈

✨ OPTIONS ✨

for details, see above. (yes really, that's what it says 💀)

  • --no-conf, --noconf — do not read any configuration files. this can only be used as the first option given on the command-line. no cap.
  • --rootcmd=gain-root-command, -rgain-root-command — the command to gain root (or fake root) privileges.
  • --preserve-env — do not clean the environment, except for PATH.
  • --preserve-envvar=var, -evar — do not clean the var variable from the environment.

if var ends in an asterisk (*) then all variables with names that match the portion of var before the asterisk will be preserved. 🫶

  • --set-envvar=var=value, -evar=value — set the environment variable var to value and do not remove it from the environment.
  • --prepend-path=value — once the normalized PATH has been set, prepend value to it.
  • --lintian — run lintian after dpkg-buildpackage. this is the default behaviour, and it overrides any configuration file directive to the contrary. 👑
  • --no-lintian — do not run lintian after dpkg-buildpackage.
  • --no-tgz-check — even if we're running dpkg-buildpackage and the version number has a Debian revision, do not check that the .orig.tar.gz file or .orig directory exists before starting the build.
  • --tgz-check — if we're running dpkg-buildpackage and the version number has a Debian revision, check that the .orig.tar.gz file or .orig directory exists before starting the build. this is the default behaviour.
  • --username username — when signing, use debrsign instead of debsign. username specifies the credentials to be used.
  • --foo-hook=hook — set a hook as described above. if hook is blank, this unsets the hook.
  • --clear-hooks — clears all hooks. they may be reinstated by later command line options. (iconic, honestly)
  • --check-dirname-level N — see the above section Directory name checking for an explanation of this option.
  • --check-dirname-regex regex — see the above section Directory name checking for an explanation of this option.
  • -d — do not run dpkg-checkbuilddeps to check build dependencies.
  • -D — run dpkg-checkbuilddeps to check build dependencies.

🎀 CONFIGURATION VARIABLES 🎀

so there are two configuration files: /etc/devscripts.conf and ~/.devscripts, and they get sourced by a shell in that order to set configuration variables. 🐚

command line options can be used to override some of these configuration file settings, otherwise the --no-conf option can be used to prevent reading these files. and heads up: environment variable settings are ignored when these configuration files are read. 🙅

the currently recognised variables are:

  • DEBUILD_PRESERVE_ENV — if this is set to yes, then it's the same as the --preserve-env command line parameter being used.
  • DEBUILD_PRESERVE_ENVVARS — which environment variables to preserve. this should be a comma-separated list of variables. corresponds to using possibly multiple --preserve-envvar or -e options.
  • DEBUILD_SET_ENVVAR_var=value — this corresponds to --set-envvar=var=value.
  • DEBUILD_PREPEND_PATH — this corresponds to --prepend-path.
  • DEBUILD_ROOTCMD — setting this variable to prog is the equivalent of -rprog.
  • DEBUILD_TGZ_CHECK — setting this variable to no is the same as the --no-tgz-check command line option.
  • DEBUILD_SIGNING_USERNAME — setting this variable is the same as using the --username command line option.
  • DEBUILD_DPKG_BUILDPACKAGE_OPTS — these are options which should be passed to the invocation of dpkg-buildpackage. they are given before any command-line options. due to issues of shell quoting, if a word containing spaces is required as a single option, extra quotes will be required. for example, to ensure that your own GPG key is always used, even for sponsored uploads, the configuration file might contain the line:
DEBUILD_DPKG_BUILDPACKAGE_OPTS="-k'Julian Gilbey <jdg@debian.org>' -sa"

which gives precisely two options. without the extra single quotes, dpkg-buildpackage would reasonably complain that Gilbey is an unrecognised option (it doesn't start with a - sign). 😭

also, if this option contains any -r, -d or -D options, these will always be taken account of by debuild. note that a -r option in this variable will override the setting in DEBUILD_ROOTCMD.

  • DEBUILD_FOO_HOOK — the hook variable for the foo hook. see the section on hooks above for more details. by default, this is empty.
  • DEBUILD_LINTIAN — should we run lintian? if this is set to no, then lintian will not be run.
  • DEBUILD_LINTIAN_OPTS — these are options which should be passed to the invocation of lintian. they are given before any command-line options, and the usage of this variable is as described for the DEBUILD_DPKG_BUILDPACKAGE_OPTS variable.
  • DEVSCRIPTS_CHECK_DIRNAME_LEVEL, DEVSCRIPTS_CHECK_DIRNAME_REGEX — see the above section Directory name checking for an explanation of these variables. note that these are package-wide configuration variables, and will therefore affect all devscripts scripts which check their value, as described in their respective manpages and in devscripts.conf(5). 💜

🌈 EXAMPLES 🌈

to build your own package, simply run debuild from inside the source tree. dpkg-buildpackage(1) options may be given on the command line. easy!

the typical command line options to build only the binary package(s) without signing the .changes file (or the non-existent .dsc file):

debuild -i -us -uc -b

change the -b to -S to build only a source package.

an example using lintian to check the resulting packages and passing options to it:

debuild --lintian-opts -i

note the order of options here, bestie: the debuild options come first, then the dpkg-buildpackage ones, then finally the checker options. (and lintian is called by default.) if you find yourself using the same dpkg-buildpackage options repeatedly, consider using the DEBUILD_DPKG_BUILDPACKAGE_OPTS configuration file option as described above. 💅

to build a package for a sponsored upload, given foobar_1.0-1.dsc and the respective source files, run something like the following commands:

dpkg-source -x foobar_1.0-1.dsc
cd foobar-1.0
debuild -k0x12345678

where 0x12345678 is replaced by your GPG key ID or other key identifier such as your email address. again, you could also use the DEBUILD_DPKG_BUILDPACKAGE_OPTS configuration file option as described above to avoid having to type the -k option each time you do a sponsored upload. 🦋

💜 SEE ALSO ✨

okay bestie, if you wanna go deeper down the rabbit hole (and honestly? you should, it's giving scholar energy), here's the whole squad that debuild hangs out with:

  • chmod(1) — changing file permission bits, iconic for a reason
  • debsign(1) — signing those Debian files so they're legit
  • dpkg-buildpackage(1) — the actual build machinery debuild is wrapping, the real main character tbh
  • dpkg-checkbuilddeps(1) — checks your build dependencies, your lil reality check
  • fakeroot(1) — fake root vibes, no actual sudo required
  • lintian(1) — the Debian package linter, your harshest but most loving bestie
  • su(1) — switch user, the OG
  • sudo(1) — do it as the superuser, you know her
  • super(1) — another way to get those elevated permissions
  • devscripts.conf(5) — the config file where all your settings live 🎀
  • dpkg-statoverride(8) — stat override shenanigans at the dpkg level

🌸 AUTHOR 🌸

so like, credit where credit is due, periodt:

The original debuild program was written by Christoph Lameter <clameter@debian.org>.

The current version has been written by Julian Gilbey <jdg@debian.org>.

bestie moment: these are the actual humans who made this tool happen. respect the elders 💖

and that's the whole page, no cap 🫶 this one comes from the Debian Utilities source, dated Debian — which is also, cute lil coincidence, the manual section it lives in, DEBUILD(1) 💅

go build something beautiful, you absolute icon 👑✨

📦 where this page comes from