[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ next ]
This document tries to describe building of a Debian package to the common Debian user, and the prospectus developer. It uses pretty common language, and it's well covered with working examples. There is an old Roman saying, Longum iter est per preaecepta, breve et efficax per exempla! (It's a long way by the rules, but short and efficient with examples!).
This document has been updated for the Debian squeeze release. [1]
One of the things that makes Debian such a top-notch distribution is its package system. While there is a vast quantity of software already in the Debian format, sometimes you need to install software that isn't. You may be wondering how you can make your own packages and perhaps you think it is a very difficult task. Well, if you are a real novice on Linux, it is hard, but if you were rookie, you wouldn't be reading this doc now. :-) You do need to know a little about Unix programming but you certainly don't need to be a wizard.
One thing is certain, though: to properly create and maintain Debian packages you need many hours. Make no mistake, for our system to work the maintainers need to be both technically competent and diligent.
This document will explain every little (at first maybe irrelevant) step, and help you create that first package, and to gain some experience in building next releases of that and maybe other packages later on.
If you need some help on packaging, please read Where to ask for help, Section 1.4.
Newer versions of this document should always be available online at http://www.debian.org/doc/maint-guide/
and in the maint-guide
package.
Before you start anything, you should make sure that you have properly installed some additional packages needed for development. Note that the list doesn't contain any packages marked essential or required - we expect that you have those installed already.
The following packages come with the standard Debian installation, so you probably have them already (along with any additional packages they depend on). Still, you should check it with "aptitude show package".
The most important package to install on your development system is the
build-essential
package. Once you try to install it, it will
pull in other packages required to have a basic build environment.
For some types of packages, that is all you will require, however there is another set of packages that while not essential for all package builds are useful to have install or may be required by your package:
file
- this handy program can determine what type a file is. (see
file(1)
)
patch
- this very useful utility will take a file containing a
difference listing (produced by the diff
program) and apply it to
the original file, producing a patched version. (see patch(1)
)
perl
- Perl is one of the most used interpreted scripting
languages on today's Unix-like systems, often referred to as "Unix's Swiss
Army Chainsaw". (see perl(1)
)
python
- Python is another of the most used interpreted scripting
languages on the Debian system that combines remarkable power with very clear
syntax. (see python(1)
)
autoconf
, automake
and autotools-dev
-
many newer programs use configure scripts and Makefile
files
preprocessed with help of programs like these. (see "info
autoconf", "info automake"). The
autotools-dev
keeps up-to-date versions of certain auto files and
has documentation about the best way to use those files.
dh-make
and debhelper
- dh-make
is
necessary to create the skeleton of our example package, and it will use some
of the debhelper
tools for creating packages. They are not
essential for creation of packages, but are highly recommended for new
maintainers. It makes the whole process very much easier to start, and control
afterwards. (see dh_make(1)
, debhelper(1)
,
/usr/share/doc/debhelper/README
) [2]
devscripts
- this package contains some nice and useful scripts
that can be helpful to the maintainers, but they are also not necessary for
building packages. Packages recommended and suggested by this package are
worth looking into. (see /usr/share/doc/devscripts/README.gz
)
fakeroot
- this utility lets you emulate being root which is
necessary for some parts of the build process. (see fakeroot(1)
)
gnupg
- a tool that enables you to digitally sign
packages. This is especially important if you want to distribute it to other
people, and you will certainly be doing that when your work gets included in
the Debian distribution. (see gpg(1)
)
gfortran
- the GNU Fortran 95 compiler, necessary if your program
is written in Fortran. (see gfortran(1)
)
gpc
- the GNU Pascal compiler, necessary if your program is
written in Pascal. Worthy of note here is fp-compiler
, the Free
Pascal Compiler, which is also good at this task. (see gpc(1)
,
ppc386(1)
)
xutils-dev
- some programs, usually those made for X11, also use
these programs to generate Makefile
files from sets of macro
functions. (see imake(1)
, xmkmf(1)
)
lintian
- this is the Debian package checker that can let you know
of any common mistakes after you build the package, and explains the errors
found. (see lintian(1)
,
/usr/share/doc/lintian/lintian.html/index.html
)
pbuilder
- this package contains programs which are used for
creating and maintaining chroot
environment. Building Debian
package in this chroot
environment verifies the proper build
dependency and avoid FTBFS (Fails To Build From Source) bugs. (see
pbuilder(8)
and pdebuild(1)
)
patchutils
- this package contains some utilities to work with
patches such as the lsdiff
, interdiff
and
filterdiff
commands.
quilt
- this package helps you to manage a series of patches by
keeping track of the changes each of them makes. They are logically organized
as a stack, and you can apply (=push), un-apply (=pop), refresh them easily by
traveling into the stack. (see quilt(1)
,
/usr/share/doc/quilt/README.Debian
)
git
- this package provides popular version control system
designed to handle very large projects with speed and efficiency; it is used
for many high profile open source projects, most notably the Linux kernel.
(see git(1)
, /usr/share/doc/git-doc/index.html
)
The following is the very important documentation which you should read along with this document:
debian-policy
- the Debian Policy
Manual
includes explanations of the structure and contents of the
Debian archive, several OS design issues, the Filesystem Hierarchy Standard
(which says where each file and directory should be) etc. For you, the most
important thing is that it describes requirements that each package must
satisfy to be included in the distribution (see
/usr/share/doc/debian-policy/policy.html/index.html
).
developers-reference
- the Debian Developer's
Reference
describes all matters not specifically about the technical
details of packaging, like the structure of the archive, how to rename, orphan,
pick up packages, how to do NMUs, how to manage bugs, best packaging practices,
when and where to upload etc. (see
/usr/share/doc/developers-reference/
).
Autotools
Tutorial
provides very good tutorial for the GNU Build System known
as the GNU Autotools
whose most important components are Autoconf,
Automake, Libtool, and gettext.
gnu-standards
- this package contains two pieces of documentation
from the GNU project: GNU Coding
Standards
, and Information for
Maintainers of GNU Software
. Although Debian does not require these
to be followed, these are still helpful as guidelines and common sense. (see
/usr/share/doc/gnu-standards/standards.html
and
/usr/share/doc/gnu-standards/maintain.html
).
If this document contradicts with what the Debian Policy Manual and Debian
Developer's Reference describes, they are correct. Please file a bug report on
the maint-guide
package.
The short descriptions that are given above only serve to introduce you to what each package does. Before continuing please thoroughly read the documentation of each program, at least, for the standard usage. It may seem like heavy going now, but later on you'll be very glad you read it.
There are two types of packages.
source package: A source package is a set of files which
contain code and data which you can compile and process into execution programs
and formatted documents. It usually comes as a combination of
*.orig.tar.gz
, *.debian.tar.gz
(or
*.diff.gz
), and *.dsc
. Some other archive and
compression methods may be used, too.
binary package: A binary package contains execution programs
and formatted documents. It usually comes as *.deb
for the normal
Debian system and as *.udeb
for the Debian Installer.
Don't mix terms like source of the program and the source package of the program!
There are several role names used around Debian.
upstream author: The person who made the original program.
upstream maintainer: The person who currently maintains the program.
maintainer: The person who makes Debian package of the program.
sponsor: The person who helps maintainers to upload packages to the official Debian Package Archive after checking their contents.
mentor: The person who helps novice maintainers on packaging etc.
Debian Developer (DD): The person who is a member of Debian. He has full upload right to the official Debian Package Archive.
Debian Maintainer (DM): The person who has limited upload right to the official Debian Package Archive.
There are several version names used around Debian.
upstream source version: The upstream source version is referred as version.
Debian revision: The revision by Debian on package is referred as revision.
Debian package version: The Debian package version is referred as the following.
version for the native Debian binary package and for the Debian source package.
version-revision for the non-native Debian binary package.
Please read the other manuals if you need more details on terminology.
You can not become an official Debian Developer (DD) over
night because it takes more than technical skill. Please do not be discouraged
by this. If it is useful to others, you can still upload your package either
as a maintainer through a sponsor or as a
Debian Maintainer. See Debian New
Maintainers
for more.
Please note that you do not need to create any new package to become an official Debian Developer. Contributing to the existing packages can provide a path to become an official Debian Developer too. There are many packages waiting for good maintainers (see Choose your program, Section 2.1).
Before you decide to ask your question in some public place, please just RTFM.
That includes documentation in /usr/share/doc/dpkg
,
/usr/share/doc/debian
,
/usr/share/doc/autotools-dev/README.Debian.gz
,
/usr/share/doc/package/*
files and the
man
/info
pages for all the programs mentioned in this
document. See all the information at http://nm.debian.org/
.
Making a small test package is good way to learn details of packaging. Inspecting existing well maintained packages is the best way to learn how other people make packages.
If you still have questions about packaging that you couldn't find answers to
in the available documentation and web resources, you can ask them on the
Debian Mentors' mailing list at debian-mentors@lists.debian.org
.
The more experienced Debian developers will gladly help you, but do read at
least some of the documentation before asking a question!
See http://lists.debian.org/debian-mentors/
for more information about this mailing list.
When you receive a bug report (yes, actual bug reports!), you will know that it
is time for you to dig into the Debian Bug Tracking System
and
read the documentation there, to be able to deal with the reports efficiently.
I highly recommend reading the Developer's
Reference, 5.8. 'Handling bugs'
.
If you still have questions, ask on the Debian Developers' mailing list at
debian-devel@lists.debian.org
.
See http://lists.debian.org/debian-devel/
for more information about this mailing list.
Even if it all worked well, it's time to start praying. Why? Because in just a few hours (or days) users from all around the world will start to use your package, and if you made some critical error you'll get mailbombed by numerous angry Debian users... Just kidding. :-)
Relax and be ready for bug reports, because there is a lot more work to be done before your package will be fully in line with Debian policies and its best practice guidelines (once again, read the real documentation for details). Good luck!
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ next ]
Debian New Maintainers' Guide
version 1.2.25, 2010-12-21 14:06:56 UTCjoy-mg@debian.org