(debian-policy.info)Main building script debian/rules
4.9 Main building script: ‘debian/rules’
========================================
This file must be an executable makefile, and contains the
package-specific recipes for compiling the package and building binary
package(s) from the source.
It 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 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 Note:
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 Note:
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. (1)
‘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. (2)
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 Note: Rules-Requires-Root. field. (3)
‘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 Note: 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 Note:
Rules-Requires-Root. If the variable is not set, the package must
behave as if it was set to ‘binary-targets’.
debian/rules and DEB_BUILD_OPTIONS- debian/rules and Rules-Requires-Root
---------- Footnotes ----------
(1) Another common way to do this is for ‘build’ to depend on
‘build-stamp’ and to do nothing else, and for the ‘build-stamp’ target
to do the building and to ‘touch build-stamp’ on completion. This is
especially useful if the build routine creates a file or directory
called ‘build’; in such a case, ‘build’ will need to be listed as a
phony target (i.e., as a dependency of the ‘.PHONY’ target). See the
documentation of ‘make’ for more information on phony targets.
(2) This split allows binary-only builds to not install the
dependencies required for the ‘build-indep’ target and skip any
resource-intensive build tasks that are only required when building
architecture-independent binary packages.
(3) The ‘fakeroot’ package often allows one to build a package
correctly even without being root.
automatically generated by info2www version 1.2.2.9