1: \input texinfo
    2: @c %**start of header
    3: @setfilename configure.info
    4: @settitle The GNU configure and build system
    5: @setchapternewpage off
    6: @c %**end of header
    7: 
    8: @dircategory GNU admin
    9: @direntry
   10: * configure: (configure).       The GNU configure and build system
   11: @end direntry
   12: 
   13: @ifnottex
   14: This file documents the GNU configure and build system.
   15: 
   16: Copyright (C) 1998 Cygnus Solutions.
   17: 
   18: Permission is granted to make and distribute verbatim copies of
   19: this manual provided the copyright notice and this permission notice
   20: are preserved on all copies.
   21: 
   22: @ignore
   23: Permission is granted to process this file through TeX and print the
   24: results, provided the printed document carries copying permission
   25: notice identical to this one except for the removal of this paragraph
   26: 
   27: 
   28: @end ignore
   29: Permission is granted to copy and distribute modified versions of this
   30: manual under the conditions for verbatim copying, provided that the entire
   31: resulting derived work is distributed under the terms of a permission
   32: notice identical to this one.
   33: 
   34: Permission is granted to copy and distribute translations of this manual
   35: into another language, under the above conditions for modified versions,
   36: except that this permission notice may be stated in a translation approved
   37: by the Foundation.
   38: @end ifnottex
   39: 
   40: @titlepage
   41: @title The GNU configure and build system
   42: @author Ian Lance Taylor
   43: 
   44: @page
   45: @vskip 0pt plus 1filll
   46: Copyright @copyright{} 1998 Cygnus Solutions
   47: 
   48: Permission is granted to make and distribute verbatim copies of
   49: this manual provided the copyright notice and this permission notice
   50: are preserved on all copies.
   51: 
   52: Permission is granted to copy and distribute modified versions of this
   53: manual under the conditions for verbatim copying, provided that the entire
   54: resulting derived work is distributed under the terms of a permission
   55: notice identical to this one.
   56: 
   57: Permission is granted to copy and distribute translations of this manual
   58: into another language, under the above conditions for modified versions,
   59: except that this permission notice may be stated in a translation
   60: approved by the Free Software Foundation.
   61: @end titlepage
   62: 
   63: @ifnottex
   64: @node Top
   65: @top GNU configure and build system
   66: 
   67: The GNU configure and build system.
   68: 
   69: @menu
   70: * Introduction::                Introduction.
   71: * Getting Started::             Getting Started.
   72: * Files::                       Files.
   73: * Configuration Names::         Configuration Names.
   74: * Cross Compilation Tools::     Cross Compilation Tools.
   75: * Canadian Cross::              Canadian Cross.
   76: * Cygnus Configure::            Cygnus Configure.
   77: * Multilibs::                   Multilibs.
   78: * FAQ::                         Frequently Asked Questions.
   79: * Index::                       Index.
   80: @end menu
   81: 
   82: @end ifnottex
   83: 
   84: @node Introduction
   85: @chapter Introduction
   86: 
   87: This document describes the GNU configure and build systems.  It
   88: describes how autoconf, automake, libtool, and make fit together.  It
   89: also includes a discussion of the older Cygnus configure system.
   90: 
   91: This document does not describe in detail how to use each of the tools;
   92: see the respective manuals for that.  Instead, it describes which files
   93: the developer must write, which files are machine generated and how they
   94: are generated, and where certain common problems should be addressed.
   95: 
   96: @ifnothtml
   97: This document draws on several sources, including the autoconf manual by
   98: David MacKenzie (@pxref{Top, , autoconf overview, autoconf, Autoconf}),
   99: the automake manual by David MacKenzie and Tom Tromey (@pxref{Top, ,
  100: automake overview, automake, GNU Automake}), the libtool manual by
  101: Gordon Matzigkeit (@pxref{Top, , libtool overview, libtool, GNU
  102: libtool}), and the Cygnus configure manual by K. Richard Pixley.
  103: @end ifnothtml
  104: @ifhtml
  105: This document draws on several sources, including
  106: @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_toc.html, the
  107: autoconf manual} by David MacKenzie,
  108: @uref{http://www.delorie.com/gnu/docs/automake/automake_toc.html, the
  109: automake manual} by David MacKenzie and Tom Tromey,
  110: @uref{http://www.delorie.com/gnu/docs/libtool/libtool_toc.html, the
  111: libtool manual} by Gordon Matzigkeit, and the Cygnus configure manual by
  112: K. Richard Pixley.
  113: @end ifhtml
  114: 
  115: @menu
  116: * Goals::                       Goals.
  117: * Tools::                       The tools.
  118: * History::                     History.
  119: * Building::                    Building.
  120: @end menu
  121: 
  122: @node Goals
  123: @section Goals
  124: @cindex goals
  125: 
  126: The GNU configure and build system has two main goals.
  127: 
  128: The first is to simplify the development of portable programs.  The
  129: system permits the developer to concentrate on writing the program,
  130: simplifying many details of portability across Unix and even Windows
  131: systems, and permitting the developer to describe how to build the
  132: program using simple rules rather than complex Makefiles.
  133: 
  134: The second is to simplify the building of programs distributed as source
  135: code.  All programs are built using a simple, standardized, two step
  136: process.  The program builder need not install any special tools in
  137: order to build the program.
  138: 
  139: @node Tools
  140: @section Tools
  141: 
  142: The GNU configure and build system is comprised of several different
  143: tools.  Program developers must build and install all of these tools.
  144: 
  145: People who just want to build programs from distributed sources normally
  146: do not need any special tools beyond a Unix shell, a make program, and a
  147: C compiler.
  148: 
  149: @table @asis
  150: @item autoconf
  151: provides a general portability framework, based on testing the features
  152: of the host system at build time.
  153: @item automake
  154: a system for describing how to build a program, permitting the developer
  155: to write a simplified @file{Makefile}.
  156: @item libtool
  157: a standardized approach to building shared libraries.
  158: @item gettext
  159: provides a framework for translation of text messages into other
  160: languages; not really discussed in this document.
  161: @item m4
  162: autoconf requires the GNU version of m4; the standard Unix m4 does not
  163: suffice.
  164: @item perl
  165: automake requires perl.
  166: @end table
  167: 
  168: @node History
  169: @section History
  170: @cindex history
  171: 
  172: This is a very brief and probably inaccurate history.
  173: 
  174: As the number of Unix variants increased during the 1980s, it became
  175: harder to write programs which could run on all variants.  While it was
  176: often possible to use @code{#ifdef} to identify particular systems,
  177: developers frequently did not have access to every system, and the
  178: characteristics of some systems changed from version to version.
  179: 
  180: By 1992, at least three different approaches had been developed:
  181: @itemize @bullet
  182: @item
  183: The Metaconfig program, by Larry Wall, Harlan Stenn, and Raphael
  184: Manfredi.
  185: @item
  186: The Cygnus configure script, by K. Richard Pixley, and the gcc configure
  187: script, by Richard Stallman.  These use essentially the same approach,
  188: and the developers communicated regularly.
  189: @item
  190: The autoconf program, by David MacKenzie.
  191: @end itemize
  192: 
  193: The Metaconfig program is still used for Perl and a few other programs.
  194: It is part of the Dist package.  I do not know if it is being developed.
  195: 
  196: In 1994, David MacKenzie and others modified autoconf to incorporate all
  197: the features of Cygnus configure.  Since then, there has been a slow but
  198: steady conversion of GNU programs from Cygnus configure to autoconf. gcc
  199: has been converted, eliminating the gcc configure script.
  200: 
  201: GNU autoconf was regularly maintained until late 1996.  As of this
  202: writing in June, 1998, it has no public maintainer.
  203: 
  204: Most programs are built using the make program, which requires the
  205: developer to write Makefiles describing how to build the programs.
  206: Since most programs are built in pretty much the same way, this led to a
  207: lot of duplication.
  208: 
  209: The X Window system is built using the imake tool, which uses a database
  210: of rules to eliminate the duplication.  However, building a tool which
  211: was developed using imake requires that the builder have imake
  212: installed, violating one of the goals of the GNU system.
  213: 
  214: The new BSD make provides a standard library of Makefile fragments,
  215: which permits developers to write very simple Makefiles.  However, this
  216: requires that the builder install the new BSD make program.
  217: 
  218: In 1994, David MacKenzie wrote the first version of automake, which
  219: permitted writing a simple build description which was converted into a
  220: Makefile which could be used by the standard make program.  In 1995, Tom
  221: Tromey completely rewrote automake in Perl, and he continues to enhance
  222: it.
  223: 
  224: Various free packages built libraries, and by around 1995 several
  225: included support to build shared libraries on various platforms.
  226: However, there was no consistent approach.  In early 1996, Gordon
  227: Matzigkeit began working on libtool, which provided a standardized
  228: approach to building shared libraries.  This was integrated into
  229: automake from the start.
  230: 
  231: The development of automake and libtool was driven by the GNITS project,
  232: a group of GNU maintainers who designed standardized tools to help meet
  233: the GNU coding standards.
  234: 
  235: @node Building
  236: @section Building
  237: 
  238: Most readers of this document should already know how to build a tool by
  239: running @samp{configure} and @samp{make}.  This section may serve as a
  240: quick introduction or reminder.
  241: 
  242: Building a tool is normally as simple as running @samp{configure}
  243: followed by @samp{make}.  You should normally run @samp{configure} from
  244: an empty directory, using some path to refer to the @samp{configure}
  245: script in the source directory.  The directory in which you run
  246: @samp{configure} is called the @dfn{object directory}.
  247: 
  248: In order to use a object directory which is different from the source
  249: directory, you must be using the GNU version of @samp{make}, which has
  250: the required @samp{VPATH} support.  Despite this restriction, using a
  251: different object directory is highly recommended:
  252: @itemize @bullet
  253: @item
  254: It keeps the files generated during the build from cluttering up your
  255: sources.
  256: @item 
  257: It permits you to remove the built files by simply removing the entire
  258: build directory.
  259: @item
  260: It permits you to build from the same sources with several sets of
  261: configure options simultaneously.
  262: @end itemize
  263: 
  264: If you don't have GNU @samp{make}, you will have to run @samp{configure}
  265: in the source directory.  All GNU packages should support this; in
  266: particular, GNU packages should not assume the presence of GNU
  267: @samp{make}.
  268: 
  269: After running @samp{configure}, you can build the tools by running
  270: @samp{make}.
  271: 
  272: To install the tools, run @samp{make install}.  Installing the tools
  273: will copy the programs and any required support files to the
  274: @dfn{installation directory}.  The location of the installation
  275: directory is controlled by @samp{configure} options, as described below.
  276: 
  277: In the Cygnus tree at present, the info files are built and installed as
  278: a separate step.  To build them, run @samp{make info}.  To install them,
  279: run @samp{make install-info}. The equivalent html files are also built
  280: and installed in a separate step. To build the html files, run
  281: @samp{make html}. To install the html files run @samp{make install-html}.
  282: 
  283: All @samp{configure} scripts support a wide variety of options.  The
  284: most interesting ones are @samp{--with} and @samp{--enable} options
  285: which are generally specific to particular tools.  You can usually use
  286: the @samp{--help} option to get a list of interesting options for a
  287: particular configure script.
  288: 
  289: The only generic options you are likely to use are the @samp{--prefix}
  290: and @samp{--exec-prefix} options.  These options are used to specify the
  291: installation directory.
  292: 
  293: The directory named by the @samp{--prefix} option will hold machine
  294: independent files such as info files.
  295: 
  296: The directory named by the @samp{--exec-prefix} option, which is
  297: normally a subdirectory of the @samp{--prefix} directory, will hold
  298: machine dependent files such as executables.
  299: 
  300: The default for @samp{--prefix} is @file{/usr/local}.  The default for
  301: @samp{--exec-prefix} is the value used for @samp{--prefix}.
  302: 
  303: The convention used in Cygnus releases is to use a @samp{--prefix}
  304: option of @file{/usr/cygnus/@var{release}}, where @var{release} is the
  305: name of the release, and to use a @samp{--exec-prefix} option of
  306: @file{/usr/cygnus/@var{release}/H-@var{host}}, where @var{host} is the
  307: configuration name of the host system (@pxref{Configuration Names}).
  308: 
  309: Do not use either the source or the object directory as the installation
  310: directory.  That will just lead to confusion.
  311: 
  312: @node Getting Started
  313: @chapter Getting Started
  314: 
  315: To start using the GNU configure and build system with your software
  316: package, you must write three files, and you must run some tools to
  317: manually generate additional files.
  318: 
  319: @menu
  320: * Write configure.in::          Write configure.in.
  321: * Write Makefile.am::           Write Makefile.am.
  322: * Write acconfig.h::            Write acconfig.h.
  323: * Generate files::              Generate files.
  324: * Getting Started Example::     Example.
  325: @end menu
  326: 
  327: @node Write configure.in
  328: @section Write configure.in
  329: @cindex @file{configure.in}, writing
  330: 
  331: You must first write the file @file{configure.in}.  This is an autoconf
  332: input file, and the autoconf manual describes in detail what this file
  333: should look like.
  334: 
  335: You will write tests in your @file{configure.in} file to check for
  336: conditions that may change from one system to another, such as the
  337: presence of particular header files or functions.
  338: 
  339: For example, not all systems support the @samp{gettimeofday} function.
  340: If you want to use the @samp{gettimeofday} function when it is
  341: available, and to use some other function when it is not, you would
  342: check for this by putting @samp{AC_CHECK_FUNCS(gettimeofday)} in
  343: @file{configure.in}.
  344: 
  345: When the configure script is run at build time, this will arrange to
  346: define the preprocessor macro @samp{HAVE_GETTIMEOFDAY} to the value 1 if
  347: the @samp{gettimeofday} function is available, and to not define the
  348: macro at all if the function is not available.  Your code can then use
  349: @samp{#ifdef} to test whether it is safe to call @samp{gettimeofday}.
  350: 
  351: If you have an existing body of code, the @samp{autoscan} program may
  352: help identify potential portability problems, and hence configure tests
  353: that you will want to use.
  354: @ifnothtml
  355: @xref{Invoking autoscan, , , autoconf, the autoconf manual}.
  356: @end ifnothtml
  357: @ifhtml
  358: See @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_4.html, the
  359: autoscan documentation}.
  360: @end ifhtml
  361: 
  362: Another handy tool for an existing body of code is @samp{ifnames}.  This
  363: will show you all the preprocessor conditionals that the code already
  364: uses.
  365: @ifnothtml
  366: @xref{Invoking ifnames, , , autoconf, the autoconf manual}.
  367: @end ifnothtml
  368: @ifhtml
  369: See @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_5.html, the
  370: ifnames documentation}.
  371: @end ifhtml
  372: 
  373: Besides the portability tests which are specific to your particular
  374: package, every @file{configure.in} file should contain the following
  375: macros.
  376: 
  377: @table @samp
  378: @item AC_INIT
  379: @cindex @samp{AC_INIT}
  380: This macro takes a single argument, which is the name of a file in your
  381: package.  For example, @samp{AC_INIT(foo.c)}.
  382: 
  383: @item AC_PREREQ(@var{VERSION})
  384: @cindex @samp{AC_PREREQ}
  385: This macro is optional.  It may be used to indicate the version of
  386: @samp{autoconf} that you are using.  This will prevent users from
  387: running an earlier version of @samp{autoconf} and perhaps getting an
  388: invalid @file{configure} script.  For example, @samp{AC_PREREQ(2.12)}.
  389: 
  390: @item AM_INIT_AUTOMAKE
  391: @cindex @samp{AM_INIT_AUTOMAKE}
  392: This macro takes two arguments: the name of the package, and a version
  393: number.  For example, @samp{AM_INIT_AUTOMAKE(foo, 1.0)}.  (This macro is
  394: not needed if you are not using automake).
  395: 
  396: @item AM_CONFIG_HEADER
  397: @cindex @samp{AM_CONFIG_HEADER}
  398: This macro names the header file which will hold the preprocessor macro
  399: definitions at run time.  Normally this should be @file{config.h}.  Your
  400: sources would then use @samp{#include "config.h"} to include it.
  401: 
  402: This macro may optionally name the input file for that header file; by
  403: default, this is @file{config.h.in}, but that file name works poorly on
  404: DOS filesystems.  Therefore, it is often better to name it explicitly as
  405: @file{config.in}.
  406: 
  407: This is what you should normally put in @file{configure.in}:
  408: @example
  409: AM_CONFIG_HEADER(config.h:config.in)
  410: @end example
  411: 
  412: @cindex @samp{AC_CONFIG_HEADER}
  413: (If you are not using automake, use @samp{AC_CONFIG_HEADER} rather than
  414: @samp{AM_CONFIG_HEADER}).
  415: 
  416: @item AM_MAINTAINER_MODE
  417: @cindex @samp{AM_MAINTAINER_MODE}
  418: This macro always appears in Cygnus configure scripts.  Other programs
  419: may or may not use it.
  420: 
  421: If this macro is used, the @samp{--enable-maintainer-mode} option is
  422: required to enable automatic rebuilding of generated files used by the
  423: configure system.  This of course requires that developers be aware of,
  424: and use, that option.
  425: 
  426: If this macro is not used, then the generated files will always be
  427: rebuilt automatically.  This will cause problems if the wrong versions
  428: of autoconf, automake, or others are in the builder's @samp{PATH}.
  429: 
  430: (If you are not using automake, you do not need to use this macro).
  431: 
  432: @item AC_EXEEXT
  433: @cindex @samp{AC_EXEEXT}
  434: @cindex @samp{AM_EXEEXT}
  435: Either this macro or @samp{AM_EXEEXT} always appears in Cygnus configure
  436: files.  Other programs may or may not use one of them.
  437: 
  438: This macro looks for the executable suffix used on the host system.  On
  439: Unix systems, this is the empty string.  On Windows systems, this is
  440: @samp{.exe}.  This macro directs automake to use the executable suffix
  441: as appropriate when creating programs.  This macro does not take any
  442: arguments.
  443: 
  444: The @samp{AC_EXEEXT} form is new, and is part of a Cygnus patch to
  445: autoconf to support compiling with Visual C++.  Older programs use
  446: @samp{AM_EXEEXT} instead.
  447: 
  448: (Programs which do not use automake use neither @samp{AC_EXEEXT} nor
  449: @samp{AM_EXEEXT}).
  450: 
  451: @item AC_PROG_CC
  452: @cindex @samp{AC_PROG_CC}
  453: If you are writing C code, you will normally want to use this macro.  It
  454: locates the C compiler to use.  It does not take any arguments.
  455: 
  456: However, if this @file{configure.in} file is for a library which is to
  457: be compiled by a cross compiler which may not fully work, then you will
  458: not want to use @samp{AC_PROG_CC}.  Instead, you will want to use a
  459: variant which does not call the macro @samp{AC_PROG_CC_WORKS}.  Examples
  460: can be found in various @file{configure.in} files for libraries that are
  461: compiled with cross compilers, such as libiberty or libgloss.  This is
  462: essentially a bug in autoconf, and there will probably be a better
  463: workaround at some point.
  464: 
  465: @item AC_PROG_CXX
  466: @cindex @samp{AC_PROG_CXX}
  467: If you are writing C++ code, you will want to use this macro.  It
  468: locates the C++ compiler to use.  It does not take any arguments.  The
  469: same cross compiler comments apply as for @samp{AC_PROG_CC}.
  470: 
  471: @item AM_PROG_LIBTOOL
  472: @cindex @samp{AM_PROG_LIBTOOL}
  473: If you want to build libraries, and you want to permit them to be
  474: shared, or you want to link against libraries which were built using
  475: libtool, then you will need this macro.  This macro is required in order
  476: to use libtool.
  477: 
  478: @cindex @samp{AM_DISABLE_SHARED}
  479: By default, this will cause all libraries to be built as shared
  480: libraries.  To prevent this--to change the default--use
  481: @samp{AM_DISABLE_SHARED} before @samp{AM_PROG_LIBTOOL}.  The configure
  482: options @samp{--enable-shared} and @samp{--disable-shared} may be used
  483: to override the default at build time.
  484: 
  485: @item AC_DEFINE(_GNU_SOURCE)
  486: @cindex @samp{_GNU_SOURCE}
  487: GNU packages should normally include this line before any other feature
  488: tests.  This defines the macro @samp{_GNU_SOURCE} when compiling, which
  489: directs the libc header files to provide the standard GNU system
  490: interfaces including all GNU extensions.  If this macro is not defined,
  491: certain GNU extensions may not be available.
  492: 
  493: @item AC_OUTPUT
  494: @cindex @samp{AC_OUTPUT}
  495: This macro takes a list of file names which the configure process should
  496: produce.  This is normally a list of one or more @file{Makefile} files
  497: in different directories.  If your package lives entirely in a single
  498: directory, you would use simply @samp{AC_OUTPUT(Makefile)}.  If you also
  499: have, for example, a @file{lib} subdirectory, you would use
  500: @samp{AC_OUTPUT(Makefile lib/Makefile)}.
  501: @end table
  502: 
  503: If you want to use locally defined macros in your @file{configure.in}
  504: file, then you will need to write a @file{acinclude.m4} file which
  505: defines them (if not using automake, this file is called
  506: @file{aclocal.m4}).  Alternatively, you can put separate macros in an
  507: @file{m4} subdirectory, and put @samp{ACLOCAL_AMFLAGS = -I m4} in your
  508: @file{Makefile.am} file so that the @samp{aclocal} program will be able
  509: to find them.
  510: 
  511: The different macro prefixes indicate which tool defines the macro.
  512: Macros which start with @samp{AC_} are part of autoconf.  Macros which
  513: start with @samp{AM_} are provided by automake or libtool.
  514: 
  515: @node Write Makefile.am
  516: @section Write Makefile.am
  517: @cindex @file{Makefile.am}, writing
  518: 
  519: You must write the file @file{Makefile.am}.  This is an automake input
  520: file, and the automake manual describes in detail what this file should
  521: look like.
  522: 
  523: The automake commands in @file{Makefile.am} mostly look like variable
  524: assignments in a @file{Makefile}.  automake recognizes special variable
  525: names, and automatically add make rules to the output as needed.
  526: 
  527: There will be one @file{Makefile.am} file for each directory in your
  528: package.  For each directory with subdirectories, the @file{Makefile.am}
  529: file should contain the line
  530: @smallexample
  531: SUBDIRS = @var{dir} @var{dir} @dots{}
  532: @end smallexample
  533: @noindent
  534: where each @var{dir} is the name of a subdirectory.
  535: 
  536: For each @file{Makefile.am}, there should be a corresponding
  537: @file{Makefile} in the @samp{AC_OUTPUT} macro in @file{configure.in}.
  538: 
  539: Every @file{Makefile.am} written at Cygnus should contain the line
  540: @smallexample
  541: AUTOMAKE_OPTIONS = cygnus
  542: @end smallexample
  543: @noindent
  544: This puts automake into Cygnus mode.  See the automake manual for
  545: details.
  546: 
  547: You may to include the version number of @samp{automake} that you are
  548: using on the @samp{AUTOMAKE_OPTIONS} line.  For example,
  549: @smallexample
  550: AUTOMAKE_OPTIONS = cygnus 1.3
  551: @end smallexample
  552: @noindent
  553: This will prevent users from running an earlier version of
  554: @samp{automake} and perhaps getting an invalid @file{Makefile.in}.
  555: 
  556: If your package builds a program, then in the directory where that
  557: program is built you will normally want a line like
  558: @smallexample
  559: bin_PROGRAMS = @var{program}
  560: @end smallexample
  561: @noindent
  562: where @var{program} is the name of the program.  You will then want a
  563: line like
  564: @smallexample
  565: @var{program}_SOURCES = @var{file} @var{file} @dots{}
  566: @end smallexample
  567: @noindent
  568: where each @var{file} is the name of a source file to link into the
  569: program (e.g., @samp{foo.c}).
  570: 
  571: If your package builds a library, and you do not want the library to
  572: ever be built as a shared library, then in the directory where that
  573: library is built you will normally want a line like
  574: @smallexample
  575: lib_LIBRARIES = lib@var{name}.a
  576: @end smallexample
  577: @noindent
  578: where @samp{lib@var{name}.a} is the name of the library.  You will then
  579: want a line like
  580: @smallexample
  581: lib@var{name}_a_SOURCES = @var{file} @var{file} @dots{}
  582: @end smallexample
  583: @noindent
  584: where each @var{file} is the name of a source file to add to the
  585: library.
  586: 
  587: If your package builds a library, and you want to permit building the
  588: library as a shared library, then in the directory where that library is
  589: built you will normally want a line like
  590: @smallexample
  591: lib_LTLIBRARIES = lib@var{name}.la
  592: @end smallexample
  593: The use of @samp{LTLIBRARIES}, and the @samp{.la} extension, indicate a
  594: library to be built using libtool.  As usual, you will then want a line
  595: like
  596: @smallexample
  597: lib@var{name}_la_SOURCES = @var{file} @var{file} @dots{}
  598: @end smallexample
  599: 
  600: The strings @samp{bin} and @samp{lib} that appear above in
  601: @samp{bin_PROGRAMS} and @samp{lib_LIBRARIES} are not arbitrary.  They
  602: refer to particular directories, which may be set by the @samp{--bindir}
  603: and @samp{--libdir} options to @file{configure}.  If those options are
  604: not used, the default values are based on the @samp{--prefix} or
  605: @samp{--exec-prefix} options to @file{configure}.  It is possible to use
  606: other names if the program or library should be installed in some other
  607: directory.
  608: 
  609: The @file{Makefile.am} file may also contain almost anything that may
  610: appear in a normal @file{Makefile}.  automake also supports many other
  611: special variables, as well as conditionals.
  612: 
  613: See the automake manual for more information.
  614: 
  615: @node Write acconfig.h
  616: @section Write acconfig.h
  617: @cindex @file{acconfig.h}, writing
  618: 
  619: If you are generating a portability header file, (i.e., you are using
  620: @samp{AM_CONFIG_HEADER} in @file{configure.in}), then you will have to
  621: write a @file{acconfig.h} file.  It will have to contain the following
  622: lines.
  623: 
  624: @smallexample
  625: /* Name of package.  */
  626: #undef PACKAGE
  627: 
  628: /* Version of package.  */
  629: #undef VERSION
  630: @end smallexample
  631: 
  632: This requirement is really a bug in the system, and the requirement may
  633: be eliminated at some later date.
  634: 
  635: The @file{acconfig.h} file will also similar comment and @samp{#undef}
  636: lines for any unusual macros in the @file{configure.in} file, including
  637: any macro which appears in a @samp{AC_DEFINE} macro.
  638: 
  639: In particular, if you are writing a GNU package and therefore include
  640: @samp{AC_DEFINE(_GNU_SOURCE)} in @file{configure.in} as suggested above,
  641: you will need lines like this in @file{acconfig.h}:
  642: @smallexample
  643: /* Enable GNU extensions.  */
  644: #undef _GNU_SOURCE
  645: @end smallexample
  646: 
  647: Normally the @samp{autoheader} program will inform you of any such
  648: requirements by printing an error message when it is run.  However, if
  649: you do anything particular odd in your @file{configure.in} file, you
  650: will have to make sure that the right entries appear in
  651: @file{acconfig.h}, since otherwise the results of the tests may not be
  652: available in the @file{config.h} file which your code will use.
  653: 
  654: (Thee @samp{PACKAGE} and @samp{VERSION} lines are not required if you
  655: are not using automake, and in that case you may not need a
  656: @file{acconfig.h} file at all).
  657: 
  658: @node Generate files
  659: @section Generate files
  660: 
  661: Once you have written @file{configure.in}, @file{Makefile.am},
  662: @file{acconfig.h}, and possibly @file{acinclude.m4}, you must use
  663: autoconf and automake programs to produce the first versions of the
  664: generated files.  This is done by executing the following sequence of
  665: commands.
  666: 
  667: @smallexample
  668: aclocal
  669: autoconf
  670: autoheader
  671: automake
  672: @end smallexample
  673: 
  674: The @samp{aclocal} and @samp{automake} commands are part of the automake
  675: package, and the @samp{autoconf} and @samp{autoheader} commands are part
  676: of the autoconf package.
  677: 
  678: If you are using a @file{m4} subdirectory for your macros, you will need
  679: to use the @samp{-I m4} option when you run @samp{aclocal}.
  680: 
  681: If you are not using the Cygnus tree, use the @samp{-a} option when
  682: running @samp{automake} command in order to copy the required support
  683: files into your source directory.
  684: 
  685: If you are using libtool, you must build and install the libtool package
  686: with the same @samp{--prefix} and @samp{--exec-prefix} options as you
  687: used with the autoconf and automake packages.  You must do this before
  688: running any of the above commands.  If you are not using the Cygnus
  689: tree, you will need to run the @samp{libtoolize} program to copy the
  690: libtool support files into your directory.
  691: 
  692: Once you have managed to run these commands without getting any errors,
  693: you should create a new empty directory, and run the @samp{configure}
  694: script which will have been created by @samp{autoconf} with the
  695: @samp{--enable-maintainer-mode} option.  This will give you a set of
  696: Makefiles which will include rules to automatically rebuild all the
  697: generated files.
  698: 
  699: After doing that, whenever you have changed some of the input files and
  700: want to regenerated the other files, go to your object directory and run
  701: @samp{make}.  Doing this is more reliable than trying to rebuild the
  702: files manually, because there are complex order dependencies and it is
  703: easy to forget something.
  704: 
  705: @node Getting Started Example
  706: @section Example
  707: 
  708: Let's consider a trivial example.
  709: 
  710: Suppose we want to write a simple version of @samp{touch}.  Our program,
  711: which we will call @samp{poke}, will take a single file name argument,
  712: and use the @samp{utime} system call to set the modification and access
  713: times of the file to the current time.  We want this program to be
  714: highly portable.
  715: 
  716: We'll first see what this looks like without using autoconf and
  717: automake, and then see what it looks like with them.
  718: 
  719: @menu
  720: * Getting Started Example 1::           First Try.
  721: * Getting Started Example 2::           Second Try.
  722: * Getting Started Example 3::           Third Try.
  723: * Generate Files in Example::           Generate Files.
  724: @end menu
  725: 
  726: @node Getting Started Example 1
  727: @subsection First Try
  728: 
  729: Here is our first try at @samp{poke.c}.  Note that we've written it
  730: without ANSI/ISO C prototypes, since we want it to be highly portable.
  731: 
  732: @example
  733: #include <stdio.h>
  734: #include <stdlib.h>
  735: #include <sys/types.h>
  736: #include <utime.h>
  737: 
  73