[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ A ] [ next ]
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.
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: extra
4 Maintainer: Josip Rodin <joy-mg@debian.org>
5 Build-Depends: debhelper (>= 7)
6 Standards-Version: 3.8.3
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 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 "extra" 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 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.
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.
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-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.
On line 7 you can put the URL of the homepage for the upstream package.
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:, 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:
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:
Frontends such as dselect or aptitude will prompt you to install the recommended packages along with your package; dselect will even insist. dpkg and apt-get will ignore this field, though. Use this for packages that are not strictly necessary but are typically used with your program.
Suggests:
When a user installs your program, all frontends will likely prompt them to install the suggested packages. dpkg and apt-get won't care. 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 problems 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 the /usr/share/doc/debian-policy/virtual-package-names-list.txt.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 overwritten with the files from your package.
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 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 X file manager using GTK+".
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.
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 (>> 3.0.0), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
6 Standards-Version: 3.8.3
7 Homepage: http://www.obsession.se/gentoo/
8
9 Package: gentoo
10 Architecture: any
11 Depends: ${shlibs:Depends}, ${misc:Depends}
12 Suggests: file
13 Description: fully GUI configurable X file manager using GTK+
14 gentoo is a file manager for Linux written from scratch in pure C. It
15 uses the GTK+ toolkit for all of its interface needs. gentoo provides
16 100% GUI configurability; no need to edit config files by hand and re-
17 start the program. gentoo supports identifying the type of various
18 files (using extension, regular expressions, or the 'file' command),
19 and can display files of different types with different colors and icons.
20 .
21 gentoo borrows some of its look and feel from the classic Amiga file
22 manager "Directory OPUS" (written by Jonathan Potter).
(I've added the line numbers.)
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 can give you a template copyright file, use the --copyright option to select the right template. As gentoo is licensed under the GPLv2 license, using the --copyright gpl2 option will give the following:
1 This work was packaged for Debian by:
2
3 Josip Rodin <joy-mg@debian.org> on Wed, 11 Nov 1998 21:02:14 +0100.
4
5 It was downloaded from:
6
7 <url://example.com>
8
9 Upstream Author(s):
10
11 <put author's name and email here>
12
13 Copyright:
14
15 <Copyright (C) YYY Firstname Lastname>
16 <likewise for another author>
17
18 License:
19
20 ### SELECT: ###
21 This package is free software; you can redistribute it and/or modify
22 it under the terms of the GNU General Public License as published by
23 the Free Software Foundation; either version 2 of the License, or
24 (at your option) any later version.
25 ### OR ###
26 This package is free software; you can redistribute it and/or modify
27 it under the terms of the GNU General Public License version 2 as
28 published by the Free Software Foundation.
29 ##########
30
31 This package is distributed in the hope that it will be useful,
32 but WITHOUT ANY WARRANTY; without even the implied warranty of
33 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
34 GNU General Public License for more details.
35
36 You should have received a copy of the GNU General Public License
37 along with this package; if not, write to the Free Software
38 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
39
40 Debian systems, the complete text of the GNU General
41 License version 2 can be found in `/usr/share/common-licenses/GPL-2'.
42
43 Debian packaging is:
44
45 Copyright (C) 1998 Josip Rodin <joy-mg@debian.org>
46
47 You can redistribute it and/or modify
48 it under the terms of the GNU General Public License as published by
49 Free Software Foundation; either version 2 of the License, or
50 (at your option) any later version.
51
52 # Please also look if there are files or directories which have a
53 # different copyright/license attached and list them 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 work was packaged for Debian by:
2
3 Josip Rodin <joy-mg@debian.org> on 2 Wed, 11 Nov 1998 21:02:14 +0100.
4
5 It was downloaded from:
6 ftp://ftp.obsession.se/gentoo/
7
8 Upstream author:
9
10 Emil Brink <emil@obsession.se>
11
12 Copyright:
13 Copyright (C) 1998-99 by Emil Brink, Obsession Development.
14
15 License:
16 You are free to distribute this software under the terms of
17 the GNU General Public License either version 2 of the License,
18 or (at your option) any later version.
19
20 This package is distributed in the hope that it will be useful,
21 but WITHOUT ANY WARRANTY; without even the implied warranty of
22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 GNU General Public License for more details.
24
25 You should have received a copy of the GNU General Public License
26 along with this package; if not, write to the Free Software
27 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
28
29 On Debian systems, the complete text of the GNU General
30 Public License version 2 can be found in `/usr/share/common-licenses/GPL-2'.
31
32 The Debian packaging is:
33
34 Copyright (C) 1998 Josip Rodin <joy-mg@debian.org>
35
36 You can redistribute it and/or modify
37 it under the terms of the GNU General Public License as published by
38 Free Software Foundation; either version 2 of the License, or
39 (at your option) any later version.
(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
.
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
2
3 * Initial Release.
4
5 -- Josip Rodin <joy-mg@debian.org> Wed, 11 Nov 1998 21:02:14 +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'), 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
2
3 * Initial Release.
4 * This is my first Debian package.
5 * Adjusted the Makefile to fix $DESTDIR problems.
6
7 -- Josip Rodin <joy-mg@debian.org> Wed, 11 Nov 1998 21:02:14 +0100
8
(I've added the line numbers.)
You can read more about updating the changelog file later in Updating the package, Chapter 9.
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 # -*- 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 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.
Line 10 can be uncommented which will mean DH_VERBOSE variable is set to 1. This will mean the debhelper tools will output more information which can be helpful in debugging what is going wrong.
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. For example, when dpkg-buildpackage wants to do the pre-build cleaning, it runs debian/rules clean which in turn calls "dh clean".
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 major change between older rules files that used debhelper and the current ones, is that the old ones had very large rules file which called each dh_* script, while the new ones have a single line calling dh.
Previously, if you wanted to change the behaviour of a dh_* script you found the relevant line in the rules file and adjusted it. Now you use overrides lines in the rules file, only for the command you want to change.
Override lines are targets that basically say "run me instead". If you have a target for override_dh_foo then instead of dh_foo being run, your commands for that target are run instead.
Gentoo has an unusual upstream changelog file called FIXES. Now, dh_installchangelogs will not install that file by default, so we need to change what is run at this point and the following lines need to be appended to the rules file:
override_dh_installchangelogs:
dh_installchangelogs FIXES
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ A ] [ next ]
Debian New Maintainers' Guide
version 1.2.13, 5 June 2008.joy-mg@debian.org