ONLamp.com    
 Published on ONLamp.com (http://www.onlamp.com/)
 See this if you're having trouble printing code examples


Making Packager-Friendly Software

by Julio M. Merino Vidal
03/31/2005

A package maintainer, or packager, is a person who creates packages for software projects. He eventually finds common problems in these projects, resulting in a complex packaging process and a final package that is a nightmare to maintain. These little flaws exist because in most cases the original developers are not packagers, so they are not aware of them. In other words, if you do not know something is wrong, you cannot fix it.

This article describes some of these common problems and possible solutions. Consequently, it is of most value to software developers who make their creations publicly available. Keep in mind that any published project will eventually catch a packager's attention; the easier it is to create the package, the sooner someone can package it.

This document can also help package maintainers to show them some problems they may not be aware of. Remember that a task of a good packager is to send bug reports--with appropriate fixes, if possible--to the mainstream developers about any problems that are found. That way, future versions of the program will be easier to maintain. Note that by doing this, they will help not only themselves, but also all other packagers who handle the same piece of software in other operating systems or platforms.

In case you're wondering whether I know what I'm talking about, let me present myself. I have worked for The NetBSD Packages Collection (pkgsrc) since November 2002. During that time, I have done more than 1,600 package updates and created around 200 packages, most of which are related to GNOME; I am the main maintainer of its packages. While doing this, I have repeatedly encountered and fixed the problems described in this article, so I would like to solve them at their root (by the original software developers). I hope this gives you a bit of confidence.

Related Reading

Managing Projects with GNU Make
By Robert Mecklenburg

When presenting solutions for the problems described, I have focused on the most popular build infrastructure in the free software world: GNU Autoconf, GNU Automake, and GNU Libtool. However, the ideas outlined here apply to any build infrastructure you can think of.

I would like to thank Ben Collver, Thomas Klausner, and Todd Vierling, all of them pkgsrc developers, due to their suggestions; and in general all other developers of this system for continuously improving its quality.

Terminology

It's a good idea to be familiar with the following basic terms, which will be used in this article:

The Distribution File

The first problems in packaging come from the way that project maintainers create or handle the distfiles. These issues are uncommon, but once you start maintaining an affected package, you are likely to suffer its problems forever (unless you persuade the author to fix them). Here's how you can avert trouble:

Documentation Files

Several build tools force developers to include documentation files in their distfiles. For example, GNU Automake checks for the existence of README, NEWS, COPYING, and other files, although it does not check the contents. Unfortunately, many developers create those files to shut up errors but forget to fill them in. Although it's hard to believe, I have found several distfiles without any kind of information, many of which are GNOME core libraries.

Why are these files important? They provide very valuable information to the packager. At the very least, he needs:

Note that keeping all this information in a web page is not as useful as including it in the package. Web pages are by nature volatile, so they may become unavailable after some time, especially if the project is abandoned or moved from the original server.

Additionally, please be careful when writing these files. Lots of projects include incomplete notes and are full of typos and incorrect spacing, which denotes that the author does not care about them. These files are usually the first thing the occasional user of your program will examine; if they look sloppy, he will have a bad impression of your project, even if it is coded perfectly.

Configuration Techniques

Before you can build a program from its sources, you have to tune several details to adapt it to your system. Other times, you have to change some default settings so that it fits your expectations. This process is known as source configuration. Believe me when I say that all software packages have some configurable aspect at this stage and that somebody, somewhere, will need to change it; there are very, very, few exceptions. To understand why this is so important, consider the following scenarios:

Given these reasons, I hope you see the need for a configuration framework in almost all scenarios. Without it, your program is neither portable nor usable, because it will be very problematic to make it work on any system different from yours.

Assuming that this has convinced you, you now have to choose which configuration framework to use. The most common alternatives are:

From now on I will assume that your program includes a configuration script. If it does not, well, read the reasons again. Keep reading, even if you still resist the idea, as the concepts explained below should apply to whichever method you use.

Configuration Script Tips

As explained earlier, a configuration script adapts the source code of a program to build and work properly on the build host. (I will not consider cross-compilation here, but that is often a focus of problems, too.) What kinds of details must a developer care about to make his creations package-friendly?

Automatic Decisions

An automated decision is one taken based on the software available on the system at configuration time, without user intervention. They are very harmful, as they make maintenance harder and often lead to incorrect dependency tracking, which is a very serious problem in a package.

As an example, consider the following scenario: your program comes with an optional GTK front end, and your configuration script provides an --enable-gtk-fe={yes,no} flag to specify whether to build it. The default action, however, is to take an automatic decision based on the presence of GTK in the system; that is, if GTK is available, build and install the GTK front end. (To make this more credible, this is what xchat and other programs do.)

This behavior is acceptable, and often very good, if the user is installing your program by hand. Unfortunately, it makes things (very) difficult in the face of package maintainers, especially when the amount of optional features is large (gst-plugins is one such beast).

When a maintainer creates a package for a software program, he must choose a known set of default build options for it. He does this to create the same--or almost equal--binary packages no matter which machine they are built on. The goal behind this is to keep a fixed dependency tree that is easy to track properly. The common procedure to do this is as follows:

  1. Manually analyze the available configure-time options (as given by ./configure --help or as seen in the README file) and the output of the configuration script.

  2. Check which features are optional and decide whether to enable them for the actual package.

  3. Adapt the source package to use only the chosen dependencies, either by giving extra flags to the configuration script or by patching it manually. Doing the latter is often quite difficult (because configuration scripts are pregenerated and unreadable shell code).

As you can imagine, this task is prone to error: it is easy to miss a required dependency, especially if it is unclear (which unfortunately is the case 90 percent of the time). Think, for example, about the yacc and lex utilities: if the packager forgets to add a dependency on them, the end user will probably have trouble building the package. It's even worse if the package finds an extra library and uses it but does not record this fact anywhere. Any mistake here will surely cause trouble to end users, who may experience build failures, extra files being installed, and so on.

Another problem appears when it is time to update the package. The packager has to repeat the same procedure to verify that the package has introduced no new dependencies. If all of them were off (or on!) by default, this could mitigate the pain, but due to the automatic decisions explained above, this causes a lot of headache.

Consider gst-plugins, which I mentioned earlier. This can build a huge amount of plugins depending on the libraries and codecs available on the system. In pkgsrc, we explicitly disable them all through configuration arguments and select them one by one in individual packages (see its Makefile.common). New versions of gst-plugins often come with new modules, so the set of arguments to pass to the configuration script needs manual adjustment on every update.

Now imagine that the packager misses the --disable-arts argument. The aRts plugin (libgstartsdsink.so) will build on some systems but not others due to the automatic detection. If the packager does not have aRts in his system, he will not add a dependency on aRts because he will not notice it. When another user builds it on his aRts-enabled system, aRts will become a dependency; however, this fact will go unrecorded. aRts has become a hidden dependency of gst-plugins. A further removal of the former will mysteriously break the latter. This kind of situation is a very serious problem that comes up over and over again.

What are some possible solutions to this dilemma?

  1. Make the configuration script abort its process when it cannot activate a feature because of missing dependencies. For example, if the default behavior of xchat is to build the GTK front end, abort the configuration process if GTK is not available. (The word default is important here; if the default is to not enable the GTK front end, the script should not care at all about GTK presence.) I know; this solution is too drastic because it makes things difficult to people building by hand (though, if they are building by hand, they should take all the consequences ...).

  2. Add an --enable-packager-mode (or similar) flag. Passing this flag to the configuration script should disable all automatic decisions, as explained in the previous solution. However, if the flag is absent, the script should behave as usual, taking automatic decisions.

In my opinion, you should use the second solution, as it does not intrude and is more flexible. Is it too complex? Not really. The following code snippet adds the --enable-packager-mode in your own GNU Autoconf scripts:

AC_ARG_ENABLE([packager-mode],
              AS_HELP_STRING([--enable-packager-mode],
                             [Change configuration behavior
                              to ease packaging]),
              [if test x"${enableval}" = xyes
               then
                   automatic_detection=no
               else
                   automatic_detection=yes
               fi],
              [automatic_detection=yes])

Assuming that you choose this option, consider how this flag could affect the first example of this section (the one to enable or disable an optional GTK front end):

AC_ARG_ENABLE([gtk-fe],
              AS_HELP_STRING([--enable-gtk-fe=auto/yes/no],
                             [Enable the GTK frontend
                             (default=auto or yes)]),
              [enable_gtk_fe=${enableval}],
              [if test x"${automatic_detection}" = xyes
               then
                   enable_gtk_fe=auto
               else
                   enable_gtk_fe=yes
               fi])

build_gtk_fe=no
if test x"${enable_gtk_fe}" = xyes ||
   test x"${enable_gtk_fe}" = xauto
then
    PKG_CHECK_MODULES(GTK,
                      [gtk+-2.0 >= 2.6.0],
                      [build_gtk_fe=yes],
                      [if test x"${enable_gtk_fe}" = xyes
                       then
                           AC_MSG_ERROR([GTK not found, but
                                         the GTK frontend
                                         is explicitly
                                         enabled])
                       else
                           build_gtk_fe=no
                       fi])
fi
AM_CONDITIONAL(BUILD_GTK_FE,
               [test x"${build_gtk_fe}" = xyes])

What's Next

This article has introduced the problems of software packaging and why developers should be aware of them. It discussed multiple problematic issues that can be usually found in the distribution files and in documentation. Finally, it analyzed in detail the need for configuration scripts, techniques to implement them, and multiple problems that arise during their creation.

The next article will focus on the build infrastructure used by third-party packages, as well as some code portability issues. Until then, if you are the maintainer of a specific software project, you have enough time to apply all the tips explained. Time to work!

Julio M. Merino Vidal studies computer science at the FIB faculty in Barcelona, Spain.


Return to ONLamp.com.

Copyright © 2009 O'Reilly Media, Inc.