itchconfig Documentation
Information for Users of Software Packages


Software packages are intended to run on many different computers. Developers are confronted with lots of technical problems when they try to make their packages portable: some shared libraries don't provide functionality they should, some standard header files don't define everything they should or aren't available at all, some C compilers don't handle all supposedly-standard keywords correctly, some operating systems have weird bugs around which the package should try to work, and so on. All such problems have to be detected and solved on a user's specific computer somehow.

There are also other kinds of issues: users might want to enable different features of a package or install built programs and helper files like documentation in different directories.

It would be very difficult for all developers of all software packages to adapt their work manually to each new portability problem which becomes known and all possible user preferences. One solution is to write down an abstract representation of the relevant needs and properties of a package and let a configuration tool like itchconfig create a configuration shell script called configure from that representation; configure will then run on a user's computer and take care of all possible problems which might be relevant for the package. This way, the knowledge about problems and their work-arounds has to be kept in only one place (the configuration tool), and a package developer just has to run a new version of the configuration tool once when it becomes available in order to get a new, better version of configure.

So, developers need a configuration tool. One such tool is the well-known, wide-spread GNU autoconf/automake. Now there's another tool available - itchconfig; it is similar in that it also generates configure shell scripts, but it differs regarding several fundamental concepts and many details; if you're interested in a rather technical overview of those, have a look at Basic Concepts and Differences.

Command-Line Options

When you have unpacked a software package which contains a configure shell script, you normally have to run this script before you can do anything else (like building a program or installing something) with the package. First of all, you should find out whether the script has been auto-generated by either itchconfig or GNU autoconf or other tools (they mostly use different command-line options), for example with the command "./configure --version" or "head configure". We'll only discuss itchconfig's scripts here, of course. :-)

To get a list of all possible command-line options, use the command "./configure --help". The options are divided into the sections "General Options", "Installation Options", "Installation Paths" and "Package Options"; it depends on the respective software package which of these sections actually exist and which options they provide. The following general options are always available:

The installation options concern the prefix and suffix of executable programs which might be installed for the software package when you use the command "make install".

The installation paths specify in which directories several kinds of files (programs, documentation, ...) will be installed when you use the command "make install"; the paths must not contain trailing slahes, so use e.g. /my/path instead of /my/path/ everywhere. You only provide the "base" directories - the configure scripts know that certain kinds of files have to be installed in certain sub-directories of the base directories; for example, if the base directory for manuals is /usr/local/man and the manual file foo.1 shall be installed, it will automagically be copied to /usr/local/man/man1, not simply to /usr/local/man.

The package options specify which features of the software package will be enabled when you e.g. build a program with the command "make".

You can also change the values of environment variables with assignments like "./configure CC=fooc". This will override both the old environment value and assignments in scripts (stage init1).

Environment Variables

A configure script might recognize several environment variables, depending on the needs of a package. If you don't set a variable, a default value will be used.

Makefile Targets

Most software packages let configure create a Makefile. The Makefile then contains several targets; some of them are always available, others depend on the package.

If you just execute "make" without an explicit target, this will build all binaries if the package contains source code files from which binaries shall be built. (Otherwise you'll only get a "nothing to do" message.)

If a package developer defined rules for installing files on your computer, "make install" will install them in the directories which were set in a prior run of configure. If you want to change the default directories, have a look at the command-line options mentioned in the section "Installation Paths" in the output of "./configure --help".

After you've configured, built and installed everything a package provides, you might want to remove some intermediary files which were created during that process in order to get back some disk space. You can use the following commands, which basically follow the GNU standards as solidified in the GNU automake manual:

This documentation file is part of version 0.0.4 of itchconfig, a configuration tool created by Arne Thomaßen. itchconfig is basically released under certain versions of the GNU General Public License and WITHOUT ANY WARRANTY. Copyright (C) 2002 Arne Thomaßen.