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


Debian New Maintainers' Guide
Chapter 4 - Required files under the debian directory


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, apt-get, apt-cache, aptitude, and other package management tools will use to manage the package. It is defined by the Debian Policy Manual, 5 'Control files and their fields'.

Here is the control file dh_make created for us:

      1 Source: gentoo
      2 Section: unknown
      3 Priority: extra
      4 Maintainer: Josip Rodin <joy-mg@debian.org>
      5 Build-Depends: debhelper (>= 7.0.50~)
      6 Standards-Version: 3.8.4
      7 Homepage: <insert the upstream URL, if relevant>
      8
      9 Package: gentoo
     10 Architecture: any
     11 Depends: ${shlibs:Depends}, ${misc:Depends}
     12 Description: <insert up to 60 chars description>
     13  <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 archive 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. See the Debian Policy Manual, 2.4 'Sections' and List of sections in 'sid' for the guidance.

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 Debian Policy Manual, 2.5 'Priorities' for the guidance.

Section and priority are used by the frontends like aptitude 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 will change the priority to "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 as the Build-Depends field. You can also have the Build-Depends-Indep field as an additional line, here. (see the Debian Policy Manual, 7.7 'Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep'). Some packages like gcc and make which are required by the build-essential package are implied. If you need to have other tools to build your package, you should add them to these fields. Multiple entries are separated with commas; read on for the explanation of binary dependencies to find out more about the syntax of these lines.

If you are not sure which one should be used, use the Build-Depends field to be on the safe side. [16]

To find out what packages your package needs to be built run the command:

     $ dpkg-depcheck -d ./configure

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-Depends entry. If you use ldd for this purpose, it will report indirect lib dependencies as well, resulting in the problem of excessive build dependencies.

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 Manual standards this package follows, the one you read while making your package.

On line 7 you can put the URL of the homepage for the upstream program.

Line 9 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 10 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 11 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, Breaks, 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 lower, lower or equal, exactly equal, greater or equal and strictly greater, 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}, ${perl:Depends}, ${misc:Depends}, etc. These entries are substituted by the list generated by other debhelper components when the dh_gencontrol(1) command is executed.

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, after your package has been built and installed into the temporary directory. This list of shared library dependencies is used for ${shlibs:Depends}.

The package list generated by the dh_perl(1) is used for ${perl:Depends}.

Some debhelper commands may make the generated package need to depend on some other packages. This list of required packages is used for ${misc:Depends}.

Having said all that, we can leave the Depends field exactly as it is now, and insert another line after it saying "Suggests: file", because gentoo can use some features provided by that file package.

Line 12 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, two-pane X file manager".

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

Let's insert Vcs-* fields documented in Developer's Reference, 6.2.5. 'Version Control System location' between line 6 and 7. Let's assume that the gentoo package is located in Debian Alioth Git Service at git://git.debian.org/git/collab-maint/gentoo.git.

Finally, here is the updated control file:

      1 Source: gentoo
      2 Section: x11
      3 Priority: optional
      4 Maintainer: Josip Rodin <joy-mg@debian.org>
      5 Build-Depends: debhelper (>= 7.0.5), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
      6 Standards-Version: 3.8.4
      7 Vcs-Git: git://git.debian.org/git/collab-maint/gentoo.git
      8 Vcs-browser: http://git.debian.org/?p=collab-maint/gentoo.git
      9 Homepage: http://www.obsession.se/gentoo/
     10
     11 Package: gentoo
     12 Architecture: any
     13 Depends: ${shlibs:Depends}, ${misc:Depends}
     14 Suggests: file
     15 Description: fully GUI-configurable, two-pane X file manager
     16  gentoo is a two-pane file manager for the X Window System. gentoo lets the
     17  user do (almost) all of the configuration and customizing from within the
     18  program itself. If you still prefer to hand-edit configuration files,
     19  they're fairly easy to work with since they are written in an XML format.
     20  .
     21  gentoo features a fairly complex and powerful file identification system,
     22  coupled to a object-oriented style system, which together give you a lot
     23  of control over how files of different types are displayed and acted upon.
     24  Additionally, over a hundred pixmap images are available for use in file
     25  type descriptions.
     26  .
     29  gentoo was written from scratch in ANSI C, and it utilises the GTK+ toolkit
     30  for its interface.

(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 Debian Policy Manual, but the content is (Debian Policy Manual, 12.5 'Copyright information'). You may also consult DEP-5: Machine-parseable debian/copyright.

dh_make can give you a template copyright file. Let's use the "--copyright gpl2" option here to get a template file for the gentoo package released under GPL-2.

You must fill in missing information such as the place you got the package from, the actual copyright notice and their license to complete this file. For the common free software licenses such as GNU GPL-1, GNU GPL-2, GNU GPL-3, LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0 or the Artistic license, you can just refer to the appropriate file in /usr/share/common-licenses/ directory that exists on every Debian system. Otherwise, you must include the complete license.

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

      1 Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=135
      2 Name: gentoo
      3 Maintainer: Josip Rodin <joy-mg@debian.org>
      4 Source: http://sourceforge.net/projects/gentoo/files/
      5
      6 Copyright: 1998-2010 Emil Brink <emil@obsession.se>
      7 License: GPL-2+
      8
      9 Files: icons/*
     10 Copyright: 1998 Johan Hanson <johan@tiq.com>
     11 License: GPL-2+
     12
     13 Files: debian/*
     14 Copyright: 1998-2010 Josip Rodin <joy-mg@debian.org>
     15 License: GPL-2+
     16
     17 License: GPL-2+
     18  This program is free software; you can redistribute it and/or modify
     19  it under the terms of the GNU General Public License as published by
     20  the Free Software Foundation; either version 2 of the License, or
     21  (at your option) any later version. 
     22  .
     23  This program is distributed in the hope that it will be useful,
     24  but WITHOUT ANY WARRANTY; without even the implied warranty of
     25  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
     26  GNU General Public License for more details.
     27 .
     28  You should have received a copy of the GNU General Public License along
     29  with this program; if not, write to the Free Software Foundation, Inc.,
     30  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
     31  .
     32  On Debian systems, the full text of the GNU General Public
     33  License version 2 can be found in the file
     34  `/usr/share/common-licenses/GPL-2'.

(I've added the line numbers.)

Please follow the HOWTO provided by ftpmasters and sent to 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 Debian Policy Manual, 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
     2
     3   * Initial release (Closes: #nnnn)  <nnnn is the bug number of your ITP>
     4
     5  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
     6

(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) [17], 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). Let's assume your ITP (Intent To Package) bug report number was "12345". 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
     2
     3   * Initial Release. Closes: #12345
     4   * This is my first Debian package.
     5   * Adjusted the Makefile to fix $(DESTDIR) problems.
     6
     7  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
     8

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


4.4.1 Targets of rules file

Every rules file, as any other Makefile, consists of several targets and their rules specifying how to handle the source. Debian Policy Manual, 4.9 'Main building script: debian/rules' explains its details.

The simplified explanation of targets are the following.

Rules that you want to execute are invoked as command line arguments (for example, "./debian/rules build" or "fakeroot make -f debian/rules binary"). 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 "info make" for more information.


4.4.2 Default rules file

Newer dh_make generates a very simple but powerful default rules file using the dh command:

      1 #!/usr/bin/make -f
      2 # -*- makefile -*-
      3 # Sample debian/rules that uses debhelper.
      4 # This file was originally written by Joey Hess and Craig Small.
      5 # As a special exception, when this file is copied by dh-make into a
      6 # dh-make output file, you may use that output file without restriction.
      7 # This special exception was added by Craig Small in version 0.37 of dh-make.
      8
      9 # Uncomment this to turn on verbose mode.
     10 #export DH_VERBOSE=1
     11
     12 %:
     13        dh $@

(I've added the line numbers. In the actual 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.

Line 10 can be uncommented to set DH_VERBOSE variable to 1. Then, the dh command will output which dh_* commands are executed by the dh command. You can also add "export DH_OPTIONS=-v" line here. Then each dh_* command will output which commands are executed by each dh_* command. This helps you to understand what exactly is going on behind this simple rules file and to debug its problems. This new dh is a core part of the debhelper tools and does not hide anything from you.

Lines 12 and 13 are where all the work is done. The percent sign means any targets which then call a single program, dh with the target name. [21] The dh command is a wrapper script which runs appropriate sequences of dh_* programs depending on its argument. [22]

The function of dh_* commands are almost self-evident from their names. [24] There are few notable ones worth making (over)simplified explanation here assuming typical build environment based on Makefile. [25]

Targets which require the fakeroot command contain dh_testroot. If you are not pretending to be root using this command, it exits with an error.

The important part to know about the rules file created by dh_make, is that it is just a suggestion. It will work for most packages but for more complicated ones, don't be afraid to customize it to fit your needs. Only things that you must not change are the names of the rules, because all the tools use these names, as mandated by the Debian Policy.

Although "install" is not required target, it is supported. "fakeroot dh install" behaves like "fakeroot dh binary" but stops after dh_fixperms.


4.4.3 Customization of rules file

There are many ways to customize the rules file created with the new dh command.

The "dh $@" command can be customized as follows. [28]

For sources using Autotools, use combination of above as "dh --with autotools-dev --with autoreconf $@" to be most current with the GNU Build System.

Many dh_* commands invoked by the new dh command can be customized by the corresponding configuration files in the debian directory. See Other files under the debian directory, Chapter 5 and the manpage of each command for the customization of such features.

Some dh_* commands invoked by the new dh command may require you to run it with some arguments or to run additional commands with them or to skip them. For such cases, you create an override_dh_foo target with its rule in the rules file only for the dh_foo command you want to change. It basically say "run me instead". [30]

Please note that the dh_auto_* commands tend to do more than what has been discussed as (over)simplified explanation to take care all the corner cases. Use of simplified equivalent command instead of these in override_dh_* targets except the override_dh_auto_clean target is a bad idea since it may kill such debhelper's smart features.

If you want to store the system configuration data for the gentoo package in the /etc/gentoo directory instead of the usual /etc directory, you can override the default --sysconfig=/etc argument given by the dh_auto_configure command to the ./configure command by the following. [31]

     override_dh_auto_configure:
             dh_auto_configure -- --sysconfig=/etc/gentoo

The arguments given after -- are appended to the default arguments of the auto-executed program to override them. Using the dh_auto_configure command is better than the ./configure command here since it will only override the --sysconfig argument and keeps well intended other arguments to the ./configure command.

If Makefile of a source for gentoo requires you to specify build as its target to build it [32], you create an override_dh_auto_build target to enable it.

     override_dh_auto_build:
             dh_auto_build -- build

This ensures to run $(MAKE) with all the default arguments given by the dh_auto_build command and build argument.

If Makefile of a source for gentoo requires you to specify the packageclean target to clean it for Debian package instead of the distclean or clean targets in the Makefile file, you create an override_dh_auto_clean target to enable it.

     override_dh_auto_clean:
             $(MAKE) packageclean

If Makefile of a source for gentoo contains test target which you do not want to run for the Debian package building process, you can use empty override_dh_auto_test target to skip it.

     override_dh_auto_test:

If gentoo has an unusual upstream changelog file called FIXES, dh_installchangelogs will not install that file by default. The dh_installchangelogs command requires FIXES as its argument to install it. [33]

     override_dh_installchangelogs:
             dh_installchangelogs FIXES

When you use the new dh command, use of explicit targets such as the ones listed in Targets of rules file, Section 4.4.1 except get-orig-source target may make it difficult to understand their exact effects. Please limit explicit targets to override_dh_* targets and completely independent ones, if possible.


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


Debian New Maintainers' Guide

version 1.2.25, 2010-12-22 12:44:34 UTC

Josip Rodin joy-mg@debian.org