4.9. Main building script: debian/rules

This file must be an executable makefile. It contains the package-specific recipes for compiling the source (if required) and constructing one or more binary packages.

debian/rules must start with the line #!/usr/bin/make -f, so that it can be invoked by saying its name rather than invoking make explicitly. That is, invoking either of make -f debian/rules args... or ./debian/rules args... must result in identical behavior.

The recommended way to implement the build process of a Debian package, in the absence of a good reason to use a different approach, is the dh tool. This includes the contents of the debian/rules building script. dh is the most common packaging helper tool in Debian. Using it will usually save effort in complying with the rules in this document, because dh will automatically implement many of them without requiring explicit instructions.

There are sometimes good reasons to use a different approach. For example, the standard tools for packaging software written in some languages may use another tool; some rarer packaging patterns, such as multiple builds of the same software with different options, are easier to express with other tools; and a packager working on a different packaging helper might want to use their tool. The recommendation to use dh does not always apply, and use of dh is not required.

For more information about how to use dh, see the documentation in the debhelper package, most notably the dh(1) manual page.

The following targets are required and must be implemented by debian/rules: clean, binary, binary-arch, binary-indep, build, build-arch and build-indep. These are the targets called by dpkg-buildpackage.

Since an interactive debian/rules script makes it impossible to auto-compile that package and also makes it hard for other people to reproduce the same binary package, all required targets must be non-interactive. It also follows that any target that these targets depend on must also be non-interactive.

The package build should be as verbose as reasonably possible, except where the terse tag is included in DEB_BUILD_OPTIONS (see debian/rules and DEB_BUILD_OPTIONS). This makes life easier for porters and bug squashers more generally, who can look at build logs for possible problems. To accomplish this, debian/rules should pass to the commands it invokes options that cause them to produce verbose output. For example, the build target should pass --disable-silent-rules to any configure scripts. See also Binaries.

For packages in the main archive, no required targets may attempt network access, except, via the loopback interface, to services on the build host that have been started by the build.

Required targets must not attempt to write outside of the unpacked source package tree. There are two exceptions. Firstly, the binary targets may write the binary packages to the parent directory of the unpacked source package tree. Secondly, required targets may write to /tmp, /var/tmp and to the directory specified by the TMPDIR environment variable, but must not depend on the contents of any of these.

This restriction is intended to prevent source package builds creating and depending on state outside of themselves, thus affecting multiple independent rebuilds. In particular, the required targets must not attempt to write into HOME.

The targets are as follows:

build (required)

The build target should perform all the configuration and compilation of the package. If a package has an interactive pre-build configuration routine, the Debian source package must either be built after this has taken place (so that the binary package can be built without rerunning the configuration) or the configuration routine modified to become non-interactive. (The latter is preferable if there are architecture-specific features detected by the configuration routine.)

For some packages, notably ones where the same source tree is compiled in different ways to produce two binary packages, the build target does not make much sense. For these packages it is good enough to provide two (or more) targets (build-a and build-b or whatever) for each of the ways of building the package, and a build target that does nothing. The binary target will have to build the package in each of the possible ways and make the binary package out of each.

The build target must not do anything that might require root privilege.

The build target may need to run the clean target first - see below.

When a package has a configuration and build routine which takes a long time, or when the makefiles are poorly designed, or when build needs to run clean first, it is a good idea to touch build when the build process is complete. This will ensure that if debian/rules build is run again it will not rebuild the whole program. 11

build-arch (required), build-indep (required)

The build-arch target must perform all the configuration and compilation required for producing all architecture-dependent binary packages (those packages for which the body of the Architecture field in debian/control is not all). Similarly, the build-indep target must perform all the configuration and compilation required for producing all architecture-independent binary packages (those packages for which the body of the Architecture field in debian/control is all). The build target should either depend on those targets or take the same actions as invoking those targets would perform. 12

The build-arch and build-indep targets must not do anything that might require root privilege.

binary (required), binary-arch (required), binary-indep (required)

The binary target must be all that is necessary for the user to build the binary package(s) produced from this source package. It is split into two parts: binary-arch builds the binary packages which are specific to a particular architecture, and binary-indep builds those which are not.

binary may be (and commonly is) a target with no commands which simply depends on binary-arch and binary-indep.

Both binary-* targets should depend on the build target, or on the appropriate build-arch or build-indep target, so that the package is built if it has not been already. It should then create the relevant binary package(s), using dpkg-gencontrol to make their control files and dpkg-deb to build them and place them in the parent of the top level directory.

Both the binary-arch and binary-indep targets must exist. If one of them has nothing to do (which will always be the case if the source generates only a single binary package, whether architecture-dependent or not), it must still exist and must always succeed.

The binary targets may need to be invoked as root depending on the value of the Rules-Requires-Root field. 13

clean (required)

This must undo any effects that the build and binary targets may have had, except that it should leave alone any output files created in the parent directory by a run of a binary target.

If a build file is touched at the end of the build target, as suggested above, it should be removed as the first action that clean performs, so that running build again after an interrupted clean doesn’t think that everything is already done.

The clean target may need to be invoked as root if binary has been invoked since the last clean, or if build has been invoked as root (since build may create directories, for example).

The clean target cannot be used to remove files in the source tree that are not compatible with the DFSG. This is because the files would remain in the upstream tarball, and thus in the source package, so the source package would continue to violate DFSG. Instead, the upstream source should be repacked to remove those files.

patch (optional)

This target performs whatever additional actions are required to make the source ready for editing (unpacking additional upstream archives, applying patches, etc.). It is recommended to be implemented for any package where dpkg-source -x does not result in source ready for additional modification. See Source package handling: debian/README.source.

The build, binary and clean targets must be invoked with the current directory being the package’s top-level directory.

Additional targets may exist in debian/rules, either as published or undocumented interfaces or for the package’s internal use.

The architectures we build on and build for are determined by make variables using the utility dpkg-architecture. You can determine the Debian architecture and the GNU style architecture specification string for the build architecture as well as for the host architecture. The build architecture is the architecture on which debian/rules is run and the package build is performed. The host architecture is the architecture on which the resulting package will be installed and run. The target architecture is the architecture of the packages that the compiler currently being built will generate. These are normally the same, but may be different in the case of cross-compilation (building packages for one architecture on machines of a different architecture), building a cross-compiler (a compiler package that will generate objects for one architecture, built on a machine of a different architecture) or a Canadian cross-compiler (a compiler that will generate objects for one architecture, built on a machine of a different architecture, that will run on yet a different architecture).

Here is a list of supported make variables:

  • DEB_*_ARCH (the Debian architecture)

  • DEB_*_ARCH_CPU (the Debian CPU name)

  • DEB_*_ARCH_BITS (the Debian CPU pointer size in bits)

  • DEB_*_ARCH_ENDIAN (the Debian CPU endianness)

  • DEB_*_ARCH_OS (the Debian System name)

  • DEB_*_GNU_TYPE (the GNU style architecture specification string)

  • DEB_*_GNU_CPU (the CPU part of DEB_*_GNU_TYPE)

  • DEB_*_GNU_SYSTEM (the System part of DEB_*_GNU_TYPE)

where * is either BUILD for specification of the build architecture, HOST for specification of the host architecture or TARGET for specification of the target architecture.

Backward compatibility can be provided in the rules file by setting the needed variables to suitable default values; please refer to the documentation of dpkg-architecture for details.

It is important to understand that the DEB_*_ARCH string only determines which Debian architecture we are building on or for. It should not be used to get the CPU or system information; the DEB_*_ARCH_CPU and DEB_*_ARCH_OS variables should be used for that. GNU style variables should generally only be used with upstream build systems.

The builder may set DEB_RULES_REQUIRES_ROOT environment variable when calling any of the mandatory targets as defined in Rules-Requires-Root. If the variable is not set, the package must behave as if it was set to binary-targets.

4.9.1. debian/rules and DEB_BUILD_OPTIONS

Supporting the standardized environment variable DEB_BUILD_OPTIONS is recommended. This variable can contain several flags to change how a package is compiled and built. Each flag must be in the form flag or flag=options. If multiple flags are given, they must be separated by whitespace. 14 flag must start with a lowercase letter (a-z) and consist only of lowercase letters, numbers (0-9), and the characters - and _ (hyphen and underscore). options must not contain whitespace. The same tag should not be given multiple times with conflicting values. Package maintainers may assume that DEB_BUILD_OPTIONS will not contain conflicting tags.

The meaning of the following tags has been standardized:

nocheck

This tag says to not run any build-time test suite provided by the package.

nodoc

This tag says to skip any build steps that only generate package documentation. Files required by other sections of Debian Policy, such as copyright and changelog files, must still be generated and put in the package, but other generated documentation such as help2man-generated pages, Doxygen-generated API documentation, or info pages generated from Texinfo sources should be skipped if possible. This option does not change the set of binary packages generated by the source package, but documentation-only binary packages may be nearly empty when built with this option.

noopt

The presence of this tag means that the package should be compiled with a minimum of optimization. For C programs, it is best to add -O0 to CFLAGS (although this is usually the default). Some programs might fail to build or run at this level of optimization; it may be necessary to use -O1, for example.

nostrip

This tag means that the debugging symbols should not be stripped from the binary during installation, so that debugging information may be included in the package.

parallel=n

This tag means that the package should be built using up to n parallel processes if the package build system supports this. 15 If the package build system does not support parallel builds, this string must be ignored. If the package build system only supports a lower level of concurrency than n, the package should be built using as many parallel processes as the package build system supports. It is up to the package maintainer to decide whether the package build times are long enough and the package build system is robust enough to make supporting parallel builds worthwhile.

terse

This tag means that the package build will be less verbose than default. For example, debian/rules might pass options to the package’s configure script that cause the compiler to produce less output.

Unknown flags must be ignored by debian/rules.

The following makefile snippet is an example of how one may implement the build options; you will probably have to massage this example in order to make it work for your package.

  1. CFLAGS = -Wall -g
  2. INSTALL = install
  3. INSTALL_FILE    = $(INSTALL) -p    -o root -g root  -m  644
  4. INSTALL_PROGRAM = $(INSTALL) -p    -o root -g root  -m  755
  5. INSTALL_SCRIPT  = $(INSTALL) -p    -o root -g root  -m  755
  6. INSTALL_DIR     = $(INSTALL) -p -d -o root -g root  -m  755
  8. ifneq (,$(filter noopt,$(DEB_BUILD_OPTIONS)))
  9.     CFLAGS += -O0
  10. else
  11.     CFLAGS += -O2
  12. endif
  13. ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS)))
  14.     INSTALL_PROGRAM += -s
  15. endif
  16. ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
  17.     NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
  18.     MAKEFLAGS += -j$(NUMJOBS)
  19. endif
  21. build:
  22.         # ...
  23. ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
  24.         # Code to run the package test suite.
  25. endif

4.9.2. debian/rules and Rules-Requires-Root

Depending on the value of the Rules-Requires-Root field, the package builder (e.g. dpkg-buildpackage) may run the debian/rules target as an unprivileged user and provide a gain root command. This command allows the debian/rules target to run particular subcommands under (fake)root.

The gain root command is passed to the build script via the DEB_GAIN_ROOT_CMD environment variable. The contents of this variable is a space separated list, the first entry of which is the command, and the proceeding entries of which are arguments to the command. The gain root command must be available via PATH. The gain root command must not rely on shell features because it will not necessarily be invoked via a shell.

The gain root command must not run interactively, including prompting for any user input. It must be possible to prepend the gain root command to an existing command and its arguments, without needing to alter or quote the existing command and its arguments. Furthermore, the gain root command must preserve all environment variables without the caller having to explicitly request any preservation.

The following are examples of valid gain root commands (in syntax of sh), assuming the tools used are available and properly configured:

  1. # Command "sudo", with arguments "-nE" and "--"
  2. export DEB_GAIN_ROOT_CMD='sudo -nE --'
  3. # Command "fakeroot" with the single argument "--"
  4. export DEB_GAIN_ROOT_CMD='fakeroot --'

Examples of valid use of the gain root command:

  1. # sh-syntax (assumes set -e semantics for error handling)
  2. $DEB_GAIN_ROOT_CMD some-cmd --which-requires-root
  4. # perl
  5. my @cmd = ('some-cmd', '--which-requires-root');
  6. unshift(@cmd, split(' ', $ENV{DEB_GAIN_ROOT_CMD})) if $ENV{DEB_GAIN_ROOT_CMD};
  7. system(@cmd) == 0 or die("@cmd failed");