Whole document tree

Debian New Maintainers' Guide
Chapter 4 Required stuff under debian/

There is a new subdirectory under the program's main directory (`gentoo-0.9.12'), it is called `debian'. There are a number of files in this directory. We will be editing these in order to customize the behavior of the package. The most important of them are `control', `changelog', `copyright' and 'rules', which are required for all packages.

4.1 `control' file

This file contains various values which dpkg and dselect will use to manage the package. Here is the control file dh_make creates for us.

       1  Source: gentoo
       2  Section: unknown
       3  Priority: optional
       4  Maintainer: Josip Rodin <jrodin@jagor.srce.hr>
       5  Standards-Version: 3.0.1
       6
       7  Package: gentoo
       8  Architecture: any
       9  Depends: ${shlibs:Depends}
       10 Description: <insert up to 60 chars description>
       11  <insert long description, indented with spaces>

(I've added the line numbers.)

Lines 1-5 are the control information for the source package. Line 1 is the name of the source package.

Line 2 is the section of the distribution this package goes into. As you may have noticed, Debian is divided in sections: main (the free software), non-free (the not really free software) and contrib (free software that depends on non-free software). Under those, there are logical subsections that describe in short what packages are in. So we have `admin' for administrator-only programs, `base' for the basic tools, `devel' for programmer tools, `doc' for documentation, `libs' for libraries, `mail' for e-mail readers and daemons, `net' for network apps and daemons, `x11' for X11 specific programs, and many more.

Let's change it then to x11.

Line 3 describes how important it is that the user install this package. Section and priority are actually only used by dselect when it sorts packages and selects defaults, and they can (and most probably will be) overridden by our FTP maintainers. See the Policy manual for guidance on what to set these fields to.

As it is a normal priority package, we'll leave it as optional.

Line 4 is the name and email address of the maintainer.

Line 5 is the version of the Debian Policy standards this package follows (two major versions of the installed debian-policy package).

If some non-standard compiler or other tool is needed to build your package, you should add here a `Build-Depends' line and list the required packages. For more information on this, read the Packaging Manual (section 8.7) and documentation of the `build-essential' package.

Line 7 is the name of the binary package.

Line 8 describes the CPU architecture the binary package can be compiled for. We can leave this as "any" because dpkg-gencontrol(1) will fill in the appropriate value for any machine this package gets compiled on (see the Developer's Reference for explanation on what porting packages is). If your package is architecture independent (for example, a shell or Perl script, or a document), change this to "all", and read later in `rules' file, Section 4.4 about using `binary-indep' rule instead of `binary-arch' for building the package.

Line 9 shows one of the most powerful features of the Debian packaging system. Packages can relate to each other in various ways. Apart from Depends:, other relationship fields are Recommends:, Suggests:, Pre-Depends:, Conflicts:, Provides:, and Replaces: .

The package management tools such as dpkg, dselect or APT (and its front-ends) usually behave the same way when dealing with these relations; if not, it will be explained. (see dpkg(8), dselect(8), apt(8), console-apt(8), gnome-apt(8))

This is what they usually mean:

• Depends:

  The package will not be installed unless the packages it depends on are installed. Use this if your program absolutely will not run (or will cause severe breakage) unless a particular package is present.

• Recommends:

  Dselect will not install your package unless the packages it recommends are installed. Dpkg and APT should let you do it, though. Use this for packages that are not strictly necessary but are typically used with your program.

• Suggests:

  When a user installs your program, dselect will prompt him to install any package it suggests. Dpkg and APT shouldn't care much. Use this for packages which will work nicely with your program but are not at all necessary.

• Pre-Depends:

  This is stronger than Depends:. The package will not be installed unless the packages it pre-depends on are installed and correctly configured. Use this very sparingly and only after discussing it on the debian-devel mailing list. Read: don't use it at all. :-)

• Conflicts:

  The package will not be installed until all the packages it conflicts with have been removed. Use this if your program absolutely will not run (or will cause severe breakage) if a particular package is present.

• Provides:

  For some types of packages where there are multiple alternatives virtual names have been defined. You can get the full list in /usr/share/doc/debian-policy/virtual-package-names-list.text.gz file. Use this if your program provides a function of an existing virtual package.

• Replaces:

  Use this when your program replaces files from another package, or completely replaces another package (used in conjunction with Conflicts:). Files from the named packages will be removed before installing yours.

All these fields have uniform syntax. They are a list of package names separated by commas. These package names may also be lists of alternative package names, separated by vertical bar symbols | (pipe symbols). The fields may restrict their applicability to particular versions of each named package. These versions are listed in parentheses after each individual package name, and they should contain a relation from the list below followed by the version number. The relations allowed are: <<, <=, =, >= and >> for strictly earlier, earlier or equal, exactly equal, later or equal and strictly later, respectively.

The last feature you need to know about is $(shlibs:Depends). This will be automatically generated by dh_shlibdeps(1) and filled in by dh_gencontrol(1) with the names of any shared libraries your program uses, such as libc6 or xlib6g, so you don't have to specify them yourself. Having said all that, we can leave line 9 exactly as it is now.

Line 10 is where the list of suggestions go. Here it's only `file', because gentoo can use some features provided by that program/package.

Line 11 is the short description. Most people screens are 80 columns wide so this shouldn't be longer than about 60 characters. I'll change it to "A fully GUI configurable GTK+ file manager".

Line 12 is where the long description goes. This should be a paragraph which gives more detail about the package. Column 1 of each line should be empty. There must be no blank lines, but you can put a . (dot) in a column to simulate that. Also, there must be no more that one blank line after the long description.

Here is the updated control file:

       1  Source: gentoo
       2  Section: x11
       3  Priority: optional
       4  Maintainer: Josip Rodin <jrodin@jagor.srce.hr>
       5  Standards-Version: 3.0.1
       6
       7  Package: gentoo
       8  Architecture: any
       9  Depends: ${shlibs:Depends}
       10 Suggests: file
       11 Description: A fully GUI configurable GTK+ file manager
       12  gentoo is a file manager for Linux written from scratch in pure C. It
       13  uses the GTK+ toolkit for all of its interface needs. gentoo provides
       14  100% GUI configurability; no need to edit config files by hand and re-
       15  start the program. gentoo supports identifying the type of various
       16  files (using extension, regular expressions, or the 'file' command),
       17  and can display files of different types with different colors and icons.
       18  .
       19  gentoo borrows some of its look and feel from the classic Amiga file
       20  manager "Directory OPUS" (written by Jonathan Potter).

(I've added the line numbers.)

4.2 `copyright' file

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

       1  This package was debianized by Josip Rodin <jrodin@jagor.srce.hr> on
       2  Wed, 11 Nov 1998 21:02:14 +0100.
       3
       4  It was downloaded from <fill in ftp site>
       5
       6  Upstream Author(s): <put author(s) name and email here>
       7
       8  Copyright:
       9
       10 <Must follow here>

(I've added the line numbers.)

The important things to add to this file are the place you got the package from and the actual copyright notice and license. You must include the complete license, unless it's one of the common free software licenses such as GNU GPL or LGPL, BSD or the Artistic license, when you can just refer to the appropriate file in /usr/share/common-licenses/ directory that exists on every Debian system. Gentoo is licensed under the GNU General Public License, so we'll change the file to this:

       1  This package was debianized by Josip Rodin <jrodin@jagor.srce.hr> on
       2  Wed, 11 Nov 1998 21:02:14 +0100.
       3
       4  It was downloaded from: ftp://ftp.obsession.se/gentoo/
       5
       6  Upstream author: Emil Brink <emil@obsession.se>
       7
       8  This software is copyright (c) 1998-99 by Emil Brink, Obsession
       9  Development.
       10
       11 You are free to distribute this software under the terms of
       12 the GNU General Public License.
       13 On Debian systems, the complete text of the GNU General Public
       14 License can be found in /usr/share/common-licenses/GPL file.

(I've added the line numbers.)

4.3 `changelog' file

This is a required file, which has a special format described in the Packaging Manual (section 3.2.3). This format is used by dpkg and other programs to obtain the version number, revision, distribution and urgency of your package.

For you, it is also important, since it is good to have documented all changes you have done. It will help people downloading your package to see whether there are there any unresolved issues with the package that they should know about instantly. It will be saved as `/usr/share/doc/gentoo/changelog.Debian.gz' in the binary package.

Dh_make creates a default one, this is what it looks like:

       1  gentoo (0.9.12-1) unstable; urgency=low
       2
       3   * Initial Release.
       4
       5  -- Josip Rodin <jrodin@jagor.srce.hr> Wed, 11 Nov 1998 21:02:14 +0100
       6
       7  Local variables:
       8  mode: debian-changelog
       9  End:

(I've added the line numbers.)

Line 1 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 shouldn't be changed to anything higher than `low'. :-)

Lines 3-5 are a log entry, where you document changes made in this package revision (not the upstream changes - there is special file for that purpose, created by upstream authors, installed as /usr/share/doc/gentoo/changelog.gz). New lines must be inserted just before the uppermost line that begins with asterisk (`*'). You can do it with dch(1), emacs(1) (lines 7-9 contain mode information for the Emacs editor), or any other text editor. You will end up with something like this:

       1  gentoo (0.9.12-1) unstable; urgency=low
       2
       3   * Initial Release.
       4   * This is my first Debian package.
       5   * Adjusted the Makefile to fix $DESTDIR problems.
       6
       7  -- Josip Rodin <jrodin@jagor.srce.hr> Wed, 11 Nov 1998 21:02:14 +0100
       8
       9  Local variables:
       10  mode: debian-changelog
       11 End:

(I've added the line numbers.)

When you release a new revision, you must increment the version number. You can do that with just `dch -i` or explicitly with `dch -v <version>-<revision>` and then insert the comments using your preferred editor. Tip: how to easily get the date in required format? Use `822-date`, or `date -R`.

New version information is added at the top of the changelog file. This is what the changelog looks like afterwards:

       1  gentoo (0.9.12-2) unstable; urgency=low
       2
       3   * Fixed a glitch in the menu file.
       4
       5  -- Josip Rodin <jrodin@jagor.srce.hr> Wed, 11 Nov 1998 22:15:39 +0100
       6
       7  gentoo (0.9.12-1) unstable; urgency=low
       8
       9   * Initial Release.
       10  * This is my first Debian package.
       11  * Adjusted the Makefile to fix $DESTDIR problems.
       12
       13 -- Josip Rodin <jrodin@jagor.srce.hr> Wed, 11 Nov 1998 21:02:14 +0100
       14
       15 Local variables:
       16 mode: debian-changelog
       17 End:

(I've added the line numbers.)

You can read more about new package versions/revisions later in Updating the package, Section 6.4.

4.4 `rules' file

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

Every `rules' file, as any other Makefile, consists of several rules specifying how to handle the source. Each rule consists of targets, filenames or names of actions that should be carried out (e.g. `build:' or `install:'). Rules that you want to execute are invoked as command line arguments (for example, `./debian/rules build` or `make -f rules install`). After the target name, you can name the dependency, program or file that that rule depends on. After that, there can be any number of commands (indented with <tab>!), until an empty line is found. There begins another rule. Multiple empty lines, and lines beginning with `#' (hash) are treated as comments and ignored.

You are probably confused now, but it will all be clear upon examination of the `rules' file that dh_make gives us as a default. You should also read the `make' entry in info for more information.

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. 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.

       1  #!/usr/bin/make -f
       2  # Made with the aid of dh_make, by Craig Small
       3  # Sample debian/rules that uses debhelper. GNU copyright 1997 by Joey Hess.
       4  # Some lines taken from debmake, by Christoph Lameter.
       5
       6  # Uncomment this to turn on verbose mode.
       7  #export DH_VERBOSE=1
       8
       9  # This is the debhelper compatibility version to use.
       10 export DH_COMPAT=1
       11
       12 build: build-stamp
       13 build-stamp:
       14	dh_testdir
       15
       16	# Add here commands to compile the package.
       17	$(MAKE)
       18
       19	touch build-stamp
       20
       21 clean:
       22	dh_testdir
       23	dh_testroot
       24	rm -f build-stamp
       25
       26	# Add here commands to clean up after the build process.
       27	-$(MAKE) clean
       28
       29	dh_clean
       30
       31 install: build-stamp
       32	dh_testdir
       33	dh_testroot
       34	dh_clean -k
       35	dh_installdirs
       36
       37	# Add here commands to install the package into debian/tmp.
       38	$(MAKE) install DESTDIR=`pwd`/debian/tmp
       39
       40 # Build architecture-independent files here.
       41 binary-indep: build install
       42 # We have nothing to do by default.
       43
       44 # Build architecture-dependent files here.
       45 binary-arch: build install
       46 #	dh_testversion
       47	dh_testdir
       48	dh_testroot
       49 #	dh_installdebconf
       50	dh_installdocs
       51	dh_installexamples
       52	dh_installmenu
       53 #	dh_installemacsen
       54 #	dh_installpam
       55 #	dh_installinit
       56	dh_installcron
       57	dh_installmanpages
       58	dh_installinfo
       59 #	dh_undocumented
       60	dh_installchangelogs
       61	dh_link
       62	dh_strip
       63	dh_compress
       64	dh_fixperms
       65	# You may want to make some executables suid here.
       66	dh_suidregister
       67 #	dh_makeshlibs
       68	dh_installdeb
       69 #	dh_perl
       70	dh_shlibdeps
       71	dh_gencontrol
       72	dh_md5sums
       73	dh_builddeb
       74
       75 binary: binary-indep binary-arch
       76 .PHONY: build clean binary-indep binary-arch binary install

(I've added the line numbers.)

You are probably familiar with lines like line 1 from shell and Perl scripts. It tells the operating system that this file is to be processed with /usr/bin/make.

Lines 12 through 19 describe the `build' (and its child `build-stamp') rule, which runs the application's own Makefile to compile the program.

The `clean' rule, as specified in lines 21-29, 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, starts with line 31. It basically runs the `install' rule from the program's own Makefile, but installs in `pwd`/debian/tmp directory - this is why we specified $(DESTDIR) as the root installation directory in gentoo's Makefile.

As the comments suggest, the `binary-indep' rule, on the line 41, is used to build architecture independent packages. As we don't have any, nothing will be done there. If your package is `Architecture: all' one, you need to include all the commands for building the package under this rule, and leave the next rule (`binary-arch') empty instead.

On to the next rule - `binary-arch', on lines 45 through 73, in which we run several small utilities from the debhelper package that do various operations on your package files 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:

• dh_testdir(1) checks that you are in the right directory (i.e. the top-level source directory),
• dh_testroot(1) checks that you have root permissions which is needed for binary* targets, and clean,
• dh_installmanpages(1) copies all the manpages it can find in the source tree to package (beware, this is DWIM),
• dh_strip(1) strips debugging headers from executable files and libraries, to make them smaller,
• dh_compress(1) gzips man pages and documentation larger than 4 kB,
• dh_installdeb(1) copies package related files (e.g. the maintainer scripts) under debian/tmp/DEBIAN directory,
• dh_shlibdeps(1) calculates shared libraries dependencies of the libraries and executables,
• dh_gencontrol(1) adds stuff to, and installs, the control file,
• dh_md5sums(1) generates MD5 checksums for all the files in the package.

For more complete information on what do all these dh_* scripts do, and what are their other options, please read respective manual pages. There are some other, possibly very useful, dh_* scripts, which were not mentioned here. If you need them, read the debhelper documentation.

The binary-arch section is the one where you really should comment out any lines that call features you don't need. For gentoo, I'll comment out lines about testversion, emacsen, pam, init, cron, manpages, info, undocumented, suidregister, makeshlibs, and perl, simply because gentoo doesn't need them. Also, on the line 60, I'll need to add ` FIXES', because that is the name of the upstream changelog file.

The last two lines (along with any other not explained ones) are just some more-or-less necessary things, regarding which you can read in the make manual, and the Packaging Manual. For now, they're not important to know about.