Overview

The use of itchconfig for a software package involves the following basic steps:

• The package developer does this:
  • execute itchscan to generate configure.scan (optional)
  • rename configure.scan to configure.base and edit it as necessary (optional)
  • execute itchconfig to generate the configure script from configure.base
• The user does this:
  • execute the configure script to create the Makefile and config.h
  • execute make to build the desired executable program(s)
  • "make install" to install the built program(s) and any additional files properly (optional)

itchconfig tries to distinguish and separate the following items neatly:

• the needs and properties of a package - in configure.base files
• the knowledge about possible portability issues - in the script generator
• user preferences - in command-line options for configure scripts and in configure.site scripts

In short: configure.base declares what shall be done, the resulting configure script determines how it is done.

Details

When a package developer executes itchscan, this checks all files in the current directory and all sub-directories for the following:

• C keywords, types, header file includes, library functions etc. which aren't available on all computers resp. are known not to work correctly with all compilers and operating systems
• source code files which might be necessary to build the executable program
• files which should be considered for "make install", for example manual pages, .info files and language-dependent .mo text files

From the results of these checks, itchscan generates the file configure.scan, which can be used as a starting point for a configure.base file. Please note that itchconfig can't yet process all commands which are generated by itchscan; so, before you put a command from configure.scan into configure.base, you should check (e.g. with the macro index) that the command has already been implemented.

When a package developer executes itchconfig, the following happens:

• itchconfig translates configure.base to a temporary, intermediary Perl script, "configure.pl", which it executes.
• configure.pl creates the final shell script, "configure", which must be included into the release package.

When a user executes configure, the following happens:

• configure parses its command-line arguments and possibly executes a configure.site script; this information is used to find out which package features the user wants to enable and where the generated binaries and other package parts should be installed.
• configure performs all tests on the user's machine which have been indicated by the original configure.base.
• configure creates a shell script, configure.act, based on the results of the previous items, and executes that.
• configure.act generates a Makefile and a configuration file config.h; it also substitutes all variables of the form "@id@" with their actual values in all relevant .in files as necessary, creating new files without the .in suffix.
• After this, the user can execute "make", "make install" etc. to build an executable program from the package source files, install it etc.

The file configure.base is some kind of central knowledge database for a software package. It contains information about all relevant specific needs and properties of the package - in a single place and encoded in m4 macro calls. (See the Macro Introduction.) itchconfig reads this database and creates a configure script file from it. itchconfig makes a special effort to minimize the size of that script, so that the overall package size isn't increased more than necessary and package users don't waste time when running the script. To achieve the design goals, the following ideas are realized:

• All relevant properties of the package must be known to itchconfig, otherwise it could "mis-optimize" something, producing buggy scripts. One consequence of this is that all relevant information must be encoded in m4 macro calls, not in shell script code (because itchconfig can't analyze the latter). itchconfig allows the addition of raw shell script code to the configure script file for maximum flexibility (see IC_EMIT_SH), but this capability shouldn't be used too much...
• An intermediary script (configure.pl) is necessary. It checks which features are actually required for the package and leaves out anything unnecessary. For example, if a package only needs a Makefile and no config.h, no code for producing/handling a config.h file has to be added to the final configure script, so it's simply omitted for this package.