Whole document tree

Debian New Maintainers' Guide
Chapter 2 First steps

While the documentation at the Developers corner is not so clear about where and how new maintainers should start their work, 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.

2.1 Choose your program.

You have probably chosen the package you want to build, but here are some pointers for you as the uninitiated:

• check if the package is in the distribution already. If you use the `stable' distribution, maybe it's best that you go to the package search page. If you use current `unstable' distribution, check it out with these commands:

         dpkg -s program
         dpkg -l '*program*'
  

• consult the WNPP page and debian-devel mailing list archives to see if anyone else is building that same package. If so, contact the current maintainer if you feel you need to. If not - find another interesting program that nobody maintains.
• program must have a license, if possible free as according to the Debian Free Software Guidelines. If it doesn't conform to some of these rules, it still can be included in `contrib' or `non-free' sections of Debian. If you are unsure about where should it go, ask on debian-legal@lists.debian.org.
• program certainly should not run setuid root, or even better - it shouldn't need to be setuid or setgid to anything.
• program should not be a daemon, or something that goes in */sbin directories.
• program should result in binary executable form, don't try libraries yet.
• it should be well documented, or at least understandable (to anyone).
• you should contact program's author(s) to check if they agree with packaging it. It is important to be able to consult with author(s) about the program in case of any program specific problems, so don't try to package unmaintained pieces of software.
• and last but not the least, you must know that it works, and have it tried for some time.

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 most experienced developers consult debian-devel 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 Linux 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 debian-mentors if you're not sure how to unpack it correctly (hint: issue `file archive.extension`).

As an example, I'll use program called `gentoo', an X11 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 exist 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 type `make uninstall` to remove all the installed files, and `make clean` (or better `make distclean`) to clean up the build directory.

2.3 Stuff prior to `dh_make'

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 Running `dh_make'

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

       dh_make -e your.maintainer@address -f ../gentoo-0.9.12.tar.gz

Of course, replace the string "your.maintainer@address" 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 with pressing <enter>. As a new maintainer you are discouraged from creating packages with multiple binary packages, or libraries, as explained earlier. It's not that hard, really, 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, Section 6.4