diff options
Diffstat (limited to 'etc/configure.info-1')
| -rw-r--r-- | etc/configure.info-1 | 1313 |
1 files changed, 1313 insertions, 0 deletions
diff --git a/etc/configure.info-1 b/etc/configure.info-1 new file mode 100644 index 000000000..0be0764f9 --- /dev/null +++ b/etc/configure.info-1 @@ -0,0 +1,1313 @@ +This is configure.info, produced by makeinfo version 4.0f from +./configure.texi. + +INFO-DIR-SECTION GNU admin +START-INFO-DIR-ENTRY +* configure: (configure). The GNU configure and build system +END-INFO-DIR-ENTRY + + This file documents the GNU configure and build system. + + Copyright (C) 1998 Cygnus Solutions. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + +File: configure.info, Node: Top, Next: Introduction, Up: (dir) + +GNU configure and build system +****************************** + + The GNU configure and build system. + +* Menu: + +* Introduction:: Introduction. +* Getting Started:: Getting Started. +* Files:: Files. +* Configuration Names:: Configuration Names. +* Cross Compilation Tools:: Cross Compilation Tools. +* Canadian Cross:: Canadian Cross. +* Cygnus Configure:: Cygnus Configure. +* Multilibs:: Multilibs. +* FAQ:: Frequently Asked Questions. +* Index:: Index. + + +File: configure.info, Node: Introduction, Next: Getting Started, Prev: Top, Up: Top + +Introduction +************ + + This document describes the GNU configure and build systems. It +describes how autoconf, automake, libtool, and make fit together. It +also includes a discussion of the older Cygnus configure system. + + This document does not describe in detail how to use each of the +tools; see the respective manuals for that. Instead, it describes +which files the developer must write, which files are machine generated +and how they are generated, and where certain common problems should be +addressed. + + This document draws on several sources, including the autoconf +manual by David MacKenzie (*note autoconf overview: (autoconf)Top.), +the automake manual by David MacKenzie and Tom Tromey (*note automake +overview: (automake)Top.), the libtool manual by Gordon Matzigkeit +(*note libtool overview: (libtool)Top.), and the Cygnus configure +manual by K. Richard Pixley. + +* Menu: + +* Goals:: Goals. +* Tools:: The tools. +* History:: History. +* Building:: Building. + + +File: configure.info, Node: Goals, Next: Tools, Up: Introduction + +Goals +===== + + The GNU configure and build system has two main goals. + + The first is to simplify the development of portable programs. The +system permits the developer to concentrate on writing the program, +simplifying many details of portability across Unix and even Windows +systems, and permitting the developer to describe how to build the +program using simple rules rather than complex Makefiles. + + The second is to simplify the building of programs distributed as +source code. All programs are built using a simple, standardized, two +step process. The program builder need not install any special tools in +order to build the program. + + +File: configure.info, Node: Tools, Next: History, Prev: Goals, Up: Introduction + +Tools +===== + + The GNU configure and build system is comprised of several different +tools. Program developers must build and install all of these tools. + + People who just want to build programs from distributed sources +normally do not need any special tools beyond a Unix shell, a make +program, and a C compiler. + +autoconf + provides a general portability framework, based on testing the + features of the host system at build time. + +automake + a system for describing how to build a program, permitting the + developer to write a simplified `Makefile'. + +libtool + a standardized approach to building shared libraries. + +gettext + provides a framework for translation of text messages into other + languages; not really discussed in this document. + +m4 + autoconf requires the GNU version of m4; the standard Unix m4 does + not suffice. + +perl + automake requires perl. + + +File: configure.info, Node: History, Next: Building, Prev: Tools, Up: Introduction + +History +======= + + This is a very brief and probably inaccurate history. + + As the number of Unix variants increased during the 1980s, it became +harder to write programs which could run on all variants. While it was +often possible to use `#ifdef' to identify particular systems, +developers frequently did not have access to every system, and the +characteristics of some systems changed from version to version. + + By 1992, at least three different approaches had been developed: + * The Metaconfig program, by Larry Wall, Harlan Stenn, and Raphael + Manfredi. + + * The Cygnus configure script, by K. Richard Pixley, and the gcc + configure script, by Richard Stallman. These use essentially the + same approach, and the developers communicated regularly. + + * The autoconf program, by David MacKenzie. + + The Metaconfig program is still used for Perl and a few other +programs. It is part of the Dist package. I do not know if it is +being developed. + + In 1994, David MacKenzie and others modified autoconf to incorporate +all the features of Cygnus configure. Since then, there has been a +slow but steady conversion of GNU programs from Cygnus configure to +autoconf. gcc has been converted, eliminating the gcc configure script. + + GNU autoconf was regularly maintained until late 1996. As of this +writing in June, 1998, it has no public maintainer. + + Most programs are built using the make program, which requires the +developer to write Makefiles describing how to build the programs. +Since most programs are built in pretty much the same way, this led to a +lot of duplication. + + The X Window system is built using the imake tool, which uses a +database of rules to eliminate the duplication. However, building a +tool which was developed using imake requires that the builder have +imake installed, violating one of the goals of the GNU system. + + The new BSD make provides a standard library of Makefile fragments, +which permits developers to write very simple Makefiles. However, this +requires that the builder install the new BSD make program. + + In 1994, David MacKenzie wrote the first version of automake, which +permitted writing a simple build description which was converted into a +Makefile which could be used by the standard make program. In 1995, Tom +Tromey completely rewrote automake in Perl, and he continues to enhance +it. + + Various free packages built libraries, and by around 1995 several +included support to build shared libraries on various platforms. +However, there was no consistent approach. In early 1996, Gordon +Matzigkeit began working on libtool, which provided a standardized +approach to building shared libraries. This was integrated into +automake from the start. + + The development of automake and libtool was driven by the GNITS +project, a group of GNU maintainers who designed standardized tools to +help meet the GNU coding standards. + + +File: configure.info, Node: Building, Prev: History, Up: Introduction + +Building +======== + + Most readers of this document should already know how to build a +tool by running `configure' and `make'. This section may serve as a +quick introduction or reminder. + + Building a tool is normally as simple as running `configure' +followed by `make'. You should normally run `configure' from an empty +directory, using some path to refer to the `configure' script in the +source directory. The directory in which you run `configure' is called +the "object directory". + + In order to use a object directory which is different from the source +directory, you must be using the GNU version of `make', which has the +required `VPATH' support. Despite this restriction, using a different +object directory is highly recommended: + * It keeps the files generated during the build from cluttering up + your sources. + + * It permits you to remove the built files by simply removing the + entire build directory. + + * It permits you to build from the same sources with several sets of + configure options simultaneously. + + If you don't have GNU `make', you will have to run `configure' in +the source directory. All GNU packages should support this; in +particular, GNU packages should not assume the presence of GNU `make'. + + After running `configure', you can build the tools by running `make'. + + To install the tools, run `make install'. Installing the tools will +copy the programs and any required support files to the "installation +directory". The location of the installation directory is controlled +by `configure' options, as described below. + + In the Cygnus tree at present, the info files are built and +installed as a separate step. To build them, run `make info'. To +install them, run `make install-info'. + + All `configure' scripts support a wide variety of options. The most +interesting ones are `--with' and `--enable' options which are +generally specific to particular tools. You can usually use the +`--help' option to get a list of interesting options for a particular +configure script. + + The only generic options you are likely to use are the `--prefix' +and `--exec-prefix' options. These options are used to specify the +installation directory. + + The directory named by the `--prefix' option will hold machine +independent files such as info files. + + The directory named by the `--exec-prefix' option, which is normally +a subdirectory of the `--prefix' directory, will hold machine dependent +files such as executables. + + The default for `--prefix' is `/usr/local'. The default for +`--exec-prefix' is the value used for `--prefix'. + + The convention used in Cygnus releases is to use a `--prefix' option +of `/usr/cygnus/RELEASE', where RELEASE is the name of the release, and +to use a `--exec-prefix' option of `/usr/cygnus/RELEASE/H-HOST', where +HOST is the configuration name of the host system (*note Configuration +Names::). + + Do not use either the source or the object directory as the +installation directory. That will just lead to confusion. + + +File: configure.info, Node: Getting Started, Next: Files, Prev: Introduction, Up: Top + +Getting Started +*************** + + To start using the GNU configure and build system with your software +package, you must write three files, and you must run some tools to +manually generate additional files. + +* Menu: + +* Write configure.in:: Write configure.in. +* Write Makefile.am:: Write Makefile.am. +* Write acconfig.h:: Write acconfig.h. +* Generate files:: Generate files. +* Getting Started Example:: Example. + + +File: configure.info, Node: Write configure.in, Next: Write Makefile.am, Up: Getting Started + +Write configure.in +================== + + You must first write the file `configure.in'. This is an autoconf +input file, and the autoconf manual describes in detail what this file +should look like. + + You will write tests in your `configure.in' file to check for +conditions that may change from one system to another, such as the +presence of particular header files or functions. + + For example, not all systems support the `gettimeofday' function. +If you want to use the `gettimeofday' function when it is available, +and to use some other function when it is not, you would check for this +by putting `AC_CHECK_FUNCS(gettimeofday)' in `configure.in'. + + When the configure script is run at build time, this will arrange to +define the preprocessor macro `HAVE_GETTIMEOFDAY' to the value 1 if the +`gettimeofday' function is available, and to not define the macro at +all if the function is not available. Your code can then use `#ifdef' +to test whether it is safe to call `gettimeofday'. + + If you have an existing body of code, the `autoscan' program may +help identify potential portability problems, and hence configure tests +that you will want to use. *Note Invoking autoscan: (autoconf)Invoking +autoscan. + + Another handy tool for an existing body of code is `ifnames'. This +will show you all the preprocessor conditionals that the code already +uses. *Note Invoking ifnames: (autoconf)Invoking ifnames. + + Besides the portability tests which are specific to your particular +package, every `configure.in' file should contain the following macros. + +`AC_INIT' + This macro takes a single argument, which is the name of a file in + your package. For example, `AC_INIT(foo.c)'. + +`AC_PREREQ(VERSION)' + This macro is optional. It may be used to indicate the version of + `autoconf' that you are using. This will prevent users from + running an earlier version of `autoconf' and perhaps getting an + invalid `configure' script. For example, `AC_PREREQ(2.12)'. + +`AM_INIT_AUTOMAKE' + This macro takes two arguments: the name of the package, and a + version number. For example, `AM_INIT_AUTOMAKE(foo, 1.0)'. (This + macro is not needed if you are not using automake). + +`AM_CONFIG_HEADER' + This macro names the header file which will hold the preprocessor + macro definitions at run time. Normally this should be + `config.h'. Your sources would then use `#include "config.h"' to + include it. + + This macro may optionally name the input file for that header + file; by default, this is `config.h.in', but that file name works + poorly on DOS filesystems. Therefore, it is often better to name + it explicitly as `config.in'. + + This is what you should normally put in `configure.in': + AM_CONFIG_HEADER(config.h:config.in) + + (If you are not using automake, use `AC_CONFIG_HEADER' rather than + `AM_CONFIG_HEADER'). + +`AM_MAINTAINER_MODE' + This macro always appears in Cygnus configure scripts. Other + programs may or may not use it. + + If this macro is used, the `--enable-maintainer-mode' option is + required to enable automatic rebuilding of generated files used by + the configure system. This of course requires that developers be + aware of, and use, that option. + + If this macro is not used, then the generated files will always be + rebuilt automatically. This will cause problems if the wrong + versions of autoconf, automake, or others are in the builder's + `PATH'. + + (If you are not using automake, you do not need to use this macro). + +`AC_EXEEXT' + Either this macro or `AM_EXEEXT' always appears in Cygnus configure + files. Other programs may or may not use one of them. + + This macro looks for the executable suffix used on the host + system. On Unix systems, this is the empty string. On Windows + systems, this is `.exe'. This macro directs automake to use the + executable suffix as appropriate when creating programs. This + macro does not take any arguments. + + The `AC_EXEEXT' form is new, and is part of a Cygnus patch to + autoconf to support compiling with Visual C++. Older programs use + `AM_EXEEXT' instead. + + (Programs which do not use automake use neither `AC_EXEEXT' nor + `AM_EXEEXT'). + +`AC_PROG_CC' + If you are writing C code, you will normally want to use this + macro. It locates the C compiler to use. It does not take any + arguments. + + However, if this `configure.in' file is for a library which is to + be compiled by a cross compiler which may not fully work, then you + will not want to use `AC_PROG_CC'. Instead, you will want to use a + variant which does not call the macro `AC_PROG_CC_WORKS'. Examples + can be found in various `configure.in' files for libraries that are + compiled with cross compilers, such as libiberty or libgloss. + This is essentially a bug in autoconf, and there will probably be + a better workaround at some point. + +`AC_PROG_CXX' + If you are writing C++ code, you will want to use this macro. It + locates the C++ compiler to use. It does not take any arguments. + The same cross compiler comments apply as for `AC_PROG_CC'. + +`AM_PROG_LIBTOOL' + If you want to build libraries, and you want to permit them to be + shared, or you want to link against libraries which were built + using libtool, then you will need this macro. This macro is + required in order to use libtool. + + By default, this will cause all libraries to be built as shared + libraries. To prevent this-to change the default-use + `AM_DISABLE_SHARED' before `AM_PROG_LIBTOOL'. The configure + options `--enable-shared' and `--disable-shared' may be used to + override the default at build time. + +`AC_DEFINE(_GNU_SOURCE)' + GNU packages should normally include this line before any other + feature tests. This defines the macro `_GNU_SOURCE' when + compiling, which directs the libc header files to provide the + standard GNU system interfaces including all GNU extensions. If + this macro is not defined, certain GNU extensions may not be + available. + +`AC_OUTPUT' + This macro takes a list of file names which the configure process + should produce. This is normally a list of one or more `Makefile' + files in different directories. If your package lives entirely in + a single directory, you would use simply `AC_OUTPUT(Makefile)'. + If you also have, for example, a `lib' subdirectory, you would use + `AC_OUTPUT(Makefile lib/Makefile)'. + + If you want to use locally defined macros in your `configure.in' +file, then you will need to write a `acinclude.m4' file which defines +them (if not using automake, this file is called `aclocal.m4'). +Alternatively, you can put separate macros in an `m4' subdirectory, and +put `ACLOCAL_AMFLAGS = -I m4' in your `Makefile.am' file so that the +`aclocal' program will be able to find them. + + The different macro prefixes indicate which tool defines the macro. +Macros which start with `AC_' are part of autoconf. Macros which start +with `AM_' are provided by automake or libtool. + + +File: configure.info, Node: Write Makefile.am, Next: Write acconfig.h, Prev: Write configure.in, Up: Getting Started + +Write Makefile.am +================= + + You must write the file `Makefile.am'. This is an automake input +file, and the automake manual describes in detail what this file should +look like. + + The automake commands in `Makefile.am' mostly look like variable +assignments in a `Makefile'. automake recognizes special variable +names, and automatically add make rules to the output as needed. + + There will be one `Makefile.am' file for each directory in your +package. For each directory with subdirectories, the `Makefile.am' +file should contain the line + SUBDIRS = DIR DIR ... + +where each DIR is the name of a subdirectory. + + For each `Makefile.am', there should be a corresponding `Makefile' +in the `AC_OUTPUT' macro in `configure.in'. + + Every `Makefile.am' written at Cygnus should contain the line + AUTOMAKE_OPTIONS = cygnus + +This puts automake into Cygnus mode. See the automake manual for +details. + + You may to include the version number of `automake' that you are +using on the `AUTOMAKE_OPTIONS' line. For example, + AUTOMAKE_OPTIONS = cygnus 1.3 + +This will prevent users from running an earlier version of `automake' +and perhaps getting an invalid `Makefile.in'. + + If your package builds a program, then in the directory where that +program is built you will normally want a line like + bin_PROGRAMS = PROGRAM + +where PROGRAM is the name of the program. You will then want a line +like + PROGRAM_SOURCES = FILE FILE ... + +where each FILE is the name of a source file to link into the program +(e.g., `foo.c'). + + If your package builds a library, and you do not want the library to +ever be built as a shared library, then in the directory where that +library is built you will normally want a line like + lib_LIBRARIES = libNAME.a + +where `libNAME.a' is the name of the library. You will then want a +line like + libNAME_a_SOURCES = FILE FILE ... + +where each FILE is the name of a source file to add to the library. + + If your package builds a library, and you want to permit building the +library as a shared library, then in the directory where that library is +built you will normally want a line like + lib_LTLIBRARIES = libNAME.la + The use of `LTLIBRARIES', and the `.la' extension, indicate a +library to be built using libtool. As usual, you will then want a line +like + libNAME_la_SOURCES = FILE FILE ... + + The strings `bin' and `lib' that appear above in `bin_PROGRAMS' and +`lib_LIBRARIES' are not arbitrary. They refer to particular +directories, which may be set by the `--bindir' and `--libdir' options +to `configure'. If those options are not used, the default values are +based on the `--prefix' or `--exec-prefix' options to `configure'. It +is possible to use other names if the program or library should be +installed in some other directory. + + The `Makefile.am' file may also contain almost anything that may +appear in a normal `Makefile'. automake also supports many other +special variables, as well as conditionals. + + See the automake manual for more information. + + +File: configure.info, Node: Write acconfig.h, Next: Generate files, Prev: Write Makefile.am, Up: Getting Started + +Write acconfig.h +================ + + If you are generating a portability header file, (i.e., you are using +`AM_CONFIG_HEADER' in `configure.in'), then you will have to write a +`acconfig.h' file. It will have to contain the following lines. + + /* Name of package. */ + #undef PACKAGE + + /* Version of package. */ + #undef VERSION + + This requirement is really a bug in the system, and the requirement +may be eliminated at some later date. + + The `acconfig.h' file will also similar comment and `#undef' lines +for any unusual macros in the `configure.in' file, including any macro +which appears in a `AC_DEFINE' macro. + + In particular, if you are writing a GNU package and therefore include +`AC_DEFINE(_GNU_SOURCE)' in `configure.in' as suggested above, you will +need lines like this in `acconfig.h': + /* Enable GNU extensions. */ + #undef _GNU_SOURCE + + Normally the `autoheader' program will inform you of any such +requirements by printing an error message when it is run. However, if +you do anything particular odd in your `configure.in' file, you will +have to make sure that the right entries appear in `acconfig.h', since +otherwise the results of the tests may not be available in the +`config.h' file which your code will use. + + (Thee `PACKAGE' and `VERSION' lines are not required if you are not +using automake, and in that case you may not need a `acconfig.h' file +at all). + + +File: configure.info, Node: Generate files, Next: Getting Started Example, Prev: Write acconfig.h, Up: Getting Started + +Generate files +============== + + Once you have written `configure.in', `Makefile.am', `acconfig.h', +and possibly `acinclude.m4', you must use autoconf and automake +programs to produce the first versions of the generated files. This is +done by executing the following sequence of commands. + + aclocal + autoconf + autoheader + automake + + The `aclocal' and `automake' commands are part of the automake +package, and the `autoconf' and `autoheader' commands are part of the +autoconf package. + + If you are using a `m4' subdirectory for your macros, you will need +to use the `-I m4' option when you run `aclocal'. + + If you are not using the Cygnus tree, use the `-a' option when +running `automake' command in order to copy the required support files +into your source directory. + + If you are using libtool, you must build and install the libtool +package with the same `--prefix' and `--exec-prefix' options as you +used with the autoconf and automake packages. You must do this before +running any of the above commands. If you are not using the Cygnus +tree, you will need to run the `libtoolize' program to copy the libtool +support files into your directory. + + Once you have managed to run these commands without getting any +errors, you should create a new empty directory, and run the `configure' +script which will have been created by `autoconf' with the +`--enable-maintainer-mode' option. This will give you a set of +Makefiles which will include rules to automatically rebuild all the +generated files. + + After doing that, whenever you have changed some of the input files +and want to regenerated the other files, go to your object directory +and run `make'. Doing this is more reliable than trying to rebuild the +files manually, because there are complex order dependencies and it is +easy to forget something. + + +File: configure.info, Node: Getting Started Example, Prev: Generate files, Up: Getting Started + +Example +======= + + Let's consider a trivial example. + + Suppose we want to write a simple version of `touch'. Our program, +which we will call `poke', will take a single file name argument, and +use the `utime' system call to set the modification and access times of +the file to the current time. We want this program to be highly +portable. + + We'll first see what this looks like without using autoconf and +automake, and then see what it looks like with them. + +* Menu: + +* Getting Started Example 1:: First Try. +* Getting Started Example 2:: Second Try. +* Getting Started Example 3:: Third Try. +* Generate Files in Example:: Generate Files. + + +File: configure.info, Node: Getting Started Example 1, Next: Getting Started Example 2, Up: Getting Started Example + +First Try +--------- + + Here is our first try at `poke.c'. Note that we've written it +without ANSI/ISO C prototypes, since we want it to be highly portable. + + #include <stdio.h> + #include <stdlib.h> + #include <sys/types.h> + #include <utime.h> + + int + main (argc, argv) + int argc; + char **argv; + { + if (argc != 2) + { + fprintf (stderr, "Usage: poke file\n"); + exit (1); + } + + if (utime (argv[1], NULL) < 0) + { + perror ("utime"); + exit (1); + } + + exit (0); + } + + We also write a simple `Makefile'. + + CC = gcc + CFLAGS = -g -O2 + + all: poke + + poke: poke.o + $(CC) -o poke $(CFLAGS) $(LDFLAGS) poke.o + + So far, so good. + + Unfortunately, there are a few problems. + + On older Unix systems derived from BSD 4.3, the `utime' system call +does not accept a second argument of `NULL'. On those systems, we need +to pass a pointer to `struct utimbuf' structure. Unfortunately, even +older systems don't define that structure; on those systems, we need to +pass an array of two `long' values. + + The header file `stdlib.h' was invented by ANSI C, and older systems +don't have a copy. We included it above to get a declaration of `exit'. + + We can find some of these portability problems by running +`autoscan', which will create a `configure.scan' file which we can use +as a prototype for our `configure.in' file. I won't show the output, +but it will notice the potential problems with `utime' and `stdlib.h'. + + In our `Makefile', we don't provide any way to install the program. +This doesn't matter much for such a simple example, but a real program +will need an `install' target. For that matter, we will also want a +`clean' target. + + +File: configure.info, Node: Getting Started Example 2, Next: Getting Started Example 3, Prev: Getting Started Example 1, Up: Getting Started Example + +Second Try +---------- + + Here is our second try at this program. + + We modify `poke.c' to use preprocessor macros to control what +features are available. (I've cheated a bit by using the same macro +names which autoconf will use). + + #include <stdio.h> + + #ifdef STDC_HEADERS + #include <stdlib.h> + #endif + + #include <sys/types.h> + + #ifdef HAVE_UTIME_H + #include <utime.h> + #endif + + #ifndef HAVE_UTIME_NULL + + #include <time.h> + + #ifndef HAVE_STRUCT_UTIMBUF + + struct utimbuf + { + long actime; + long modtime; + }; + + #endif + + static int + utime_now (file) + char *file; + { + struct utimbuf now; + + now.actime = now.modtime = time (NULL); + return utime (file, &now); + } + + #define utime(f, p) utime_now (f) + + #endif /* HAVE_UTIME_NULL */ + + int + main (argc, argv) + int argc; + char **argv; + { + if (argc != 2) + { + fprintf (stderr, "Usage: poke file\n"); + exit (1); + } + + if (utime (argv[1], NULL) < 0) + { + perror ("utime"); + exit (1); + } + + exit (0); + } + + Here is the associated `Makefile'. We've added support for the +preprocessor flags we use. We've also added `install' and `clean' +targets. + + # Set this to your installation directory. + bindir = /usr/local/bin + + # Uncomment this if you have the standard ANSI/ISO C header files. + # STDC_HDRS = -DSTDC_HEADERS + + # Uncomment this if you have utime.h. + # UTIME_H = -DHAVE_UTIME_H + + # Uncomment this if utime (FILE, NULL) works on your system. + # UTIME_NULL = -DHAVE_UTIME_NULL + + # Uncomment this if struct utimbuf is defined in utime.h. + # UTIMBUF = -DHAVE_STRUCT_UTIMBUF + + CC = gcc + CFLAGS = -g -O2 + + ALL_CFLAGS = $(STDC_HDRS) $(UTIME_H) $(UTIME_NULL) $(UTIMBUF) $(CFLAGS) + + all: poke + + poke: poke.o + $(CC) -o poke $(ALL_CFLAGS) $(LDFLAGS) poke.o + + .c.o: + $(CC) -c $(ALL_CFLAGS) poke.c + + install: poke + cp poke $(bindir)/poke + + clean: + rm poke poke.o + + Some problems with this approach should be clear. + + Users who want to compile poke will have to know how `utime' works +on their systems, so that they can uncomment the `Makefile' correctly. + + The installation is done using `cp', but many systems have an +`install' program which may be used, and which supports optional +features such as stripping debugging information out of the installed +binary. + + The use of `Makefile' variables like `CC', `CFLAGS' and `LDFLAGS' +follows the requirements of the GNU standards. This is convenient for +all packages, since it reduces surprises for users. However, it is +easy to get the details wrong, and wind up with a slightly nonstandard +distribution. + + +File: configure.info, Node: Getting Started Example 3, Next: Generate Files in Example, Prev: Getting Started Example 2, Up: Getting Started Example + +Third Try +--------- + + For our third try at this program, we will write a `configure.in' +script to discover the configuration features on the host system, rather +than requiring the user to edit the `Makefile'. We will also write a +`Makefile.am' rather than a `Makefile'. + + The only change to `poke.c' is to add a line at the start of the +file: + #include "config.h" + + The new `configure.in' file is as follows. + + AC_INIT(poke.c) + AM_INIT_AUTOMAKE(poke, 1.0) + AM_CONFIG_HEADER(config.h:config.in) + AC_PROG_CC + AC_HEADER_STDC + AC_CHECK_HEADERS(utime.h) + AC_EGREP_HEADER(utimbuf, utime.h, AC_DEFINE(HAVE_STRUCT_UTIMBUF)) + AC_FUNC_UTIME_NULL + AC_OUTPUT(Makefile) + + The first four macros in this file, and the last one, were described +above; see *Note Write configure.in::. If we omit these macros, then +when we run `automake' we will get a reminder that we need them. + + The other macros are standard autoconf macros. + +`AC_HEADER_STDC' + Check for standard C headers. + +`AC_CHECK_HEADERS' + Check whether a particular header file exists. + +`AC_EGREP_HEADER' + Check for a particular string in a particular header file, in this + case checking for `utimbuf' in `utime.h'. + +`AC_FUNC_UTIME_NULL' + Check whether `utime' accepts a NULL second argument to set the + file change time to the current time. + + See the autoconf manual for a more complete description. + + The new `Makefile.am' file is as follows. Note how simple this is +compared to our earlier `Makefile'. + + bin_PROGRAMS = poke + + poke_SOURCES = poke.c + + This means that we should build a single program name `poke'. It +should be installed in the binary directory, which we called `bindir' +earlier. The program `poke' is built from the source file `poke.c'. + + We must also write a `acconfig.h' file. Besides `PACKAGE' and +`VERSION', which must be mentioned for all packages which use automake, +we must include `HAVE_STRUCT_UTIMBUF', since we mentioned it in an +`AC_DEFINE'. + + /* Name of package. */ + #undef PACKAGE + + /* Version of package. */ + #undef VERSION + + /* Whether utime.h defines struct utimbuf. */ + #undef HAVE_STRUCT_UTIMBUF + + +File: configure.info, Node: Generate Files in Example, Prev: Getting Started Example 3, Up: Getting Started Example + +Generate Files +-------------- + + We must now generate the other files, using the following commands. + + aclocal + autoconf + autoheader + automake + + When we run `autoheader', it will remind us of any macros we forgot +to add to `acconfig.h'. + + When we run `automake', it will want to add some files to our +distribution. It will add them automatically if we use the +`--add-missing' option. + + By default, `automake' will run in GNU mode, which means that it +will want us to create certain additional files; as of this writing, it +will want `NEWS', `README', `AUTHORS', and `ChangeLog', all of which +are files which should appear in a standard GNU distribution. We can +either add those files, or run `automake' with the `--foreign' option. + + Running these tools will generate the following files, all of which +are described in the next chapter. + + * `aclocal.m4' + + * `configure' + + * `config.in' + + * `Makefile.in' + + * `stamp-h.in' + + +File: configure.info, Node: Files, Next: Configuration Names, Prev: Getting Started, Up: Top + +Files +***** + + As was seen in the previous chapter, the GNU configure and build +system uses a number of different files. The developer must write a +few files. The others are generated by various tools. + + The system is rather flexible, and can be used in many different +ways. In describing the files that it uses, I will describe the common +case, and mention some other cases that may arise. + +* Menu: + +* Developer Files:: Developer Files. +* Build Files:: Build Files. +* Support Files:: Support Files. + + +File: configure.info, Node: Developer Files, Next: Build Files, Up: Files + +Developer Files +=============== + + This section describes the files written or generated by the +developer of a package. + +* Menu: + +* Developer Files Picture:: Developer Files Picture. +* Written Developer Files:: Written Developer Files. +* Generated Developer Files:: Generated Developer Files. + + +File: configure.info, Node: Developer Files Picture, Next: Written Developer Files, Up: Developer Files + +Developer Files Picture +----------------------- + + Here is a picture of the files which are written by the developer, +the generated files which would be included with a complete source +distribution, and the tools which create those files. The file names +are plain text and the tool names are enclosed by `*' characters (e.g., +`autoheader' is the name of a tool, not the name of a file). + + acconfig.h configure.in Makefile.am + | | | + | --------------+---------------------- | + | | | | | + v v | acinclude.m4 | | + *autoheader* | | v v + | | v --->*automake* + v |--->*aclocal* | | + config.in | | | v + | v | Makefile.in + | aclocal.m4--- + | | + v v + *autoconf* + | + v + configure + + +File: configure.info, Node: Written Developer Files, Next: Generated Developer Files, Prev: Developer Files Picture, Up: Developer Files + +Written Developer Files +----------------------- + + The following files would be written by the developer. + +`configure.in' + This is the configuration script. This script contains + invocations of autoconf macros. It may also contain ordinary + shell script code. This file will contain feature tests for + portability issues. The last thing in the file will normally be + an `AC_OUTPUT' macro listing which files to create when the + builder runs the configure script. This file is always required + when using the GNU configure system. *Note Write configure.in::. + +`Makefile.am' + This is the automake input file. It describes how the code should + be built. It consists of definitions of automake variables. It + may also contain ordinary Makefile targets. This file is only + needed when using automake (newer tools normally use automake, but + there are still older tools which have not been converted, in + which the developer writes `Makefile.in' directly). *Note Write + Makefile.am::. + +`acconfig.h' + When the configure script creates a portability header file, by + using `AM_CONFIG_HEADER' (or, if not using automake, + `AC_CONFIG_HEADER'), this file is used to describe macros which are + not recognized by the `autoheader' command. This is normally a + fairly uninteresting file, consisting of a collection of `#undef' + lines with comments. Normally any call to `AC_DEFINE' in + `configure.in' will require a line in this file. *Note Write + acconfig.h::. + +`acinclude.m4' + This file is not always required. It defines local autoconf + macros. These macros may then be used in `configure.in'. If you + don't need any local autoconf macros, then you don't need this + file at all. In fact, in general, you never need local autoconf + macros, since you can put everything in `configure.in', but + sometimes a local macro is convenient. + + Newer tools may omit `acinclude.m4', and instead use a + subdirectory, typically named `m4', and define `ACLOCAL_AMFLAGS = + -I m4' in `Makefile.am' to force `aclocal' to look there for macro + definitions. The macro definitions are then placed in separate + files in that directory. + + The `acinclude.m4' file is only used when using automake; in older + tools, the developer writes `aclocal.m4' directly, if it is needed. + + +File: configure.info, Node: Generated Developer Files, Prev: Written Developer Files, Up: Developer Files + +Generated Developer Files +------------------------- + + The following files would be generated by the developer. + + When using automake, these files are normally not generated manually +after the first time. Instead, the generated `Makefile' contains rules +to automatically rebuild the files as required. When +`AM_MAINTAINER_MODE' is used in `configure.in' (the normal case in +Cygnus code), the automatic rebuilding rules will only be defined if +you configure using the `--enable-maintainer-mode' option. + + When using automatic rebuilding, it is important to ensure that all +the various tools have been built and installed on your `PATH'. Using +automatic rebuilding is highly recommended, so much so that I'm not +going to explain what you have to do if you don't use it. + +`configure' + This is the configure script which will be run when building the + package. This is generated by `autoconf' from `configure.in' and + `aclocal.m4'. This is a shell script. + +`Makefile.in' + This is the file which the configure script will turn into the + `Makefile' at build time. This file is generated by `automake' + from `Makefile.am'. If you aren't using automake, you must write + this file yourself. This file is pretty much a normal `Makefile', + with some configure substitutions for certain variables. + +`aclocal.m4' + This file is created by the `aclocal' program, based on the + contents of `configure.in' and `acinclude.m4' (or, as noted in the + description of `acinclude.m4' above, on the contents of an `m4' + subdirectory). This file contains definitions of autoconf macros + which `autoconf' will use when generating the file `configure'. + These autoconf macros may be defined by you in `acinclude.m4' or + they may be defined by other packages such as automake, libtool or + gettext. If you aren't using automake, you will normally write + this file yourself; in that case, if `configure.in' uses only + standard autoconf macros, this file will not be needed at all. + +`config.in' + This file is created by `autoheader' based on `acconfig.h' and + `configure.in'. At build time, the configure script will define + some of the macros in it to create `config.h', which may then be + included by your program. This permits your C code to use + preprocessor conditionals to change its behaviour based on the + characteristics of the host system. This file may also be called + `config.h.in'. + +`stamp.h-in' + This rather uninteresting file, which I omitted from the picture, + is generated by `automake'. It always contains the string + `timestamp'. It is used as a timestamp file indicating whether + `config.in' is up to date. Using a timestamp file means that + `config.in' can be marked as up to date without actually changing + its modification time. This is useful since `config.in' depends + upon `configure.in', but it is easy to change `configure.in' in a + way which does not affect `config.in'. + + +File: configure.info, Node: Build Files, Next: Support Files, Prev: Developer Files, Up: Files + +Build Files +=========== + + This section describes the files which are created at configure and +build time. These are the files which somebody who builds the package +will see. + + Of course, the developer will also build the package. The +distinction between developer files and build files is not that the +developer does not see the build files, but that somebody who only +builds the package does not have to worry about the developer files. + +* Menu: + +* Build Files Picture:: Build Files Picture. +* Build Files Description:: Build Files Description. + + +File: configure.info, Node: Build Files Picture, Next: Build Files Description, Up: Build Files + +Build Files Picture +------------------- + + Here is a picture of the files which will be created at build time. +`config.status' is both a created file and a shell script which is run +to create other files, and the picture attempts to show that. + + config.in *configure* Makefile.in + | | | + | v | + | config.status | + | | | + *config.status*<======+==========>*config.status* + | | + v v + config.h Makefile + + +File: configure.info, Node: Build Files Description, Prev: Build Files Picture, Up: Build Files + +Build Files Description +----------------------- + + This is a description of the files which are created at build time. + +`config.status' + The first step in building a package is to run the `configure' + script. The `configure' script will create the file + `config.status', which is itself a shell script. When you first + run `configure', it will automatically run `config.status'. An + `Makefile' derived from an automake generated `Makefile.in' will + contain rules to automatically run `config.status' again when + necessary to recreate certain files if their inputs change. + +`Makefile' + This is the file which make will read to build the program. The + `config.status' script will transform `Makefile.in' into + `Makefile'. + +`config.h' + This file defines C preprocessor macros which C code can use to + adjust its behaviour on different systems. The `config.status' + script will transform `config.in' into `config.h'. + +`config.cache' + This file did not fit neatly into the picture, and I omitted it. + It is used by the `configure' script to cache results between + runs. This can be an important speedup. If you modify + `configure.in' in such a way that the results of old tests should + change (perhaps you have added a new library to `LDFLAGS'), then + you will have to remove `config.cache' to force the tests to be + rerun. + + The autoconf manual explains how to set up a site specific cache + file. This can speed up running `configure' scripts on your + system. + +`stamp.h' + This file, which I omitted from the picture, is similar to + `stamp-h.in'. It is used as a timestamp file indicating whether + `config.h' is up to date. This is useful since `config.h' depends + upon `config.status', but it is easy for `config.status' to change + in a way which does not affect `config.h'. + + +File: configure.info, Node: Support Files, Prev: Build Files, Up: Files + +Support Files +============= + + The GNU configure and build system requires several support files to +be included with your distribution. You do not normally need to concern +yourself with these. If you are using the Cygnus tree, most are already +present. Otherwise, they will be installed with your source by +`automake' (with the `--add-missing' option) and `libtoolize'. + + You don't have to put the support files in the top level directory. +You can put them in a subdirectory, and use the `AC_CONFIG_AUX_DIR' +macro in `configure.in' to tell `automake' and the `configure' script +where they are. + + In this section, I describe the support files, so that you can know +what they are and why they are there. + +`ABOUT-NLS' + Added by automake if you are using gettext. This is a + documentation file about the gettext project. + +`ansi2knr.c' + Used by an automake generated `Makefile' if you put `ansi2knr' in + `AUTOMAKE_OPTIONS' in `Makefile.am'. This permits compiling ANSI + C code with a K&R C compiler. + +`ansi2knr.1' + The man page which goes with `ansi2knr.c'. + +`config.guess' + A shell script which determines the configuration name for the + system on which it is run. + +`config.sub' + A shell script which canonicalizes a configuration name entered by + a user. + +`elisp-comp' + Used to compile Emacs LISP files. + +`install-sh' + A shell script which installs a program. This is used if the + configure script can not find an install binary. + +`ltconfig' + Used by libtool. This is a shell script which configures libtool + for the particular system on which it is used. + +`ltmain.sh' + Used by libtool. This is the actual libtool script which is used, + after it is configured by `ltconfig' to build a library. + +`mdate-sh' + A shell script used by an automake generated `Makefile' to pretty + print the modification time of a file. This is used to maintain + version numbers for texinfo files. + +`missing' + A shell script used if some tool is missing entirely. This is + used by an automake generated `Makefile' to avoid certain sorts of + timestamp problems. + +`mkinstalldirs' + A shell script which creates a directory, including all parent + directories. This is used by an automake generated `Makefile' + during installation. + +`texinfo.tex' + Required if you have any texinfo files. This is used when + converting Texinfo files into DVI using `texi2dvi' and TeX. + +`ylwrap' + A shell script used by an automake generated `Makefile' to run + programs like `bison', `yacc', `flex', and `lex'. These programs + default to producing output files with a fixed name, and the + `ylwrap' script runs them in a subdirectory to avoid file name + conflicts when using a parallel make program. + + +File: configure.info, Node: Configuration Names, Next: Cross Compilation Tools, Prev: Files, Up: Top + +Configuration Names +******************* + + The GNU configure system names all systems using a "configuration +name". All such names used to be triplets (they may now contain four +parts in certain cases), and the term "configuration triplet" is still +seen. + +* Menu: + +* Configuration Name Definition:: Configuration Name Definition. +* Using Configuration Names:: Using Configuration Names. + |