Whole document tree

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 on the variables, i.e. any strings surrounded with `@'s, for example @CFLAGS@ or @LN_S@, which are replaced with actual stuff on each ./configure invocation.

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. You have to make sure that they do it correctly, but you have to make them install themselves in a temporary subdirectory that will be created under your debian/ directory, usually called debian/tmp, from which the maintainer tools will build a working .deb package. Everything that is contained in this directory will be installed on user's system when he installs your package, the only difference is that dpkg will be installing the files in the root directory.

Basically, you need to make the program install in debian/tmp, but behave correctly when placed in the root directory, i.e. when installed from the .deb package. With programs using GNU autoconf, this will be quite easy, because dh_make will set up commands for doing that 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'? Note: if you change this,
       # gentoo will not find the icons as it starts up. You're going to
       # have to alter gentoo's icon path (in the config window, "Paths"
       # tab) to get it work.
       ICONS   = /usr/local/lib/gentoo/

Before all that, you should insert a new two lines that say:

       # Edited for Debian GNU/Linux.
       DESTDIR =

because the build process requires it (will be explained later, in `rules' file, Section 4.4).

Then the Makefile mentions the location of the final binary. Just change that to this:

       # Where to put binary on 'make install'?
       BIN     = $(DESTDIR)/usr/X11R6/bin

But why in that directory, and not some other? Because Debian has defined some rules on where programs are to be installed. That is specified in the Filesystem Hierarchy Standard (see /usr/share/doc/debian-policy/fhs/). So, we should install the binary in /usr/X11R6/bin instead of /usr/local/bin, and the man page (it doesn't exist here, but almost every program has one, so we'll make one later) in /usr/share/man/man1 instead of /usr/local/man/man1.

After that we have a bit harder situation. If you change one line to:

       ICONS   = $(DESTDIR)/usr/share/gentoo/

which conforms to the policy, you will have to edit some real C sources. But where and what to search? You can find this out by issuing:

       grep -n usr/local/lib *.[ch]

(in every subdirectory that contains .c and .h files). Grep will tell you the name of the file and the line in it, when it finds an occurrence. Now edit those files and in those lines replace usr/local/lib with usr/share - and that is it. Just replace usr/local/lib with your location, and be very careful that you don't mess up the rest of the code, if you don't know much about programming in C. :-)

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

       # ----------------------------------------- Installation
     
       # You're going to have to be root to do this!
       install:        gentoo
                       install ./gentoo $(BIN)
                       install icons $(ICONS)
                       install gentoorc-example $(HOME)/.gentoorc

After our change it says:

       # ----------------------------------------- Installation
     
       # You're going to have to be root to do this!
       install:        gentoo-target
                       install -d $(BIN) $(ICONS) $(DESTDIR)/etc
                       install ./gentoo $(BIN)
                       install -m644 icons/* $(ICONS)
                       install -m644 gentoorc-example $(DESTDIR)/etc/gentoorc
                       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 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. Note that you don't have to send the debian/* files upstream, but you should do so with any other patches. And try to be nice to upstream, by making your fixes not specific to Debian or Linux (or even Unix!) prior to sending them.

3.2 Differing libraries

There is one other common problem: libraries are often different from platform to platform. For example, Makefile can contain a reference to a library which doesn't exist on Debian, or even Linux. In that case, we need to change it to a library which does exist in Debian, and serves the same purpose. The best way is to comment out those lines because there may be others who will try to compile on different platforms, so that they can have some hints about what could be the problem.

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
       #LIBS = -lcurses -lsomething -lsomethingelse