[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ A ] [ next ]

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

There is a new subdirectory under the program's source directory, it's called `debian'. There are a number of files in this directory that we should edit 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, dselect and other package management tools will use to manage the package.

Here is the control file dh_make created for us:

       1  Source: gentoo
       2  Section: unknown
       3  Priority: optional
       4  Maintainer: Josip Rodin <[email protected]>
       5  Build-Depends: debhelper (>> 3.0.0)
       6  Standards-Version: 3.6.2
       8  Package: gentoo
       9  Architecture: any
       10 Depends: ${shlibs:Depends}
       11 Description: <insert up to 60 chars description>
       12  <insert long description, indented with spaces>

(I've added the line numbers.)

Lines 1-6 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 the source 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 programs that don't fit anywhere else, and many more.

Let's change it then to x11. (A "main/" prefix is implied so we can omit it.)

Line 3 describes how important it is that the user installs this package. See the Policy manual for guidance on what to set this field to. The "optional" priority will usually work for new packages.

Section and priority are used by frontends like dselect when they sort packages and select defaults. Once you upload the package to Debian, the value of these two fields can be overridden by the archive maintainers, in which case you will be notified by email.

As this is a normal priority package and doesn't conflict with anything else, we'll leave it as "optional".

Line 4 is the name and email address of the maintainer. Make sure that this field includes a valid "To: " header for an email, because after you upload it, the bug tracking system will use it to deliver bug emails to you. Avoid using commas, ampersands and parenthesis.

The 5th line includes the list of packages required to build your package. Some packages like gcc and make are implied, see the build-essential package for details. If some non-standard compiler or other tool is needed to build your package, you should add it to the `Build-Depends' line. Multiple entries are separated with commas; read on for the explanation of binary dependencies to find out more about the syntax of this field.

You can also have Build-Depends-Indep, Build-Conflicts and other fields here. This data will be used by the Debian automatic package building software in order to create binary packages for other computer platforms. See the Policy manual for more information about the build-dependencies and the Developers' Reference for more information about these other platforms (architectures) and how to port software to them.

Here's a hack you can use to find out which packages your package needs to be built:

       strace -f -o /tmp/log ./configure
       # or make instead of ./configure, if the package doesn't use autoconf
       for x in `dpkg -S $(grep open /tmp/log|\
                           perl -pe 's!.* open\(\"([^\"]*).*!$1!' |\
                           grep "^/"| sort | uniq|\
                           grep -v "^\(/tmp\|/dev\|/proc\)" ) 2>/dev/null|\
                           cut -f1 -d":"| sort | uniq`; \
             do \
               echo -n "$x (>=" `dpkg -s $x|grep ^Version|cut -f2 -d":"` "), "; \

To manually find exact build dependency for /usr/bin/foo, you execute

       objdump -p /usr/bin/foo | grep NEEDED

and for each library listed, e.g., libfoo.so.6, execute

       dpkg -S libfoo.so.6

Then you just take -dev version of every package as `Build-deps' entry. If you use ldd for this purpose, it will report indirect lib dependencies as well, resulting in the problem of excessive build deps.

Gentoo also happens to require xlibs-dev, libgtk1.2-dev and libglib1.2-dev to build, so we'll add them here next to debhelper.

Line 6 is the version of the Debian Policy standards this package follows, the versions of the Policy manual you read while making your package.

Line 8 is the name of the binary package. This is usually the same as the name of the source package, but it doesn't necessarily have to be that way.

Line 9 describes the CPU architecture the binary package can be compiled for. We'll leave this as "any" because dpkg-gencontrol(1) will fill in the appropriate value for any machine this package gets compiled on.

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 the `binary-indep' rule instead of `binary-arch' for building the package.

Line 10 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 usually behave the same way when dealing with these relations; if not, it will be explained. (see dpkg(8), dselect(8), apt(8), aptitude(1) etc.)

This is what the dependencies mean:

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. For example,

       Depends: foo (>= 1.2), libbar1 (= 1.3.4)
       Conflicts: baz
       Recommends: libbaz4 (>> 4.0.7)
       Suggests: quux
       Replaces: quux (<< 5), quux-foo (<= 7.6)

The last feature you need to know about is ${shlibs:Depends}. After your package has been built and installed into the temporary directory, dh_shlibdeps(1) will scan it for binaries and libraries, determine their shared library dependencies and detect which packages they are in, such as libc6 or xlib6g. It'll pass on the list to dh_gencontrol(1) which will fill it in the right place, and you won't have to worry about this yourself.

Having said all that, we can leave the Depends: line exactly as it is now, and insert another line after it saying Suggests: 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 "fully GUI configurable X file manager using GTK+".

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

Finally, here is the updated control file:

       1  Source: gentoo
       2  Section: x11
       3  Priority: optional
       4  Maintainer: Josip Rodin <[email protected]>
       5  Build-Depends: debhelper (>> 3.0.0), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
       6  Standards-Version: 3.5.2
       8  Package: gentoo
       9  Architecture: any
       10 Depends: ${shlibs:Depends}
       11 Suggests: file
       12 Description: fully GUI configurable X file manager using GTK+
       13  gentoo is a file manager for Linux written from scratch in pure C. It
       14  uses the GTK+ toolkit for all of its interface needs. gentoo provides
       15  100% GUI configurability; no need to edit config files by hand and re-
       16  start the program. gentoo supports identifying the type of various
       17  files (using extension, regular expressions, or the 'file' command),
       18  and can display files of different types with different colors and icons.
       19  .
       20  gentoo borrows some of its look and feel from the classic Amiga file
       21  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 content is (section 12.6 "Copyright information").

dh_make created a default one, this is what it looks like:

       1  This package was debianized by Josip Rodin <[email protected]> on
       2  Wed, 11 Nov 1998 21:02:14 +0100.
       4  It was downloaded from <fill in ftp site>
       6  Upstream Author(s): <put author(s) name and email here>
       8  Copyright:
       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.

In short, here's how gentoo's copyright file should look like:

       1  This package was debianized by Josip Rodin <[email protected]> on
       2  Wed, 11 Nov 1998 21:02:14 +0100.
       4  It was downloaded from: ftp://ftp.obsession.se/gentoo/
       6  Upstream author: Emil Brink <[email protected]>
       8  This software is copyright (c) 1998-99 by Emil Brink, Obsession
       9  Development.
       11 You are free to distribute this software under the terms of
       12 the GNU General Public License  either version 2 of the License,
       13 or (at your option) any later version.
       14 On Debian systems, the complete text of the GNU General Public
       15 License can be found in the file `/usr/share/common-licenses/GPL-2'.

(I've added the line numbers.)

Please follow the HOWTO from the debian-devel-announce: http://lists.debian.org/debian-devel-announce/2006/03/msg00023.html .

4.3 `changelog' file

This is a required file, which has a special format described in the Policy section 4.4 "debian/changelog". 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 issues with the package that they should know about. It will be saved as `/usr/share/doc/gentoo/changelog.Debian.gz' in the binary package.

dh_make created a default one, and this is how it looks like:

       1  gentoo (0.9.12-1) unstable; urgency=low
       3   * Initial Release.
       5  -- Josip Rodin <[email protected]>  Wed, 11 Nov 1998 21:02:14 +0100

(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 even `experimental'), 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 the upstream authors, which you will later install 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), or manually with a text editor.

You will end up with something like this:

       1  gentoo (0.9.12-1) unstable; urgency=low
       3   * Initial Release.
       4   * This is my first Debian package.
       5   * Adjusted the Makefile to fix $DESTDIR problems.
       7  -- Josip Rodin <[email protected]> Wed, 11 Nov 1998 21:02:14 +0100

(I've added the line numbers.)

You can read more about updating the changelog file later in Updating the package, Chapter 9.

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, but different than the one(s) in the upstream source. Unlike other files in debian/, this one is marked as executable.

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 the rule depends on. After that, there can be any number of commands, indented with <tab>. A new rule begins with the target declaration in the first column. 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 Policy.

Here's (approximately) how the default debian/rules file that dh_make generated for us looks like:

       1  #!/usr/bin/make -f
       2  # Sample debian/rules that uses debhelper.
       3  # GNU copyright 1997 to 1999 by Joey Hess.
       5  # Uncomment this to turn on verbose mode.
       6  #export DH_VERBOSE=1
       8  # This is the debhelper compatibility version to use.
       9  export DH_COMPAT=4
       11 CFLAGS = -g
       12 ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
       13 CFLAGS += -O0
       14 else
       15 CFLAGS += -O2
       16 endif
       18 build: build-stamp
       19 build-stamp:
       20        dh_testdir
       22        # Add here commands to compile the package.
       23        $(MAKE)
       24        #docbook-to-man debian/gentoo.sgml > gentoo.1
       26        touch build-stamp
       28 clean:
       29        dh_testdir
       30        dh_testroot
       31        rm -f build-stamp
       33        # Add here commands to clean up after the build process.
       34        -$(MAKE) clean
       36        dh_clean
       38 install: build
       39        dh_testdir
       40        dh_testroot
       41        dh_clean -k
       42        dh_installdirs
       44        # Add here commands to install the package into debian/gentoo.
       45        $(MAKE) install DESTDIR=$(CURDIR)/debian/gentoo
       47 # Build architecture-independent files here.
       48 binary-indep: build install
       49 # We have nothing to do by default.
       51 # Build architecture-dependent files here.
       52 binary-arch: build install
       53        dh_testdir
       54        dh_testroot
       55 #      dh_installdebconf
       56        dh_installdocs
       57        dh_installexamples
       58        dh_installmenu
       59 #      dh_installlogrotate
       60 #      dh_installemacsen
       61 #      dh_installpam
       62 #      dh_installmime
       63 #      dh_installinit
       64        dh_installcron
       65        dh_installman
       66        dh_installinfo
       67 #      dh_undocumented
       68        dh_installchangelogs ChangeLog
       69        dh_link
       70        dh_strip
       71        dh_compress
       72        dh_fixperms
       73 #      dh_makeshlibs
       74        dh_installdeb
       75 #      dh_perl
       76        dh_shlibdeps
       77        dh_gencontrol
       78        dh_md5sums
       79        dh_builddeb
       81 binary: binary-indep binary-arch
       82 .PHONY: build clean binary-indep binary-arch binary install

(I've added the line numbers. In the actual debian/rules file, the leading white spaces are TAB codes.)

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.

The meaning of DH_* variables mentioned on lines 6 and 9 should be evident from the short description. For more information on DH_COMPAT read the "Debhelper compatibility levels" section of the debhelper(1) manual page.

The lines 11 through 16 are a skeleton of support for DEB_BUILD_OPTIONS parameters, described in the Policy section 10.1 "Binaries". Basically, these things control if the binaries are to be built with the debugging symbols, and if they should be stripped upon installation. Again, this is just a skeleton, a hint that you should do it. You should check into how the upstream build system handles the inclusion of debugging symbols and stripping on installation and implement this yourself.

Usually you can tell gcc to compile with "-g" using the CFLAGS variable -- if that's the case for your package, propagate the variable by appending CFLAGS="$(CFLAGS)" to the $(MAKE) invocation in the build rule (see below). Alternatively, if your package uses an autoconf configure script, you can pass it to configure by prepending the above string to the ./configure invocation in the build rule.

As for the stripping, programs are commonly configured to install themselves unstripped, and often without an option to change this. Fortunately, you still have dh_strip(1) which will detect when the DEB_BUILD_OPTIONS=nostrip flag is set and silently exit.

Lines 18 through 26 describe the `build' (and its child `build-stamp') rule, which runs make with the application's own Makefile to compile the program. If your package uses GNU configure utilities to build binaries, please make absolutely sure to read /usr/share/doc/autotools-dev/README.Debian.gz . We'll talk about the commented out docbook-to-man example later in manpage.1.ex, manpage.sgml.ex, Section 5.8.

The `clean' rule, as specified in lines 28-36, 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 have make ignore return values (failures) using a `-' in front of the command name.

The installation process, the `install' rule, starts with line 38. It basically runs the `install' rule from the program's own Makefile, but installs in the $(CURDIR)/debian/gentoo 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 48, is used to build packages independent of architecture. As we don't have any, nothing will be done there.

On to the next rule - `binary-arch', on lines 52 through 79, 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.

If your package is an `Architecture: all' one, you need to include all the commands for building the package under the `binary-indep' rule, and leave the `binary-arch' rule empty instead.

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

For more complete information on what do all these dh_* scripts do, and what their other options are, please read their 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 or remove any lines that call features you don't need. For gentoo, I'll comment out lines about examples, cron, init, man and info, simply because gentoo doesn't need them. Also, on the line 68, I'll replace `ChangeLog' with `FIXES', because that is the real name of the upstream changelog file.

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

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ A ] [ next ]

Debian New Maintainers' Guide

version 1.2.11, 12 January 2007.

Josip Rodin [email protected]