The rules file

The rules file is written in make, and provides the actual instructions to build the package. See CaffeinatedMake for a brief overview of syntax.

CDBS and Debhelper

Writing rules files from scratch is difficult and time-consuming, and virtually nobody does it. (For an example of a rules file written entirely from scratch, see the one included with the hello package.) Instead, there exist two suites to simply this task: Common Debian Build System (CDBS), and Debhelper. (CDBS, in turn, uses Debhelper internally.)

CDBS

When using CDBS, your control file must declare a build-dependency on cdbs. With CDBS, a makefile might look like this:

#!/usr/bin/make -f

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/autotools.mk

CDBS includes debhelper.mk to get Debhelper functionality, and then includes autotools.mk because the software being packaged uses GNU autotools (e.g. autoconf, automake, etc.). For simple packages that merely ship with a Makefile, for which one types "make; make install", the second line would instead be include /usr/share/cdbs/1/class/makefile.mk. For packages that use other build systems, there are rules files in /usr/share/cdbs/1/class/ for python-distutils, ant, and a few others. If you plan to use quilt patches, you’ll want to include /usr/share/cdbs/1/rules/patchsys-quilt.mk.

CDBS is primarily controlled through the setting of make variables in the rules file or through the existence of special files in the debian directory. Many changes to flags passed to during the build process can be implemented by just setting a single variable. Many of these variables can also be set on a per-package basis using names like CFLAGS_package. To get a definitive answer, one should inspect the code of debhelper.mk or the class file that you are using.

Useful makefile variables

• DEB_AUTO_UPDATE_DEBIAN_CONTROL: Set this to enabled auto-generation of debian/control from debian/control.in. This option is basically banned in Debian because it apparently causes problems with NMUs, but it can save work.
• DEB_CONFIGURE_EXTRA_FLAGS (autotools.mk): Any extra flags you want to pass to configure.
• DEB_MAKE_ENVVARS (makefile.mk): Any environment variables you want to set for make.
• DEB_MAKE_INVOKE += … (makefile.mk): Pass extra flags to make (note the += here).
• DEB_MAKE_{BUILD,CLEAN,…}_TARGET (makefile.mk): Control what make targets CDBS uses. Note that make install and make check unless you set their corresponding target variable.
• DEB_MAKE_CLEAN_TARGET (makefile.mk): Often you want to set this to distclean.
• CFLAGS,CPPFLAGS,LDFLAGS,… (makefile.mk): Control common compiler and linker flags.
• DEB_CONFIGURE_EXTRA_FLAGS (autotools.mk): Any extra flags you want to pass to configure.
• DEB_AUTO_UPDATE_AUTOAUTO = version (makefile.mk): Have autotools component AUTOAUTO-version run at build time.
• DEB_DH_LINK_ARGS: Create symlinks in your installation (or use a .links file, see below)
• DEB_DH_debhelper-tool_ARGS: Add flags to any of a number of debhelper tools.

Debhelper

A debhelper rules file is even simpler:

#!/usr/bin/make -f

%:
        dh $@ 

Note that Debathena still uses primarily CDBS, because config-package-dev is not available for pure Debhelper packages. During the Spring and Summer of 2013, we hope to convert the repository to primarily Debhelper packages.