| This is configure.info, produced by makeinfo version 4.0 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. |
| |