Introduction

You can set the environment variable ITCHCONFIG_SITE on your computer to the path of a configure.site shell script which performs site-specific configuration initializations. This shell script will be executed at several stages of a configure script run and in its execution environment, using the shell-builtin "." (period) command.

A configure.site script can be useful for several reasons, e.g. if configure scripts shall use non-standard values of environment variables or if you want to preset (possibly package-specific) non-default installation paths or enable/disable package features so that you don't have to re-type the --path-... and --enable-... command-line options for each run of a configure script.

In theory, configure.site could do everything any shell script can do. In practice, it should only perform initializations with assignments like "CC=fooc". It may also analyze the command-line options of the configure script; the configure script will ignore all command-line options which begin with "--site", so you can use them freely to activate special behavior of your configure.site script. There's a sample configure.site script available which contains several examples from "very simple" to "quite advanced".

Finding configure.site

The path of the configure.site script is defined by the environment variable ITCHCONFIG_SITE. For uniformity reasons, it should be something like /usr/local/share/itchconfig/configure.site or /usr/share/itchconfig/configure.site; but you are free to choose any path you want, even something like /foo/crazy/cfgsite or ~/mycfg. - The script name should not be "config.site" because that is used by configure scripts which are generated by GNU autoconf; using that name also with itchconfig could cause confusion.

The path can be still more flexible: if it contains the special variable "%P%", the configure script will first replace this with "-packagename" and check whether a file with the resulting name exists; only if that file doesn't exist, the configure script will replace the variable with an empty string and try again. For example, if the path is "/usr/configure%P%.site", a configure script for the package "helloworld" would try "/usr/configure-helloworld.site" and "/usr/configure.site". You could also put the configure.site scripts into different directories if the "%P%" is somewhere in front of the file name, e.g. "/usr/local/configuration%P%/configure.site". - This feature allows you to write several small, package-specific configure.site scripts instead of (or in addition to) a single, possibly big one.

Stages

configure.site can be called at several stages during the execution of the configure script. This makes a flexible, context-dependent initialization possible. You can check the shell script variable ic_site_stage to find out the current stage, and you can set ic_site_next to define the next stage at which configure.site shall be called again. If ic_site_next is set to an empty string, configure.site won't be called again during this run of the configure script. ic_site_next will always be set to an empty string before configure.site is executed, so you only have to change it if configure.site shall be called again. The following stages are defined:

• init1: after the inevitable shell compatibility stuff at the beginning of configure; here you can set or change environment variables
• init2: before the command-line parsing; here the default installation options, installation paths and package options can be changed
• init3: before the property tests begin; this will be the place to preset cache values as soon as the caching mechanism has been implemented
• exit1: before the script exits successfully; this can e.g. be used to store certain test results in a special cache file as soon as the caching mechanism has been implemented

configure.site will always be executed for the stage init1, where you could set ic_site_next as appropriate for your needs. If you want to use configure.site only to override some environment variables, you need not care about the whole stage mechanism at all - just put the assignments into configure.site and that's it.

Identifiers

A configure script defines several identifiers to allow configure.site detailed control of the configuration initialization. configure.site may use the following identifiers; those marked as "read-only" must not be changed by configure.site.

• ic_version (read-only): the version of itchconfig which was used to generate the configure script
• ic_package_name (read-only): the name of the package which is to be configured
• ic_package_version (read-only): the version number of the package
• ic_site_file (read-only): the actual path of the configure.site file
• ic_site_stage (read-only): the current stage of a configure script run
• ic_site_next: the next stage at which configure.site wants to be executed again
• ic_program_prefix, ic_program_suffix: the program prefix and suffix for installation (corresponds to the command-line options "--program-prefix=..." and "--program-suffix=...")
• ic_path_...: installation paths (corresponds to the command-line options "--path-...")
• ic_option_...: package options (corresponds to the command-line options "--enable-...", "--disable-..." and "--set-...")

Please note that changes of default values (e.g. for ic_path_...) won't show up in the output of "./configure --help" because that could cause unexpected line-breaks in the output depending on the actual length of a value. (So there would be a cosmetic issue; the problem could be solved easily with a shell command like "expr substr ...", but unfortunately that wouldn't be portable... Portable solutions would be much more complex and just not worth the trouble.)