Gory details described

Here we describe the backend support.

• Makefile Extensions: Extensions to the GNU coding standards
• configure.in: The format of the configure.in file
• config.status: config.status
• Makefile Fragments: Makefile Fragments

Extensions to the GNU coding standards

The following additions to the GNU coding standards are required for Cygnus configure to work properly.

• The Makefile must contain exactly one line starting with ####. This line should follow any default macro definitions but precede any rules. Host, target, and site specific Makefile fragments will be inserted immediately after this line. If the line is missing, the fragments will not be inserted.

Cygnus adds the following targets to our Makefiles. Their existence is not required for Cygnus configure, but they are documented here for completeness.

info

Build all info files from texinfo source.

install-info

Install all info files.

clean-info

Remove all info files and any intermediate files that can be generated from texinfo source.

stage1

stage2

stage3

stage4

de-stage1

de-stage2

de-stage3

de-stage4

bootstrap

comparison

Makefile

These targets are in transition and may be removed shortly.

In addition, the following Makefile targets have revised semantics:

install

Should not depend on the target all. If the program is not already built, make install should fail. This allows you to install programs even when make would otherwise determine them to be out of date. This can happen when the result of a make all is transported via tape to another machine for installation as well as in a number of other cases.

clean

Should remove any file that can be regenerated by the Makefile, excepting only the Makefile itself, and any links created by configure. That is, make all clean should return all directories to their original condition. If this is not done, then:

configure host1 ; make all clean ; configure host2 ; make all

will fail because of intermediate files intended for host1.

Cygnus adds the following macros to all `Makefile.in' files, but you are not required to use them to run Cygnus configure.

docdir

The directory in which to install any documentation that is not either a man page or an info file. For man pages, see mandir, for info, see infodir.

includedir

The directory in which to install any headers files that should be made available to users. This is distinct from the gcc include directory which is intended for gcc only. Files in includedir may be used by cc as well.

In addition, the following macros have revised semantics. Most of them describe installation directories; see also section Full descriptions of all installation subdirectories.

manext

is not used. The intended usage is not clear. For example, if you have a `foo.man' and a `bar.man', and `foo.man' is destined for `/usr/local/lib/man/man1/foo.1' while `bar.man' is destined for `/usr/local/lib/man/man5/bar.5', then what is the desired value of manext?

datadir

is used for host independent data files.

mandir

The default path for mandir depends on prefix.

infodir

The default path for infodir depends on prefix.

BISON

is assumed to have a yacc calling convention. To use bison, use BISON=bison -y.

Cygnus Makefiles also conform to one additional restriction:

• When libraries are installed, the line containing the call to INSTALL_DATA should always be followed by a line containing a call to RANLIB on the installed library. This is to accomodate systems that use ranlib. Systems that do not use ranlib can set RANLIB to echo in a host specific Makefile fragment.

The format of the `configure.in' file

A `configure.in' file for Cygnus configure consists of a per-invocation section, followed by a per-host section, followed by a per-target section, optionally followed by a post-target section. Each section is a shell script fragment, which is sourced by the configure shell script at an appropriate time. Values are passed among configure and the shell fragments through a set of shell variables. When each section is being interpreted (sourced) by the shell, the shell's current directory is the build directory, and any files created by the section (or referred to by the section) will be relative to the build directory. To reference files in other places (such as the source directory), prepend a shell variable such as srcdir to the desired file name.

The beginning of the `configure.in' file begins the per-invocation section.

A line beginning with # Per-host: begins the per-host section.

A line beginning with # Per-target: begins the per-target section.

If it exists, the post-target section begins with # Per-target:.

• Minimal: A minimal configure.in
• Configure Variables: Variables available to configure.in
• Declarations: For each invocation
• Per-host: For each host
• Per-target: For each target
• Post-target: After each target
• Example: An example configure.in

A minimal `configure.in'

A minimal `configure.in' consists of four lines.

srctrigger=foo.c
srcname="source for the foo program"
# Per-host:
# Per-target:

The `Per-host' and `Per-target' lines divide the file into the three required sections. The `srctrigger' line names a file. configure checks to see that this file exists in the source directory before configuring. If the `srctrigger' file does not exist, configure uses the value of `srcname' to print an error message about not finding the source.

This particular example uses no links, and only the default host, target, and site specific Makefile fragments if they exist.

Variables available to configure.in

The following variables pass information between the standard parts of configure and the shell-script fragments in `configure.in':

Variable: @defvar{srctrigger}

Contains the name of a source file that is expected to live in the source directory. You must usually set this in the per-invocation section of `configure.in'. Configure tests to see that this file exists. If the file does not exist, configure prints an error message. This is used as a sanity check that configure.in matches the source directory.

Variable: @defvar{srcname}

Contains the name of the source collection contained in the source directory. You must usually set this in the per-invocation section of `configure.in'. If the file named in srctrigger does not exist, configure uses the value of this variable when it prints the error message.

Variable: @defvar{configdirs}

Contains the names of any subdirectories where configure should recur. You must usually set this in the per-invocation section of `configure.in'. If `Makefile.in' contains a line starting with SUBDIRS =, then it will be replaced with an assignment to SUBDIRS using the value of configdirs (if subdirs is empty). This can be used to determine which directories to configure and build depending on the host and target configurations. Use configdirs (instead of the subdirs variable described below) if you want to be able to partition the sub-directories, or use independent Makefile fragments. Each sub-directory can be independent, and independently re-configured.

Variable: @defvar{subdirs}

Contains the names of any subdirectories where configure should create a Makefile (in addition to the current directory), without recursively running configure. Use subdirs (instead of the configdirs variable described above) if you want to configure all of the directories as a unit. Since there is a single invocation of configure that configures many directories, all the directories can use the same Makefile fragments, and the same configure.in.

Variable: @defvar{host}

Contains the full configuration name (generated by the script `config.sub' from the name that the user entered) for the host. This is a three-part name of the form

cpu-vendor-os

There are separate variables host_cpu, host_vendor, and host_os that you can use to test each of the three parts; this variable is useful, however, for error messages, and for testing combinations of the three components.

Variable: @defvar{host_cpu}

Contains the first element of the canonical triple representing the host as returned by `config.sub'. This is occasionally used to distinguish between minor variations of a particular vendor's operating system and sometimes to determine variations in binary format between the host and the target.

Variable: @defvar{host_vendor}

Contains the second element of the canonical triple representing the host as returned by `config.sub'. This is usually used to distinguish betwen the numerous variations between common operating systems.

Variable: @defvar{host_os}

Contains the the third element of the canonical triple representing the host as returned by `config.sub'.

Variable: @defvar{target}

Contains the full configuration name (generated by the script `config.sub' from the name that the user entered) for the target. This is a three-part name of the form

cpu-vendor-os

There are separate variables target_cpu, target_vendor, and target_os that you can use to test each of the three parts; this variable is useful, however, for error messages, and for testing combinations of the three components.

Variable: @defvar{target_cpu}

Contains the first element of the canonical triple representing the target as returned by `config.sub'. This is used heavily by programs involved in building programs, like the compiler, assembler, linker, etc. Most programs will not need the target variables at all, but this one could conceivably be used to build a program, for instance, that operated on binary data files whose byte order or alignment differ from the system where the program is running.

Variable: @defvar{target_vendor}

Contains the second element of the canonical triple representing the target as returned by `config.sub'. This is usually used to distinguish betwen the numerous variations between common operating systems or object file formats. Sometimes it is used to switch between different flavors of user interfaces.

Variable: @defvar{target_os}

Contains the the third element of the canonical triple representing the target as returned by `config.sub'. This variable is used by development tools to distinguish between subtle variations in object file formats that some vendors use across operating system releases. It might also be use to decide which libraries to build or what user interface the tool should provide.

Variable: @defvar{floating_point}

Is set to no if the user invoked configure with the -nfp command line option, otherwise it is empty. This is a request to target machines with no floating point unit, even if the targets ordinarily have floating point units available. This option has no negation.

Variable: @defvar{gas}

Is set to true if the user invoked configure with the -gas command line option, otherwise it is empty. This is a request to assume that all target machines have GAS available even if they ordinarily do not. The converse option `-no-gas' is not available.

Variable: @defvar{x}

Is set to true if the user invoked configure with the -x command line option, otherwise it is empty. This is a request to assume that MIT X11 compatible headers files and libraries are available on all hosts, regardless of what is normally available on them.

Variable: @defvar{srcdir}

Is set to the name of the directory containing the source for this program. This will be different from `.' if the user has specified the -srcdir= option. Note that srcdir is not necessarily an absolute path.

Variable: @defvar{host_makefile_frag}

If set by `configure.in', this variable should be the name a file, relative to srcdir to be included in the resulting Makefile. If the named file does not exist, configure will print a warning message. This variable is not set by configure.

Variable: @defvar{target_makefile_frag}

If set by `configure.in', this variable should be the name of a file, relative to srcdir, to be included in the resulting Makefile. If the named file does not exist, configure will print a warning message. This variable is not set by configure.

Variable: @defvar{site_makefile_frag}

Is set to a file name representing to the default Makefile fragment for this host. It may be set in `configure.in' to override this default. Normally site_makefile_frag is empty, but will have a value if the user specified -site= on the command line. It is probably not a good idea to override this variable from `configure.in', since that may defeat the configure user's intentions.

Variable: @defvar{Makefile}

Is set to the name of the generated `Makefile'. Normally this value is precisely `Makefile' but some programs may want something else.

Variable: @defvar{removing}

Is normally empty but will be set to some non-empty value if the user specified -rm on the command line. That is, if removing is non-empty, then configure is removing a configuration rather than creating one.

Variable: @defvar{files}

If this variable is non-empty following the per-target: section, then each word in its value will be the target of a symbolic link named in the corresponding word from the links variable.

Variable: @defvar{links}

If the files variable is non-empty following the per-target: section, then configure creates symbolic links with the first word of links pointing to the first word of files, the second word of links pointing to the second word of files, and so on.

For each invocation

configure sources the entire shell script fragment from the start of `configure.in' up to a line beginning with `# Per-host:' immediately after parsing command line arguments. The variables srctrigger and srcname must be set here.

You might also want to set the variable configdirs here.

For each host

The per-host section of `configure.in' starts with the line that begins with `# Per-host:' and ends before a line beginning with `# Per-target:'. configure sources the per-host section once for each host.

This section usually contains a big case statement using the variables `host_cpu', `host_vendor', and `host_os' to determine appropriate values for `host_makefile_frag' and `files', although `files' is not usually set here. Usually, it is set at the end of the per-target section after determining the names of the target specific configuration files.

For each target

The per-target section of `configure.in' starts with the line that begins with `# Per-target:' and ends before the line that begins with `# Post-target:', if there is such a line. Otherwise the per-target section extends to the end of the file. configure sources the per-target section once for each target before building any files, directories, or links.

This section usually contains a big case statement using the variables called `target_cpu', `target_vendor', and `target_os' to determine appropriate values for `target_makefile_frag' and `files'. The last lines in the per-target section normally set the variables files and links.

After each target

The post-target section is optional. If it exists, the post-target section starts with a line beginning with # Post-target: and extends to the end of the file. If it exists, configure sources this section once for each target after building all files, directories, or links.

This section is seldom needed, but you can use it to edit the Makefile generated by configure.

An example `configure.in'

Here is a small example of a `configure.in' file.

# This file is a collection of shell script fragments used to tailor
# a template configure script as appropriate for this directory.  
# For more information, see configure.texi.

configdirs=
srctrigger=warshall.c
srcname="bison"

# per-host:
case "${host_os}" in
m88kbcs)
	host_makefile_frag=config/mh-delta88
	;;
esac

# per-target:

files="bison_in.hairy"
links="bison.hairy"

# post-target:

config.status

The final step in configuring a directory is to create an executable shell script, `config.status'. The main purpose of this file is to allow the Makefile for the current directory to rebuild itself, if necessary. For this reason, `config.status' uses the `-norecursion' option to configure, and is therefore probably inappropriate for reconfiguring a tree of source code.

Makefile Fragments

Cygnus configure uses three types of Makefile fragments. In a generated Makefile they appear in the order target fragment, host fragment, and site fragment. This allows host fragments to override target fragments, and site fragments to override both.

Host specific Makefile fragments conventionally reside in the `./config' directory with names of the form `mh-host'. They are used for hosts that require odd options to the standard compiler and for compile time options based on the host configuration.

Target specific Makefile fragments conventionally reside in the `./config' directory with names of the form `mt-target'. They are used for target dependent compile time options.

Site specific Makefile fragments conventionally reside in the `./config' directory with names of the form `ms-site'. They are used to override host and target independent compile time options. Note that you can also override these options on the make invocation line.