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

Debian New Maintainers' Guide
Chapter 3 - Modifying the source

Normally, programs install themselves in the /usr/local subdirectories. But, Debian packages must not use that directory, since it is reserved for system administrator's (or user's) private use. This means that you have to take a look at your program's build system, usually starting with the Makefile. This is the script make(1) will use to automate building this program. For more details on Makefiles, look in `rules' file, Section 4.4.

Note that if your program uses GNU automake(1) and/or autoconf(1), meaning the source includes Makefile.am and/or Makefile.in files, respectively, you will need to modify those files. This is because each automake invocation will rewrite Makefile.in's with information generated from Makefile.am's, and each ./configure invocation will do the same with Makefile's, with data from Makefile.in's. Editing Makefile.am files requires some knowledge of automake, which you can read about in the automake info entry, whereas editing Makefile.in files is pretty much the same as editing Makefile files, just pay attention to the variables, i.e. any strings surrounded with `@'s, for example @[email protected] or @[email protected], which are replaced with actual stuff on each ./configure invocation. Please make sure to read /usr/share/doc/autotools-dev/README.Debian.gz before proceeding.

Also note that there isn't space here to go into all the details of fixing upstream sources, but here are a few problems people often run across.

3.1 Installation in a subdirectory

Most of the programs have some way of installing themselves in the existing directory structure of your system, so that their binaries get included in your $PATH, and that you find their documentation and manual pages in common places. However, if you do that, the program will be installed among everything else already on your system. This would make it hard for the packaging tools to figure out which files belong to your package and which don't.

Therefore you need to do something else: install the program into a temporary subdirectory from which the maintainer tools will build a working .deb package. Everything that is contained in this directory will be installed on a user's system when they install your package, the only difference is that dpkg will be installing the files in the root directory.

This temporary directory is usually created under your debian/ directory in the unpacked source tree. It is usually called debian/packagename.

Bear in mind that even though you need to make the program install in debian/packagename, it still needs to behave correctly when placed in the root directory, i.e. when installed from the .deb package. So you mustn't allow the build system to hardcode strings like /home/me/deb/gentoo-0.9.12/usr/share/gentoo into the package files.

With programs that use GNU autoconf, this will be quite easy. Most such programs have makefiles that are by default set up to allow installation into a random subdirectory while keeping in mind that /usr (for example) is the canonical prefix. When it detects your program uses autoconf, dh_make will set up commands for doing all this automatically, so you might as well skip reading this section. But with other programs, you will most probably have to examine and edit the Makefiles.

Here's the relevant part of gentoo's Makefile:

       # Where to put binary on 'make install'?
       BIN     = /usr/local/bin
       # Where to put icons on 'make install'?
       ICONS   = /usr/local/share/gentoo

We see that the files are set to install under /usr/local. Change those paths to:

       # Where to put binary on 'make install'?
       BIN     = $(DESTDIR)/usr/bin
       # Where to put icons on 'make install'?
       ICONS   = $(DESTDIR)/usr/share/gentoo

But why in that directory, and not some other? Because Debian packages never install files beneath /usr/local -- that tree is reserved for the system administrator's use. Such files on Debian systems go under /usr instead.

The more exact locations for binaries, icons, documentation etc are specified in the Filesystem Hierarchy Standard (see /usr/share/doc/debian-policy/fhs/). I recommend you browse it and read the sections that might concern your package.

So, we should install the binary in /usr/bin instead of /usr/local/bin, the manual page in /usr/share/man/man1 instead of /usr/local/man/man1 etc. Notice how there's no manual page mentioned in gentoo's makefile, but since the Debian Policy requires that every program has one, we'll make one later and install it in /usr/share/man/man1.

Some programs don't use makefile variables to define paths such as these. This means you might have to edit some real C sources in order to fix them to use the right locations. But where to search, and exactly what for? You can find this out by issuing:

       grep -nr -e 'usr/local/lib' --include='*.[c|h]' .

Grep will run recursively through the source tree and tell you the name of the file and the line in it, when it finds an occurrence.

Edit those files and in those lines replace /usr/local/* with usr/* -- and that's about it. Be careful that you don't mess up the rest of the code! :-)

After that you should find the install target (search for line that starts with `install:', that will usually work) and rename all references to directories other than ones defined at the top of the Makefile. Previously, gentoo's install target said:

       install:        gentoo
                       install ./gentoo $(BIN)
                       install icons/* $(ICONS)
                       install gentoorc-example $(HOME)/.gentoorc

After our change it says:

       install:        gentoo-target
                       install -d $(BIN) $(ICONS) $(DESTDIR)/etc
                       install ./gentoo $(BIN)
                       install -m644 icons/* $(ICONS)
                       install -m644 gentoorc-example $(DESTDIR)/etc/gentoorc

You've surely noticed that there's now a install -d command before the other commands in the rule. The original makefile didn't have it because usually the /usr/local/bin and other directories already exist on the system where one runs `make install`. However, since we will install into our own empty (or even nonexistent) directory, we will have to create each and every one of those directories.

We can also add in other things at the end of the rule, like the installation of additional documentation that the upstream authors sometimes omit:

                       install -d $(DESTDIR)/usr/share/doc/gentoo/html
                       cp -a docs/* $(DESTDIR)/usr/share/doc/gentoo/html

A careful reader will notice that I changed `gentoo' to `gentoo-target' in the `install:' line. That is called an unrelated bug fix :-)

Whenever you make changes that are not specifically related to Debian package, be sure to send them to the upstream maintainer so they can be included in the next program revision and be useful to everyone else. Also remember to make your fixes not specific to Debian or Linux (or even Unix!) prior to sending them -- make them portable. This will make your fixes much easier to apply.

Note that you don't have to send the debian/* files upstream.

3.2 Differing libraries

There is one other common problem: libraries are often different from platform to platform. For example, a Makefile can contain a reference to a library which doesn't exist on Debian systems. In that case, we need to change it to a library which does exist in Debian, and serves the same purpose.

So, if there is a line in your program's Makefile (or Makefile.in) that says something like this (and your program doesn't compile):

       LIBS = -lcurses -lsomething -lsomethingelse

Change it to this, and it will most probably work:

       LIBS = -lncurses -lsomething -lsomethingelse

(The author realizes that this is not the best example considering our libncurses package now ships with a libcurses.so symlink, but he couldn't think of a better one. Suggestions very welcome :-)

[ 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]