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


Debian New Maintainers' Guide
Chapter 2 - First steps


Let's try to make your own package (or, better even, adopt an existing one).


2.1 Choose your program

You have probably chosen the package you want to create. The first thing you need to do is check if the package is in the distribution archive already by using aptitude.

You can also check package information through package search page and Debian Package Tracking System.

If the package already exists, well, install it! :-) If it happens to be orphaned -- if its maintainer is set to Debian QA Group, you may be able to pick it up if it's still available (check the ownership status at Debian Bug report logs: Bugs in package wnpp in unstable). You may also adopt a package for which the corresponding maintainer has filed a "Request for Adoption" (RFA).

Several different views of orphaned or RFA'ed packages are available at:

As a side note, it's important to point out that Debian already has packages for most kinds of programs, and the number of packages already in the Debian archive is much larger than that of contributors with upload rights. Thus, contributions to packages already in the archive are far more appreciated (and more likely to receive sponsorship) by other developers [3]. You can do that in various ways.

If you are able to adopt the package, get the sources (with something like "apt-get source packagename") and examine them. This document unfortunately doesn't include comprehensive information about adopting packages. Thankfully you shouldn't have a hard time figuring out how the package works since someone has already done the initial set up for you. Keep reading, though, a lot of the advice below will still be applicable for your case.

If the package is new, and you decide you'd like to see it in Debian, proceed as follows:

Of course, these things are just safety measures, and intended to save you from raging users if you do something wrong in some setuid daemon... When you gain some more experience in packaging, you'll be able to do such packages, but even the experienced developers consult the debian-mentors@lists.debian.org mailing list when they are in doubt. And people there will gladly help.

For more help about these, check in Debian Developer's Reference.


2.2 Get the program, and try it out

So the first thing to do is to find and download the original source code. I presume that you already have the source file that you picked up at the author's homepage. Sources for free Unix programs usually come in tar+gzip format with extension .tar.gz, or tar+bzip2 format with extension .tar.bz2. These usually contain the subdirectory called programname-version in them and all the sources under it.

If the latest version of such sources are available through VCS such as Git, Subversion, or CVS repository, you need to get it with "git clone", "cvs co", or "svn co" and repack it into tar+gzip format by yourself using the "--exclude-vcs" option.

If your program's source comes as some other sort of archive (for instance, the filename ends in .Z or .zip[4]), unpack it with appropriate tools and repack it, too.

As an example, I'll use a program called gentoo, an X GTK+ file manager.[5]

Create a subdirectory under your home directory named debian or deb or anything you find appropriate (e.g. just ~/gentoo would do fine in this case). Place the downloaded archive in it, and extract it (with "tar xzf gentoo-0.9.12.tar.gz"). Make sure there are no errors, even some irrelevant ones, because there will most probably be problems unpacking on other people's systems, whose unpacking tools may or may not ignore those anomalies. On your console screen, you should see the following.

     $ mkdir ~/gentoo ; cd ~/gentoo
     $ wget http://www.example.org/gentoo-0.9.12.tar.gz
     $ tar xvzf gentoo-0.9.12.tar.gz
     $ ls -F
     gentoo-0.9.12/
     gentoo-0.9.12.tar.gz

Now you have another subdirectory, called gentoo-0.9.12. Change to that directory and thoroughly read the provided documentation. Usually there are files named README*, INSTALL*, *.lsm or *.html. You must find instructions on how to correctly compile and install the program (most probably they'll assume you want to install to /usr/local/bin directory; you won't be doing that, but more on that later in Installation of files to the destination, Section 3.3).

Simple programs come with a Makefile file in them and can be compiled simply with "make". Some of them support "make check", which runs included self-checks. Installation to the destination directories is usually done with "make install".

Now try to compile and run your program, to make sure it works properly and doesn't break something else while it's installing or running.

Also, you can usually run "make clean" (or better "make distclean") to clean up the build directory. Sometimes there's even a "make uninstall" which can be used to remove all the installed files.


2.3 Free portable programs

A lot of Free programs are written in the C and C++ languages. Many of these use Autotools or CMake to make them portable across different platforms. These tools are used to generate Makefile and other required source files. Then, such programs are built with usual "make; make install".

Autotools are the GNU build system comprising Autoconf, Automake, Libtool, and gettext. You can notice such sources by the configure.ac, Makefile.am, and Makefile.in files. [6]

The first step of Autotools work flow is usually that the upstream runs "autoreconf -i -f" in the source and distributes this source with generated files.

     configure.ac-----+-> autoreconf -+-> configure
     Makefile.am -----+        |      +-> Makefile.in
     src/Makefile.am -+        |      +-> src/Makefile.in
                               |      +-> config.h.in
                           automake
                           aclocal
                           aclocal.m4
                           autoheader

Editing configure.ac and Makefile.am files requires some knowledge of autoconf and automake. See "info autoconf" and "info automake".

The second step of Autotools work flow is usually that the user obtains this distributed source and runs "./configure && make" in the source to compile program into a binary.

     Makefile.in -----+                +-> Makefile -----+-> make -> binary
     src/Makefile.in -+-> ./configure -+-> src/Makefile -+
     config.h.in -----+                +-> config.h -----+
                               |
                config.status -+
                config.guess --+

You can change many things in the Makefile file such as the default file install location using the command option, e.g. "./configure --prefix=/usr".

Although it is not required, updating the configure and other files with "autoreconf -i -f" as the user may improve the compatibility of the source.

CMake is an alternative build system. You can notice such sources by the CMakeLists.txt file.


2.4 Package name and version

You should start packaging with a completely clean (pristine) source directory, or simply with freshly unpacked sources.

For the package to be built correctly, you must make the program's original name lowercase (if it isn't already), and you should move the source directory to packagename-version.

If the program name consists of more than one word, contract them to one word, or make an abbreviation. For example, program "John's little editor for X" package would be named johnledx, or jle4x, or whatever you decide, as long as it's under some reasonable limit, e.g. 20 characters.

Also check for the exact version of the program (to be included in the package version). If that piece of software is not numbered with versions like X.Y.Z, but with some kind of date, feel free to use that date as the version number, as long as newer version numbers will look larger. While it is best to use the same version number as what upstream uses, if it is in the format of 09Oct23 you may need to convert it to YYYYMMDD format, which would be 20091023, to ensure proper order for upgrade with the dpkg program.[7]

Some programs won't be numbered at all, in which case you should contact the upstream maintainer to see if they've got some other revision-tracking method.


2.5 Initial Debian package

Let's set up the shell environment variable $DEBEMAIL and $DEBFULLNAME so many Debian maintenance tools recognize your name and email address to use for packages as follows.[8].

     $ cat >>~/.bashrc <<EOF
     DEBEMAIL=your.email.address@example.org
     DEBFULLNAME="Firstname Lastname"
     export DEBEMAIL DEBFULLNAME
     EOF

Let's make an initial Debian package by issuing the dh_make command as follows.

     $ . ~/.bashrc
     $ cd ~/gentoo/gentoo-0.9.12
     $ dh_make -f ../gentoo-0.9.12.tar.gz

Of course, replace the filename with the name of your original source archive. [9] See dh_make(1) for details.

Some information will come up. It will ask you what sort of package you want to create. Gentoo is a single binary package - it creates only one binary, and thus one .deb file - so we will select the first option, with the "s" key, check the information on the screen and confirm by pressing "ENTER". [10]

After this execution of dh_make, a copy of the upstream tarball is created as gentoo_0.9.12.orig.tar.gz in the parent directory to accommodate the creation of the non-native Debian source package with the debian.tar.gz later.

     $ cd ~/gentoo ; ls -F
     gentoo-0.9.12/
     gentoo-0.9.12.tar.gz
     gentoo_0.9.12.orig.tar.gz

Please note 2 key features in this gentoo_0.9.12.orig.tar.gz file name:

You should also notice that many template files are created in the source under the debian directory. These will be explained in Required files under the debian directory, Chapter 4 and Other files under the debian directory, Chapter 5. You should also understand that the packaging is not automatic process. You need to modify the upstream source for Debian as Modifying the source, Chapter 3. After all these, you need to build Debian packages under the proper method as Building the package, Chapter 6, check them as Checking the package for errors, Chapter 7, and upload them as Uploading the package, Chapter 8. I will explain all these steps.

Once again, as a new maintainer you are discouraged from creating complicated packages, e.g.,

It's not too hard, but it does require a bit more knowledge, so we won't describe all of it here.

If you accidentally erased some template files while working on them, you can recover them by running dh_make with the --addmissing option again in a Debian package source tree.

Updating an existing package may get complicated since it may be using older techniques. Please stick with fresh packaging cases for now to learn basics. I will come back to explain it later in Updating the package, Chapter 9.


[ 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