This file contains various values which dpkg and dselect will use to manage the package. Here is an example:

Source: bao
Section: games
Priority: optional
Maintainer: Ben Mesman <ben@mesman.nu>
Build-Depends: debhelper (>> 3.0.0)
Standards-Version: 3.5.2

Package: bao
Architecture: any
Depends: ${shlibs:Depends}
Description: A mancala game from Tanzania and Zanzibar
 Bao is what we call a mancala game. Mancala is the term to denominate
 games with one shared characteristic: moves are not executed as in
 chess or checkers, instead moves are executed by sowing seeds (or
 other playing pieces) into holes.

The first six lines are the control information for the source package.

The Section: field is the Debian section this package goes to. This package will be installed in the section “games”. Other sections include for instance “x11” for X11 specific programs or “devel” for programmer tools.

The Priority: field describes how important it is for the user to install this package. Possible priorities are “required”, “important”, “standard”, “optional” and “extra”. This should probably be “optional” or “extra” for self-created packages.

The Maintainer: field is the maintainer of the Debian package, not the upstream maintainer. The Standards-Version is the version of the Debian Policy Manual the package conforms to.

If you want to resolve the build dependencies (i.e., the packages needed to build this package) automatically, you need to specify the packages in the Build-Depends field.

The second part of the file contains information on the binary package that will be generated. If more binary packages should be created from the same source, there will be more of these sections.

Note that the Architecture: field should be set to “all” for most packages. Se the Debian Policy Manual for more information on architecture dependent packages.

Apart from the package description, the most important information here is the relationship with other packages. There are seven possible relations:

Note that in this example the “Depends:” field contains $(shlibs:Depends). This will be automatically generated by dh_shlibdeps, and filled in by dh_gencontrol, with the names of any shared libraries the program uses, such as libc6 or xlib6g, so they don't have to be explicitly specified.

This file contains the information about package upstream resources, copyright and license information. Its format is not dictated by the Debian PolicyJackson01, but the contents is (section 6.5). dh_make creates a default one. This is what it looks like:

This package was debianized by Ben Mesman <ben@snow.nl>
on Fri, 23 Nov 2001 11:42:37 +0100.

It was downloaded from <fill in ftp site>

Upstream Author(s): <put author(s) name and email here>

Copyright:

<Must follow here>

If the program is licensed under one of the common free software licenses, such as the GNU GPL or LGPL, BSD or the Artistic license, you can refer to the appropriate file in the /usr/share/common-licenses/ directory. If the program has its own license, the complete license must be included in this file.

This is a required file and uses a special format. This format is used by dpkg and other programs to obtain the version number, revision, distribution and urgency of the package.

For the maintainer of the program, it is also important, since it is good to document all changes. It will help people downloading the package to see whether there are any unresolved issues that they should know about before installing. It will be saved as /usr/share/doc/bao/changelog.Debian.gz in the binary package.

This is an example Changelog:

bao (0.1.0) unstable; urgency=low

  * Initial Release.

 -- Ben Mesman <ben@snow.nl>  Fri, 23 Nov 2001 11:42:37 +0100

Local variables:
mode: debian-changelog
End:

The first line is the package name, version, distribution and urgency. The name must match the source package name, distribution should be either “unstable” or “experimental” (for now), and urgency probably shouldn't be changed to anything higher than “low”.

The third line is a log entry describing the changes in this release. The fifth line closes the comments and specifies who made the release and when. The name <email> must be followed by two spaces and the date in RFC822 format (e.g., as generated with date -R).

New releases should be added at the top.

Now we need to take a look at the exact rules which dpkg-buildpackage will use to actually create the package. This file is actually another Makefile, since it is executed with “make -f”, but different from the one in the upstream source.

The important part to know about the rules file created by dh_make is that it is just a suggestion. It will work for simple packages, but, for more complicated ones, don't be afraid to add and subtract from it to fit your needs. The only thing that you must not change are the names of the rules, because all the tools use these names, as mandated by the Packaging Manual.

#!/usr/bin/make -f
# Sample debian/rules that uses debhelper.
# GNU copyright 1997 to 1999 by Joey Hess.

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

# This is the debhelper compatibility version to use.
export DH_COMPAT=3

configure: configure-stamp
configure-stamp:
        dh_testdir
        # Add here commands to configure the package.
        ./configure --prefix=/usr --mandir=\$${prefix}/share/man --infodir=\$${prefix}/share/info

        touch configure-stamp

build: configure-stamp build-stamp
build-stamp:
        dh_testdir

        # Add here commands to compile the package.
        $(MAKE)
        #/usr/bin/docbook-to-man debian/bao.sgml > bao.1

        touch build-stamp

clean:
        dh_testdir
        # dh_testroot
        rm -f build-stamp configure-stamp

        # Add here commands to clean up after the build process.
        -$(MAKE) distclean

        dh_clean

install: build
        dh_testdir
        dh_testroot
        dh_clean -k
        dh_installdirs

        # Add here commands to install the package into debian/bao.
        $(MAKE) install DESTDIR=$(CURDIR)/debian/bao

# Build architecture-independent files here.
binary-indep: build install
# We have nothing to do by default.

# Build architecture-dependent files here.
binary-arch: build install
        dh_testdir
        dh_testroot
#       dh_installdebconf
        dh_installdocs
        dh_installexamples
        dh_installmenu
#       dh_installlogrotate
#       dh_installemacsen
#       dh_installpam
#       dh_installmime
#       dh_installinit
        dh_installcron
        dh_installman
        dh_installinfo
#       dh_undocumented
        dh_installchangelogs 
        dh_link
        dh_strip
        dh_compress
        dh_fixperms
#       dh_makeshlibs
        dh_installdeb
#       dh_perl
        dh_shlibdeps
        dh_gencontrol
        dh_md5sums
        dh_builddeb

binary: binary-indep binary-arch
.PHONY: build clean binary-indep binary-arch binary install configure

As you can see from the first line, this script will be processed by make.

The “configure” rule (and its child, “config-stamp”) specify that the program will be configured to run in /usr (instead of the default /usr/local). Also the manual pages and the shared files will be installed in the Debian default location.

The “build” rule (and its child “build-stamp”) specify how the program is to be built. In most cases, the program's own Makefile will be used.

The “clean” rule cleans up any unneeded binary or auto-generated stuff left over from building the package. This rule must be working at all times (even when the source tree is cleaned up!), so please use the forcing options (e.g., for rm, that is -f), or ignore return values (with a - in front of a command name).

The installation process, the “install” rule, basically runs the “install” rule from the program's own Makefile, but installs in <pwd>/debian/bao directory.

As the comments suggest, the “binary-indep” rule is used to build architecture independent packages. As none are specified in the control file, nothing will be done. If the package was an “Architecture: all” one, all the commands for building the package would be under this rule, and the next rule (“binary-arch”) would be empty instead.

The “binary-arch” rule uses several small utilities from the debhelper package to perform various operations to make the package Policy conforming.

The names start with dh_, and the rest is the description of what the particular utility really does. It is all quite self-explanatory, but here are some additional explanations:

For more information on these and other debhelper commands, read the debhelper documentation.

When the rules file is adapted to the program, a package can be build by executing

dpkg-buildpackage -rfakeroot

This will do everything for you, including the signing of the files. You will just have to enter your PGP (or GPG) secret key twice.

In our example, the following files will be generated:

The header consists of a series of fields that provide general information about the package. These fields are:

This is the second section of the spec file. It should contain all commands to set-up the source to do a make. This is where you unpack the source(s) and apply the patch(es).

One thing to note is that each of these sections is really just a place to execute shell scripts. So, it is possible to create a sh script and put it after the %prep tag to unpack and patch the sources. However, there are macros to aid in this.

The first macro, shown in the example, is the %setup macro. It unpacks the sources mentioned in the “Source:” line in the header and cd's into the source directory.

The second macro is called %patch. It will apply all patches mentioned in the header. Since there are no patches for this package, the %patch macro is not included in the example.

If something needs to be done that can't be handled by these macros, you can include another setup. Everything up to the “%build” section will be interpreted as an sh script.

There aren't really any macros for this section. Just use any commands here that you would need to build the software once you have untarred the source, patched it and cd'ed into the directory. This is just another set of commands passed to sh, so any legal sh commands can go here (including comments).

There aren't really any macros here, either. Basically, use any commands that are necessary for the install. If you have make install available to you in the package you are building, put that here. If not, you can either patch the Makefile for a make install and just do a make install here, or you can hand install them here with sh commands. You can consider your current directory to be the top-level of the source directory.

The variable RPM_BUILD_ROOT is available to tell you the path set as the “Buildroot:” in the header. Using build roots are optional, but are highly recommended because they keep you from cluttering your system with software that isn't in your RPM database (building an RPM doesn't touch your database...you must install the binary RPM you just built to do that).

It's a good idea to always make sure there is a clean build root before building a package a second time on a system. The “%clean” macro will help with that. Simply put the proper commands there to blow away a former build root.

In the example, the RPM_BUILD_ROOT is removed. To be prudent, it is a good idea to check that RPM_BUILD_ROOT was not set to / before doing something this volatile.

This is the section where you must list the files for the binary package. RPM has no way of knowing what binaries get installed as a result of make install. To circumvent this, some have suggested doing a find before and after the package install. With a multiuser system, this is unacceptable as other files may be created during a package building process that have nothing to do with the package itself.

There are some macros available to do some special things as well. They are listed and described here:

A potential problem in the file list is listing directories. If you list /usr/bin by accident, your binary package will contain every file in /usr/bin on your system.

This is a log of the changes that were made when the package was updated. If you are modifying an existing RPM it is a good idea to list the changes here.

The format is simple. Start each new entry with a line with a “*” followed by the date, your name and your email address. The date should appear in the same format that is output by:

date +"%a %b %d %Y"

The rest of the section is a free text field, but should be organised in some coherent manner.

When the SPEC file is finished, you can build an RPM with:

rpm -bb <spec-file>

The -bb indicate that rpm should build a binary package. -bs builds a source rpm and -ba builds both (all). The RPM will be placed in /usr/src/RPMS/ and the source RPM will be placed in /usr/src/SRPMS (or wherever your RPM-build tree should be).