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

Debian New Maintainers' Guide
Chapter 2 - First steps

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. If you use the `stable' distribution, maybe it's best that you go to the package search page.

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.

Then you should consult the Debian web site at Work-Needing and Prospective Packages and its linked pages to check the latest adoption/orphan status of the package.

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 mailing list when they are in doubt. And people there will gladly help.

For more help about these, check in 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 package. 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, and usually contain the subdirectory called program-version and all the sources in it. If your program's source comes as some other sort of archive (for instance, the filename ends in ".Z" or ".zip"), unpack it with appropriate tools, or ask on the debian-mentors mailing list if you're not sure how to unpack it correctly (hint: issue `file archive.extension`).

As an example, I'll use a program called `gentoo', an X GTK+ file manager. Note that the program is already packaged, and has changed substantially from the version while this text was first written.

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 uncompress 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.

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 in a subdirectory, Section 3.1).

The process varies from program to program, but a lot of modern programs come with a `configure' script that configures the source under your system and makes sure that your system is in condition to compile it. After configuring with `./configure`, programs are usually compiled with `make`. Some of them support `make check`, to run included self-checks. Installation in 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 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, prepended with a "0.0." (just in case upstream people one day decide to release a nice version like 1.0). So, if the release or snapshot date was 19th of December, 1998, you can use the version string of 0.0.19981219.

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.4 Initial "debianization"

Make sure you're in the program source directory, and issue this:

       dh_make -e [email protected] -f ../gentoo-0.9.12.tar.gz

Of course, replace the string "[email protected]" with your e-mail address for inclusion in the changelog entry and other files, and the filename with the name of your original source archive. 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>.

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 diff.gz. Please note 2 key features in this file name:

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.

Please note that you should run dh_make only once, and that it won't behave correctly if you run it again in the same, already "debianized", directory. That also means that you will use a different method to release a new revision or a new version of your package in the future. Read more about that later in Updating the package, Chapter 9

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

Debian New Maintainers' Guide

version 1.2.11, 12 January 2007.

Josip Rodin [email protected]