[ 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: optional
4 Maintainer: Josip Rodin <[email protected]>
5 Build-Depends: debhelper (>> 3.0.0)
6 Standards-Version: 3.6.2
7
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":"` "), "; \
done
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:
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 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
7
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.)
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.
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.
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.
3
4 It was downloaded from: ftp://ftp.obsession.se/gentoo/
5
6 Upstream author: Emil Brink <[email protected]>
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 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
.
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 <[email protected]> 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 <[email protected]> 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 # Sample debian/rules that uses debhelper.
3 # GNU copyright 1997 to 1999 by Joey Hess.
4
5 # Uncomment this to turn on verbose mode.
6 #export DH_VERBOSE=1
7
8 # This is the debhelper compatibility version to use.
9 export DH_COMPAT=4
10
11 CFLAGS = -g
12 ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
13 CFLAGS += -O0
14 else
15 CFLAGS += -O2
16 endif
17
18 build: build-stamp
19 build-stamp:
20 dh_testdir
21
22 # Add here commands to compile the package.
23 $(MAKE)
24 #docbook-to-man debian/gentoo.sgml > gentoo.1
25
26 touch build-stamp
27
28 clean:
29 dh_testdir
30 dh_testroot
31 rm -f build-stamp
32
33 # Add here commands to clean up after the build process.
34 -$(MAKE) clean
35
36 dh_clean
37
38 install: build
39 dh_testdir
40 dh_testroot
41 dh_clean -k
42 dh_installdirs
43
44 # Add here commands to install the package into debian/gentoo.
45 $(MAKE) install DESTDIR=$(CURDIR)/debian/gentoo
46
47 # Build architecture-independent files here.
48 binary-indep: build install
49 # We have nothing to do by default.
50
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
80
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:
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 the targets `binary-arch', `binary-indep' and `clean',
dh_installman(1) will copy the manpages into the right place in
the destination directory, you just have to tell it where they are, relative to
the top-level source directory,
dh_strip(1) strips debugging headers from executable files and
libraries, to make them smaller,
dh_compress(1) compresses man pages and documentation larger than
4 kB with gzip(1),
dh_installdeb(1) copies package related files (e.g. the
maintainer scripts) to the debian/gentoo/DEBIAN directory,
dh_shlibdeps(1) calculates shared libraries dependencies of the
libraries and executables,
dh_gencontrol(1) installs a fine-tuned version of the control file
into debian/gentoo/DEBIAN,
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 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
[email protected]