home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / automake-1.1e-bin.lha / info / automake.info-1 next >
Encoding:
GNU Info File  |  1996-10-12  |  49.4 KB  |  1,335 lines
  1. This is Info file automake.info, produced by Makeinfo-1.64 from the
  2. input file /ade-src/fsf/automake/automake.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * automake: (automake).        Making Makefile.in's
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This file documents GNU automake 1.1e
  9.  
  10.    Copyright (C) 1995 Free Software Foundation, Inc.
  11.  
  12.    Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16.    Permission is granted to copy and distribute modified versions of
  17. this manual under the conditions for verbatim copying, provided that
  18. the entire resulting derived work is distributed under the terms of a
  19. permission notice identical to this one.
  20.  
  21.    Permission is granted to copy and distribute translations of this
  22. manual into another language, under the above conditions for modified
  23. versions, except that this permission notice may be stated in a
  24. translation approved by the Foundation.
  25.  
  26. 
  27. File: automake.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
  28.  
  29. GNU Automake
  30. ************
  31.  
  32.    This file documents the GNU Automake package for creating GNU
  33. Standards-compliant Makefiles from template files.  This edition
  34. documents version 1.1e.
  35.  
  36. * Menu:
  37.  
  38. * Introduction::                Automake's purpose
  39. * Invoking Automake::           Creating a Makefile.in
  40. * Generalities::                General ideas
  41. * configure::                   Scanning configure.in
  42. * Top level::                   The top-level Makefile.am
  43. * Programs::                    Building programs and libraries
  44. * Other objects::               Other derived objects
  45. * Other GNU Tools::             Other GNU Tools
  46. * Documentation::               Building documentation
  47. * Install::                     What gets installed
  48. * Clean::                       What gets cleaned
  49. * Dist::                        What goes in a distribution
  50. * Tests::                       Support for test suites
  51. * Options::                     Changing Automake's behavior
  52. * Miscellaneous::               Miscellaneous rules
  53. * Extending::                   Extending Automake
  54. * Distributing::                Distributing the Makefile.in
  55. * Examples::                    Some example packages
  56. * Future::                      Some ideas for the future
  57. * Variables::                   Index of variables
  58. * Configure variables::         Index of configure variables and macros
  59. * Targets::                     Index of targets
  60.  
  61. 
  62. File: automake.info,  Node: Introduction,  Next: Invoking Automake,  Prev: Top,  Up: Top
  63.  
  64. Introduction
  65. ************
  66.  
  67.    Automake is a tool for automatically generating `Makefile.in's from
  68. files called `Makefile.am'.  The `Makefile.am' is basically a series of
  69. `make' macro definitions (with rules being thrown in occasionally).
  70. The generated `Makefile.in's are compliant with the GNU Makefile
  71. standards.
  72.  
  73.    The GNU Makefile Standards Document (*note Makefile Conventions:
  74. (standards.info)Makefile Conventions.) is long, complicated, and
  75. subject to change.  The goal of Automake is to remove the burden of
  76. Makefile maintenance from the back of the individual GNU maintainer
  77. (and put it on the back of the Automake maintainer).
  78.  
  79.    The typical Automake input files is simply a series of macro
  80. definitions.  Each such file is processed to create a `Makefile.in'.
  81. There should generally be one `Makefile.am' per directory of a project.
  82.  
  83.    Automake does constrain a project in certain ways; for instance it
  84. assumes that the project uses Autoconf (*note The Autoconf Manual:
  85. (autoconf.info)Top.), and enforces certain restrictions on the
  86. `configure.in' contents.
  87.  
  88.    `Automake' requires `perl' in order to generate the `Makefile.in's.
  89. However, the distributions created by Automake are fully GNU
  90. standards-compliant, and do not require `perl' in order to be built.
  91.  
  92.    Mail suggestions and bug reports for Automake to
  93. bug-gnu-utils@prep.ai.mit.edu.
  94.  
  95. 
  96. File: automake.info,  Node: Invoking Automake,  Next: Generalities,  Prev: Introduction,  Up: Top
  97.  
  98. Creating a `Makefile.in'
  99. ************************
  100.  
  101.    To create all the `Makefile.in's for a package, run the `automake'
  102. program in the top level directory, with no arguments.  `automake' will
  103. automatically find each appropriate `Makefile.am' (by scanning
  104. `configure.in'; *note configure::.) and generate the corresponding
  105. `Makefile.in'.
  106.  
  107.    You can optionally give `automake' an argument; `.am' is appended to
  108. the argument and the result is used as the name of the input file.
  109. This feature is generally only used to automatically rebuild an
  110. out-of-date `Makefile.in'.  Note that `automake' must always be run
  111. from the topmost directory of a project, even if being used to
  112. regenerate the `Makefile.in' in some subdirectory.  This is necessary
  113. because `automake' must scan `configure.in', and because `automake'
  114. uses the knowledge that a `Makefile.in' is in a subdirectory to change
  115. its behavior in some cases.
  116.  
  117.    `automake' accepts the following options:
  118.  
  119. `-a'
  120. `--add-missing'
  121.      Automake requires certain common files to exist in certain
  122.      situations; for instance `config.guess' is required if
  123.      `configure.in' runs `AC_CANONICAL_HOST'.  Automake is distributed
  124.      with several of these files; this option will cause the missing
  125.      ones to be automatically added to the package, whenever possible.
  126.      In general if Automake tells you a file is missing, try using this
  127.      option.
  128.  
  129. `--amdir=DIR'
  130.      Look for Automake data files in directory DIR instead of in the
  131.      installation directory.  This is typically used for debugging.
  132.  
  133. `--build-dir=DIR'
  134.      Tell Automake where the build directory is.  This option is used
  135.      when including dependencies into a `Makefile.in' generated by `make
  136.      dist'; it should not be used otherwise.
  137.  
  138. `--foreign'
  139.      An alias for `--strictness=foreign'.
  140.  
  141. `--gnits'
  142.      An alias for `--strictness=gnits'.
  143.  
  144. `--gnu'
  145.      An alias for `--strictness=gnu'.
  146.  
  147. `--help'
  148.      Print a summary of the command line options and exit.
  149.  
  150. `-i'
  151. `--include-deps'
  152.      Include all automatically generated dependency information (*note
  153.      Dependencies::.) in the generated `Makefile.in'.  This is
  154.      generally done when making a distribution; see *Note Dist::.
  155.  
  156. `-o DIR'
  157. `--output-dir=DIR'
  158.      Put the generated `Makefile.in' in the directory DIR.  Ordinarily
  159.      each `Makefile.in' is created in the directory of the
  160.      corresponding `Makefile.am'.  This option is used when making
  161.      distributions.
  162.  
  163. `--srcdir-name=DIR'
  164.      Tell Automake the name of the source directory used in the current
  165.      build.  This option is used when including dependencies into a
  166.      `Makefile.in' generated by `make dist'; it should not be used
  167.      otherwise.
  168.  
  169. `-s LEVEL'
  170. `--strictness=LEVEL'
  171.      Set the global strictness to LEVEL; this can be overridden in each
  172.      `Makefile.am' if required.  *Note Generalities:: for more
  173.      information.
  174.  
  175. `-v'
  176. `--verbose'
  177.      Cause Automake to print information about which files are being
  178.      read or created.
  179.  
  180. `--version'
  181.      Print the version number of Automake and exit.
  182.  
  183. 
  184. File: automake.info,  Node: Generalities,  Next: configure,  Prev: Invoking Automake,  Up: Top
  185.  
  186. General ideas
  187. *************
  188.  
  189.    There are a few basic ideas that will help understand how Automake
  190. works.
  191.  
  192. * Menu:
  193.  
  194. * General Operation::           General operation of Automake
  195. * Depth::                       The kinds of packages
  196. * Strictness::                  Standards conformance checking
  197. * Uniform::                     The Uniform Naming Scheme
  198. * Canonicalization::            How derived variables are named
  199.  
  200. 
  201. File: automake.info,  Node: General Operation,  Next: Depth,  Up: Generalities
  202.  
  203. General Operation
  204. =================
  205.  
  206.    Automake essentially works by reading a `Makefile.am' and generating
  207. a `Makefile.in'.
  208.  
  209.    The macro definitions and targets in the `Makefile.am' are copied
  210. into the generated file.  This allows you to add essentially arbitrary
  211. code into the generated `Makefile.in'.  For instance the Automake
  212. distribution includes a non-standard `cvs-dist' target, which the
  213. Automake maintainer uses to make distributions from his source control
  214. system.
  215.  
  216.    Note that GNU make extensions are not recognized by Automake.  Using
  217. such extensions in a `Makefile.am' will lead to errors or confusing
  218. behavior.
  219.  
  220.    Automake tries to group comments with adjoining targets (or variable
  221. definitions) in an intelligent way.
  222.  
  223.    A target defined in `Makefile.am' generally overrides any such
  224. target of a similar name that would be automatically generated by
  225. `automake'.  Although this is a supported feature, it is generally best
  226. to avoid making use of it, as sometimes the generated rules are very
  227. particular.
  228.  
  229.    When examining a variable definition, Automake will recursively
  230. examine variables referenced in the definition.  Eg if Automake is
  231. looking at the content of `foo_SOURCES' in this snippet
  232.  
  233.      xs = a.c b.c
  234.      foo_SOURCES = c.c $(xs)
  235.  
  236.    it would use the files `a.c', `b.c', and `c.c' as the contents of
  237. `foo_SOURCES'.
  238.  
  239.    Automake also allows a form of comment which is *not* copied into
  240. the output; all lines beginning with `##' are completely ignored by
  241. Automake.
  242.  
  243.    It is customary to make the first line of `Makefile.am' read:
  244.  
  245.      ## Process this file with automake to produce Makefile.in
  246.  
  247. 
  248. File: automake.info,  Node: Depth,  Next: Strictness,  Prev: General Operation,  Up: Generalities
  249.  
  250. Depth
  251. =====
  252.  
  253.    `automake' supports three kinds of directory hierarchy: "flat",
  254. "shallow", and "deep".
  255.  
  256.    A "flat" package is one in which all the files are in a single
  257. directory.  The `Makefile.am' for such a package by definition lacks a
  258. `SUBDIRS' macro.  An example of such a package is `termutils'.
  259.  
  260.    A "deep" package is one in which all the source lies in
  261. subdirectories; the top level directory contains mainly configuration
  262. information.  GNU cpio is a good example of such a package, as is GNU
  263. `tar'.  The top level `Makefile.am' for a deep package will contain a
  264. `SUBDIRS' macro, but no other macros to define objects which are built.
  265.  
  266.    A "shallow" package is one in which the primary source resides in
  267. the top-level directory, while various parts (typically libraries)
  268. reside in subdirectories.  `automake' is one such package (as is GNU
  269. `make', which does not currently use `automake').
  270.  
  271. 
  272. File: automake.info,  Node: Strictness,  Next: Uniform,  Prev: Depth,  Up: Generalities
  273.  
  274. Strictness
  275. ==========
  276.  
  277.    While Automake is intended to be used by maintainers of GNU
  278. packages, it does make some effort to accommodate those who wish to use
  279. it, but do not want to use all the GNU conventions.
  280.  
  281.    To this end, Automake supports three levels of "strictness" - the
  282. strictness indicating how stringently Automake should check standards
  283. conformance.
  284.  
  285.    The valid strictness levels are:
  286.  
  287. `foreign'
  288.      Automake will check for only those things which are absolutely
  289.      required for proper operations.  For instance, whereas GNU
  290.      standards dictate the existence of a `NEWS' file, it will not be
  291.      required in this mode.  The name comes from the fact that Automake
  292.      is intended to be used for GNU programs; these relaxed rules are
  293.      not the standard mode of operation.
  294.  
  295. `gnu'
  296.      Automake will check - as much as possible - for compliance to the
  297.      GNU standards for packages.  This is the default.
  298.  
  299. `gnits'
  300.      Automake will check for compliance to the as-yet-unwritten GNITS
  301.      standards.  These are based on the GNU standards, but are even more
  302.      detailed.  Unless you are a GNITS standards contributor, it is
  303.      recommended that you avoid this option until such time as the GNITS
  304.      standard is actually published.
  305.  
  306. 
  307. File: automake.info,  Node: Uniform,  Next: Canonicalization,  Prev: Strictness,  Up: Generalities
  308.  
  309. The Uniform Naming Scheme
  310. =========================
  311.  
  312.    Automake variables generally follow a uniform naming scheme that
  313. makes it easy to decide how programs (and other derived objects) are
  314. built, and how they are installed.  This scheme also supports
  315. `configure' time determination of what should be built.
  316.  
  317.    At `make' time, certain variables are used to determine which
  318. objects are to be built.  These variables are called "primary"
  319. variables.  For instance, the primary variable `PROGRAMS' holds a list
  320. of programs which are to be compiled and linked.
  321.  
  322.    A different set of variables is used to decide where the built
  323. objects should be installed.  These variables are named after the
  324. primary variables, but have a prefix indicating which standard
  325. directory should be used as the installation directory.  The standard
  326. directory names are given in the GNU standards (*note Directory
  327. Variables: (standards.info)Directory Variables.).  `automake' extends
  328. this list with `pkglibdir', `pkgincludedir', and `pkgdatadir'; these
  329. are the same as the non-`pkg' versions, but with `@PACKAGE@' appended.
  330.  
  331.    For each primary, there is one additional variable named by
  332. prepending `EXTRA_' to the primary name.  This variable is used to list
  333. objects which may or may not be built, depending on what `configure'
  334. decides.  This variable is required because Automake must know the
  335. entire list of objects to be built in order to generate a `Makefile.in'
  336. that will work in all cases.
  337.  
  338.    For instance, `cpio' decides at configure time which programs are
  339. built.  Some of the programs are installed in `bindir', and some are
  340. installed in `sbindir':
  341.  
  342.      EXTRA_PROGRAMS = mt rmt
  343.      bin_PROGRAMS = cpio pax
  344.      sbin_PROGRAMS = @PROGRAMS@
  345.  
  346.    Defining a primary variable is an error.
  347.  
  348.    Note that the common `dir' suffix is left off when constructing the
  349. variable names; thus one writes `bin_PROGRAMS' and not
  350. `bindir_PROGRAMS'.
  351.  
  352.    Not every sort of object can be installed in every directory.
  353. Automake will flag those attempts it finds in error.  Automake will
  354. also diagnose obvious misspellings in directory names.
  355.  
  356.    Sometimes the standard directories - even as augmented by Automake -
  357. are not enough.  In particular it is sometimes useful, for clarity, to
  358. install objects in a subdirectory of some predefined directory.  To this
  359. end, Automake allows you to extend the list of possible installation
  360. directories.  A given prefix (eg `zar') is valid if a variable of the
  361. same name with `dir' appended is defined (eg `zardir').
  362.  
  363.    For instance, until HTML support is part of Automake, you could use
  364. this to install raw HTML documentation:
  365.  
  366.      htmldir = $(prefix)/html
  367.      html_DATA = automake.html
  368.  
  369.    The special prefix `noinst' indicates that the objects in question
  370. should not be installed at all.
  371.  
  372.    The special prefix `check' indicates that the objects in question
  373. should not be built until the `make check' command is run.
  374.  
  375.    Possible primary names are `PROGRAMS', `LIBRARIES', `LISP',
  376. `SCRIPTS', `DATA', `HEADERS', `MANS', and `TEXINFOS'.
  377.  
  378. 
  379. File: automake.info,  Node: Canonicalization,  Prev: Uniform,  Up: Generalities
  380.  
  381. How derived variables are named
  382. ===============================
  383.  
  384.    Sometimes a Makefile variable name is derived from some text the user
  385. supplies.  For instance program names are rewritten into Makefile macro
  386. names.  Automake canonicalizes this text, so that it does not have to
  387. follow Makefile variable naming rules.  All characters in the name
  388. except for letters, numbers, and the underscore are turned into
  389. underscores when making macro references.  Eg, if your program is named
  390. `sniff-glue', the derived variable name would be `sniff_glue_SOURCES',
  391. not `sniff-glue_SOURCES'.
  392.  
  393. 
  394. File: automake.info,  Node: configure,  Next: Top level,  Prev: Generalities,  Up: Top
  395.  
  396. Scanning `configure.in'
  397. ***********************
  398.  
  399.    Automake scans the package's `configure.in' to determine certain
  400. information about the package.  Some `autoconf' macros are required and
  401. some variables must be defined in `configure.in'.  Automake will also
  402. use information from `configure.in' to further tailor its output.
  403.  
  404. * Menu:
  405.  
  406. * Requirements::                Configuration requirements
  407. * Optional::                    Other things Automake recognizes
  408. * Invoking aclocal::            Auto-generating aclocal.m4
  409. * Macros::                      Autoconf macros supplied with Automake
  410. * Extending aclocal::           Writing your own aclocal macros
  411.  
  412. 
  413. File: automake.info,  Node: Requirements,  Next: Optional,  Up: configure
  414.  
  415. Configuration requirements
  416. ==========================
  417.  
  418.    The simplest way to meet the basic Automake requirements is to use
  419. the macro `AM_INIT_AUTOMAKE' (FIXME: xref).  But if you prefer, you can
  420. do the required steps by hand:
  421.  
  422.    * Define the variables `PACKAGE' and `VERSION' with `AC_SUBST'.
  423.      `PACKAGE' should be the name of the package as it appears when
  424.      bundled for distribution.  For instance, Automake defines `PACKAGE'
  425.      to be `automake'.  `VERSION' should be the version number of the
  426.      release that is being developed.  We recommend that you make
  427.      `configure.in' the only place in your package where the version
  428.      number is defined; this makes releases simpler.
  429.  
  430.      Automake doesn't do any interpretation of `PACKAGE' or `VERSION',
  431.      except in `Gnits' mode (FIXME xref).
  432.  
  433.    * Use the macro `AC_ARG_PROGRAM' if a program or script is installed.
  434.  
  435.    * Use `AC_PROG_MAKE_SET' if the package is not flat.
  436.  
  437.    * Use `AM_PROG_INSTALL' if any scripts (*note Scripts::.) are
  438.      installed by the package.  Otherwise, use `AC_PROG_INSTALL'.
  439.  
  440.    Here are the other macros which Automake requires but which are not
  441. run by `AM_INIT_AUTOMAKE':
  442.  
  443. `AC_OUTPUT'
  444.      Automake uses this to determine which files to create.  Listed
  445.      files named `Makefile' are treated as `Makefile's.  Other listed
  446.      files are treated differently.  Currently the only difference is
  447.      that a `Makefile' is removed by `make distclean', while other files
  448.      are removed by `make clean'.
  449.  
  450. 
  451. File: automake.info,  Node: Optional,  Next: Invoking aclocal,  Prev: Requirements,  Up: configure
  452.  
  453. Other things Automake recognizes
  454. ================================
  455.  
  456.    Automake will also recognize the use of certain macros and tailor the
  457. generated `Makefile.in' appropriately.  Currently recognized macros and
  458. their effects are:
  459.  
  460. `AC_CONFIG_HEADER'
  461.      Automake will generate rules to automatically regenerate the config
  462.      header.  If you do use this macro, you must create the file
  463.      `stamp-h.in' in your source directory.  It can be empty.  Also, the
  464.      `AC_OUTPUT' command in `configure.in' must create `stamp-h', eg:
  465.           AC_OUTPUT(Makefile,
  466.           [test -z "$CONFIG_HEADERS" || echo timestamp > stamp-h])
  467.      Note that Automake does not currently currently check to make sure
  468.      the `AC_OUTPUT' command is correct.  Hopefully a future version of
  469.      `autoconf' will let Automake handle this automatically.
  470.  
  471. `AC_CONFIG_AUX_DIR'
  472.      Automake will look for various helper scripts, such as
  473.      `mkinstalldirs', in the directory named in this macro invocation.
  474.      If not seen, the scripts are looked for in their "standard"
  475.      locations (either the top source directory, or in the source
  476.      directory corresponding to the current `Makefile.am', whichever is
  477.      appropriate).  FIXME: give complete list of things looked for in
  478.      this directory
  479.  
  480. `AC_PATH_XTRA'
  481.      Automake will insert definitions for the variables defined by
  482.      `AC_PATH_XTRA' into each `Makefile.in' that builds a C program or
  483.      library.
  484.  
  485. `AC_CANONICAL_HOST'
  486. `AC_CANONICAL_SYSTEM'
  487. `AC_CHECK_TOOL'
  488.      Automake will ensure that `config.guess' and `config.sub' exist.
  489.  
  490. `AC_FUNC_ALLOCA'
  491. `AC_FUNC_GETLOADAVG'
  492. `AC_FUNC_MEMCMP'
  493. `AC_STRUCT_ST_BLOCKS'
  494. `AM_FUNC_FNMATCH'
  495. `AM_FUNC_STRTOD'
  496. `AC_REPLACE_FUNCS'
  497. `AC_REPLACE_GNU_GETOPT'
  498. `AM_WITH_REGEX'
  499.      Automake will ensure that the appropriate source files are part of
  500.      the distribution, and will ensure that the appropriate
  501.      dependencies are generated for these objects.  *Note A Library::
  502.      for more information.
  503.  
  504. `LIBOBJS'
  505.      Automake will detect statements which put `.o' files into
  506.      `LIBOBJS', and will treat these additional files as if they were
  507.      discovered via `AC_REPLACE_FUNCS'.
  508.  
  509. `AC_PROG_RANLIB'
  510.      This is required if any libraries are built in the package.
  511.  
  512. `AC_PROG_CXX'
  513.      This is required if any C++ source is included.
  514.  
  515. `AC_PROG_YACC'
  516.      If a Yacc source file is seen, then you must either use this macro
  517.      or declare the variable `YACC' in `configure.in'.  The former is
  518.      preferred.
  519.  
  520. `AC_DECL_YYTEXT'
  521.      This macro is required if there is Yacc source in the package.
  522.  
  523. `AC_PROG_LEX'
  524.      If a Lex source file is seen, then this macro must be used.
  525.  
  526. `ALL_LINGUAS'
  527.      If Automake sees that this variable is set in `configure.in', it
  528.      will check the `po' directory to ensure that all the named `.po'
  529.      files exist, and that all the `.po' files that exist are named.
  530.  
  531. `AM_C_PROTOTYPES'
  532.      This is required when using automatic de-ANSI-fication, see *Note
  533.      ANSI::.
  534.  
  535. `ud_GNU_GETTEXT'
  536.      This macro is required for packages which use GNU gettext (*note
  537.      gettext::.).  It is distributed with gettext.  Automake uses this
  538.      macro to ensure that the package meets some of gettext's
  539.      requirements.
  540.  
  541. `AM_MAINTAINER_MODE'
  542.      This macro adds a `--enable-maintainer-mode' option to
  543.      `configure'.  If this is used, `automake' will cause
  544.      "maintainer-only" rules to be turned off by default in the
  545.      generated `Makefile.in's.  This macro is disallowed in `Gnits'
  546.      mode.  FIXME xref.
  547.  
  548. 
  549. File: automake.info,  Node: Invoking aclocal,  Next: Macros,  Prev: Optional,  Up: configure
  550.  
  551. Auto-generating aclocal.m4
  552. ==========================
  553.  
  554.    The `aclocal' program will automatically generate `aclocal.m4' files
  555. based on the contents of `configure.in'.
  556.  
  557.    ... explain why on earth you'd want to do this
  558.  
  559.    `aclocal' accepts the following options:
  560.  
  561. `--acdir=DIR'
  562.      Look for the macro files in DIR instead of the installation
  563.      directory.  This is typically used for debugging.
  564.  
  565. `--help'
  566.      Print a summary of the command line options and exit.
  567.  
  568. `--output=FILE'
  569.      Cause the output to be put into FILE instead of `aclocal.m4'.
  570.  
  571. `--verbose'
  572.      Print the names of the files it examines.
  573.  
  574. `--version'
  575.      Print the version number of Automake and exit.
  576.  
  577. 
  578. File: automake.info,  Node: Macros,  Next: Extending aclocal,  Prev: Invoking aclocal,  Up: configure
  579.  
  580. Autoconf macros supplied with Automake
  581. ======================================
  582.  
  583. `AM_FUNC_FNMATCH'
  584.      If the `fnmatch' function is not available, or does not work
  585.      correctly (like the one on SunOS 5.4), add `fnmatch.o' to output
  586.      variable `LIBOBJS'.
  587.  
  588. `AM_FUNC_STRTOD'
  589.      If the `strtod' function is not available, or does not work
  590.      correctly (like the one on SunOS 5.4), add `strtod.o' to output
  591.      variable `LIBOBJS'.
  592.  
  593. `AM_C_PROTOTYPES'
  594. `AM_TIOCGWINSZ_NEEDS_IOCTL'
  595. `AM_INIT_AUTOMAKE'
  596. `AM_MAINTAINER_MODE'
  597. `AM_PATH_LISPDIR'
  598. `AM_PROG_CC_STDC'
  599. `AM_PROG_INSTALL'
  600. `AM_SANITY_CHECK_CC'
  601. `AM_SYS_POSIX_TERMIOS'
  602. `AM_TYPE_PTRDIFF_T'
  603. `AM_WITH_DMALLOC'
  604. `AM_WITH_REGEX'
  605. 
  606. File: automake.info,  Node: Extending aclocal,  Prev: Macros,  Up: configure
  607.  
  608. Writing your own aclocal macros
  609. ===============================
  610.  
  611.    ... explain format of macro files ... explain how to get your own
  612. macros installed (using acinstall) ... explain situations where this is
  613. actually useful (eg gettext)
  614.  
  615. 
  616. File: automake.info,  Node: Top level,  Next: Programs,  Prev: configure,  Up: Top
  617.  
  618. The top-level `Makefile.am'
  619. ***************************
  620.  
  621.    In non-flat packages, the top level `Makefile.am' must tell Automake
  622. which subdirectories are to be built.  This is done via the `SUBDIRS'
  623. variable.
  624.  
  625.    The `SUBDIRS' macro holds a list of subdirectories in which building
  626. of various sorts can occur.  Many targets (eg `all') in the generated
  627. `Makefile' will run both locally and in all specified subdirectories.
  628. Note that the directories listed in `SUBDIRS' are not required to
  629. contain `Makefile.am's; only `Makefile's (after configuration).  This
  630. allows inclusion of libraries from packages which do not use Automake
  631. (such as `gettext').
  632.  
  633.    In a deep package, the top-level `Makefile.am' is often very short.
  634. For instance, here is the `Makefile.am' from the textutils distribution:
  635.  
  636.      SUBDIRS = lib src doc man
  637.      EXTRA_DIST = @README_ALPHA@
  638.  
  639.    `SUBDIRS' can contain configure substitutions (eg `@DIRS@');
  640. Automake itself does not actually examine the contents of this variable.
  641.  
  642.    If `SUBDIRS' is defined, then your `configure.in' must include
  643. `AC_PROG_MAKE_SET'.
  644.  
  645.    The use of `SUBDIRS' is not restricted to just the top-level
  646. `Makefile.am'.  Automake can be used to construct packages of arbitrary
  647. depth.
  648.  
  649. 
  650. File: automake.info,  Node: Programs,  Next: Other objects,  Prev: Top level,  Up: Top
  651.  
  652. Building Programs and Libraries
  653. *******************************
  654.  
  655.    A large part of Automake's functionality is dedicated to making it
  656. easy to build C programs and libraries.
  657.  
  658. * Menu:
  659.  
  660. * A Program::                   Building a program
  661. * A Library::                   Building a library
  662. * LIBOBJS::                     Special handling for LIBOBJS and ALLOCA
  663. * Program variables::           Variables used when building a program
  664. * Yacc and Lex::                Yacc and Lex support
  665. * C++::                         C++ and other languages
  666. * ANSI::                        Automatic de-ANSI-fication
  667. * Dependencies::                Automatic dependency tracking
  668.  
  669. 
  670. File: automake.info,  Node: A Program,  Next: A Library,  Up: Programs
  671.  
  672. Building a program
  673. ==================
  674.  
  675.    In a directory containing source that gets built into a program (as
  676. opposed to a library), the `PROGRAMS' primary is used.  Programs can be
  677. installed in `bindir', `sbindir', `libexecdir', `pkglibdir', or not at
  678. all.
  679.  
  680.    For instance:
  681.  
  682.      bin_PROGRAMS = hello
  683.  
  684.    In this simple case, the resulting `Makefile.in' will contain code
  685. to generate a program named `hello'.  The variable `hello_SOURCES' is
  686. used to specify which source files get built into an executable:
  687.  
  688.      hello_SOURCES = hello.c
  689.  
  690.    This causes `hello.c' to be compiled into `hello.o', and then linked
  691. to produce `hello'.
  692.  
  693.    If `prog_SOURCES' is needed, but not specified, then it defaults to
  694. the single file `prog.c'.  In the example above, the definition of
  695. `hello_SOURCES' is actually redundant.
  696.  
  697.    Multiple programs can be built in a single directory.  Multiple
  698. programs can share a single source file.  The source file must be
  699. listed in each `_SOURCES' definition.
  700.  
  701.    Header files listed in a `_SOURCES' definition will be included in
  702. the distribution but otherwise ignored.  In case it isn't obvious, you
  703. should not include the header file generated by `configure' in an
  704. `_SOURCES' variable; this file should not be distributed.  Lex (`.l')
  705. and yacc (`.y') files can also be listed; support for these should work
  706. but is still preliminary.
  707.  
  708.    Sometimes it is useful to determine the programs that are to be
  709. built at configure time.  For instance, GNU `cpio' only builds `mt' and
  710. `rmt' under special circumstances.
  711.  
  712.    In this case, you must notify `Automake' of all the programs that
  713. can possibly be built, but at the same time cause the generated
  714. `Makefile.in' to use the programs specified by `configure'.  This is
  715. done by having `configure' substitute values into each `_PROGRAMS'
  716. definition, while listing all optionally built programs in
  717. `EXTRA_PROGRAMS'.
  718.  
  719.    If you need to link against libraries that are not found by
  720. `configure', you can use `LDADD' to do so.  This variable actually can
  721. be used to add any options to the linker command line.
  722.  
  723.    Sometimes, multiple programs are built in one directory but do not
  724. share the same link-time requirements.  In this case, you can use the
  725. `PROG_LDADD' variable (where PROG is the name of the program as it
  726. appears in some `_PROGRAMS' variable, and usually written in lowercase)
  727. to override the global `LDADD'.  (If this variable exists for a given
  728. program, then that program is not linked using `LDADD'.)
  729.  
  730.    For instance, in GNU cpio, `pax', `cpio', and `mt' are linked
  731. against the library `libcpio.a'.  However, `rmt' is built in the same
  732. directory, and has no such link requirement.  Also, `mt' and `rmt' are
  733. only built on certain architectures.  Here is what cpio's
  734. `src/Makefile.am' looks like (abridged):
  735.  
  736.      bin_PROGRAMS = cpio pax @MT@
  737.      libexec_PROGRAMS = @RMT@
  738.      EXTRA_PROGRAMS = mt rmt
  739.      
  740.      LDADD = ../lib/libcpio.a @INTLLIBS@
  741.      rmt_LDADD =
  742.      
  743.      cpio_SOURCES = ...
  744.      pax_SOURCES = ...
  745.      mt_SOURCES = ...
  746.      rmt_SOURCES = ...
  747.  
  748.    It is also occasionally useful to have a program depend on some other
  749. target which is not actually part of that program.  This can be done
  750. using the `prog_DEPENDENCIES' variable.  Each program depends on the
  751. contents of such a variable, but no further interpretation is done.
  752.  
  753.    If `prog_DEPENDENCIES' is not supplied, it is computed by Automake.
  754. The automatically-assigned value is the contents of `prog_LDADD' with
  755. all the `-l' and `-L' options removed.  Be warned that `configure'
  756. substitutions are preserved; this can lead to bad dependencies if you
  757. are not careful.
  758.  
  759. 
  760. File: automake.info,  Node: A Library,  Next: LIBOBJS,  Prev: A Program,  Up: Programs
  761.  
  762. Building a library
  763. ==================
  764.  
  765.    Building a library is much like building a program.  In this case,
  766. the name of the primary is `LIBRARIES'.  Libraries can be installed in
  767. `libdir' or `pkglibdir'.
  768.  
  769.    Each `_LIBRARIES' variable is a list of the base names of libraries
  770. to be built.  For instance to create a library named `libcpio.a', but
  771. not install it, you would write:
  772.  
  773.      noinst_LIBRARIES = cpio
  774.  
  775.    The sources that go into a library are determined exactly as they are
  776. for programs, via the `_SOURCES' variables.  Note that programs and
  777. libraries share a namespace, so one cannot have a program (`lob') and a
  778. library (`liblob.a') with the same name in one directory.
  779.  
  780.    Extra objects can be added to a library using the `library_LIBADD'
  781. variable.  This should be used for objects determined by `configure'.
  782. Again from cpio:
  783.  
  784.      cpio_LIBADD = @LIBOBJS@ @ALLOCA@
  785.  
  786. 
  787. File: automake.info,  Node: LIBOBJS,  Next: Program variables,  Prev: A Library,  Up: Programs
  788.  
  789. Special handling for LIBOBJS and ALLOCA
  790. =======================================
  791.  
  792.    Automake explicitly recognizes the use of `@LIBOBJS@' and
  793. `@ALLOCA@', and uses this information, plus the list of `LIBOBJS' files
  794. derived from `configure.in' to automatically include the appropriate
  795. source files in the distribution (*note Dist::.).  These source files
  796. are also automatically handled in the dependency-tracking scheme, see
  797. *Note Dependencies::.
  798.  
  799.    `@LIBOBJS@' and `@ALLOCA@' are specially recognized in any `_LDADD'
  800. or `_LIBADD' variable.
  801.  
  802. 
  803. File: automake.info,  Node: Program variables,  Next: Yacc and Lex,  Prev: LIBOBJS,  Up: Programs
  804.  
  805. Variables used when building a program
  806. ======================================
  807.  
  808.    Occasionally it is useful to know which `Makefile' variables
  809. Automake uses for compilations; for instance you might need to do your
  810. own compilation in some special cases.
  811.  
  812.    Some variables are inherited from Autoconf; these are `CC',
  813. `CFLAGS', `CPPFLAGS', `DEFS', `LDFLAGS', and `LIBS'.
  814.  
  815.    There are some additional variables which Automake itself defines:
  816.  
  817. `INCLUDES'
  818.      A list of `-I' options.  This can be set in your `Makefile.am' if
  819.      you have special directories you want to look in.
  820.  
  821. `COMPILE'
  822.      This is the command used to actually compile a C source file.  The
  823.      filename is appended to form the complete command line.
  824.  
  825. `LINK'
  826.      This is the command used to actually link a C program.
  827.  
  828. 
  829. File: automake.info,  Node: Yacc and Lex,  Next: C++,  Prev: Program variables,  Up: Programs
  830.  
  831. Yacc and Lex support
  832. ====================
  833.  
  834.    Automake has somewhat idiosyncratic support for Yacc and Lex.
  835. FIXME: describe it here.
  836.  
  837. 
  838. File: automake.info,  Node: C++,  Next: ANSI,  Prev: Yacc and Lex,  Up: Programs
  839.  
  840. C++ and other languages
  841. =======================
  842.  
  843.    Automake includes full support for C++, and rudimentary support for
  844. other languages.  Support for other languages will be improved based on
  845. demand.
  846.  
  847.    Any package including C++ code must use `AC_PROG_CXX' in its
  848. `configure.in'.
  849.  
  850.    A few additional variables are defined when a C++ source file is
  851. seen:
  852.  
  853. `CXX'
  854.      The name of the C++ compiler.
  855.  
  856. `CXXFLAGS'
  857.      Any flags to pass to the C++ compiler.
  858.  
  859. `CXXCOMPILE'
  860.      The command used to actually compile a C++ source file.  The file
  861.      name is appended to form the complete command line.
  862.  
  863. `CXXLINK'
  864.      The command used to actually link a C++ program.
  865.  
  866. 
  867. File: automake.info,  Node: ANSI,  Next: Dependencies,  Prev: C++,  Up: Programs
  868.  
  869. Automatic de-ANSI-fication
  870. ==========================
  871.  
  872.    Although the GNU standards prohibit it, some GNU programs are
  873. written in ANSI C; see FIXME.  This is possible because each source
  874. file can be "de-ANSI-fied" before the actual compilation takes place.
  875.  
  876.    If the `Makefile.am' variable `AUTOMAKE_OPTIONS' (*Note Options::)
  877. contains the option `ansi2knr' then code to handle de-ANSI-fication is
  878. inserted into the generated `Makefile.in'.
  879.  
  880.    This causes each source file to be treated as ANSI C.  If an ANSI C
  881. compiler is available, it is used.
  882.  
  883.    This support requires the source files `ansi2knr.c' and `ansi2knr.1'
  884. to be in the same directory as the ANSI C source; these files are
  885. distributed with Automake.  Also, the package `configure.in' must call
  886. the macro `AM_C_PROTOTYPES'.
  887.  
  888.    Automake also handles finding the `ansi2knr' support files in some
  889. other directory in the current package.  This is done by prepending the
  890. relative path to the appropriate directory to the `ansi2knr' option.
  891. For instance, suppose the package has ANSI C code in the `src' and
  892. `lib' subdirs.  The files `ansi2knr.c' and `ansi2knr.1' appear in
  893. `lib'.  Then this could appear in `src/Makefile.am':
  894.  
  895.      AUTOMAKE_OPTIONS = ../lib/ansi2knr
  896.  
  897.    Note that the directory holding the `ansi2knr' support files must be
  898. built before all other directories using these files.  Automake does
  899. not currently check that this is the case.
  900.  
  901. 
  902. File: automake.info,  Node: Dependencies,  Prev: ANSI,  Up: Programs
  903.  
  904. Automatic dependency tracking
  905. =============================
  906.  
  907.    As a developer it is often painful to continually update the
  908. `Makefile.in' whenever the include-file dependencies change in a
  909. project.  `automake' supplies a way to automatically track dependency
  910. changes, and distribute the dependencies in the generated `Makefile.in'.
  911.  
  912.    Currently this support requires the use of GNU `make' and `gcc'.  It
  913. might become possible in the future to supply a different dependency
  914. generating program, if there is enough demand.
  915.  
  916.    This mode is enabled by default if any C program or library is
  917. defined in the current directory.
  918.  
  919.    When you decide to make a distribution, the `dist' target will
  920. re-run `automake' with the `--include-deps' option.  This causes the
  921. previously generated dependencies to be inserted into the generated
  922. `Makefile.in', and thus into the distribution.  `--include-deps' also
  923. turns off inclusion of the dependency generation code.
  924.  
  925.    This mode can be suppressed by putting `no-dependencies' in the
  926. variable `AUTOMAKE_OPTIONS'.
  927.  
  928.    If you unpack a distribution made by `make dist', and you want to
  929. turn on the dependency-tracking code again, simply run `automake' with
  930. no arguments.
  931.  
  932. 
  933. File: automake.info,  Node: Other objects,  Next: Other GNU Tools,  Prev: Programs,  Up: Top
  934.  
  935. Other Derived Objects
  936. *********************
  937.  
  938.    Automake can handle derived objects which are not C programs.
  939. Sometimes the support for actually building such objects must be
  940. explicitly supplied, but Automake will still automatically handle
  941. installation and distribution.
  942.  
  943. * Menu:
  944.  
  945. * Scripts::                     Executable scripts
  946. * Headers::                     Header files
  947. * Data::                        Architecture-independent data files
  948. * Sources::                     Derived sources
  949.  
  950. 
  951. File: automake.info,  Node: Scripts,  Next: Headers,  Up: Other objects
  952.  
  953. Executable Scripts
  954. ==================
  955.  
  956.    It is possible to define and install programs which are scripts.
  957. Such programs are listed using the `SCRIPTS' primary name.  `automake'
  958. doesn't define any dependencies for scripts; the `Makefile.am' should
  959. include the appropriate rules.
  960.  
  961.    `automake' does not assume that scripts are derived objects; such
  962. objects must be deleted by hand; see *Note Clean:: for more information.
  963.  
  964.    `automake' itself is a script that is generated at configure time
  965. from `automake.in'.  Here is how this is handled:
  966.  
  967.      bin_SCRIPTS = automake
  968.  
  969.    Since `automake' appears in the `AC_OUTPUT' macro, a target for it
  970. is automatically generated.
  971.  
  972.    Script objects can be installed in `bindir', `sbindir',
  973. `libexecdir', or `pkgdatadir'.
  974.  
  975. 
  976. File: automake.info,  Node: Headers,  Next: Data,  Prev: Scripts,  Up: Other objects
  977.  
  978. Header files
  979. ============
  980.  
  981.    Header files are specified by the `HEADERS' family of variables.
  982. Generally header files are not installed, so the `noinst_HEADERS'
  983. variable will be the most used.
  984.  
  985.    All header files must be listed somewhere; missing ones will not
  986. appear in the distribution.  Often it is clearest to list uninstalled
  987. headers with the rest of the sources for a program.  *Note A Program::.
  988. Headers listed in a `_SOURCES' variable need not be listed in any
  989. `_HEADERS' variable.
  990.  
  991.    Headers can be installed in `includedir', `oldincludedir', or
  992. `pkgincludedir'.
  993.  
  994. 
  995. File: automake.info,  Node: Data,  Next: Sources,  Prev: Headers,  Up: Other objects
  996.  
  997. Architecture-independent data files
  998. ===================================
  999.  
  1000.    Automake supports the installation of miscellaneous data files using
  1001. the `DATA' family of variables.
  1002.  
  1003.    Such data can be installed in the directories `datadir',
  1004. `sysconfdir', `sharedstatedir', `localstatedir', or `pkgdatadir'.
  1005.  
  1006.    All such data files are included in the distribution.
  1007.  
  1008.    Here is how `automake' installs its auxiliary data files:
  1009.  
  1010.      pkgdata_DATA = clean-kr.am clean.am compile-kr.am compile-vars.am \
  1011.      compile.am data.am depend.am dist-subd-top.am dist-subd-vars.am \
  1012.      dist-subd.am dist-vars.am dist.am footer.am header-vars.am header.am \
  1013.      libscripts.am libprograms.am libraries-vars.am libraries.am library.am \
  1014.      mans-vars.am mans.am packagedata.am program.am programs.am remake-hdr.am \
  1015.      remake-subd.am remake.am scripts.am subdirs.am tags.am tags-subd.am \
  1016.      texinfos-vars.am texinfos.am hack-make.sed nl-remove.sed
  1017.  
  1018. 
  1019. File: automake.info,  Node: Sources,  Prev: Data,  Up: Other objects
  1020.  
  1021. Built sources
  1022. =============
  1023.  
  1024.    Occasionally a file which would otherwise be called "source" (eg a C
  1025. `.h' file) is actually derived from some other file.  Such files should
  1026. be listed in the `BUILT_SOURCES' variable.
  1027.  
  1028.    Files listed in `BUILT_SOURCES' are built before any automatic
  1029. dependency tracking is done.  Built sources are included in a
  1030. distribution.
  1031.  
  1032. 
  1033. File: automake.info,  Node: Other GNU Tools,  Next: Documentation,  Prev: Other objects,  Up: Top
  1034.  
  1035. Other GNU Tools
  1036. ***************
  1037.  
  1038.    Since Automake is primarily intended to generate `Makefile.in's for
  1039. use in GNU programs, it tries hard to interoperatoe with other GNU
  1040. tools.
  1041.  
  1042. * Menu:
  1043.  
  1044. * Emacs Lisp::                  Emacs Lisp
  1045. * gettext::                     Gettext
  1046.  
  1047. 
  1048. File: automake.info,  Node: Emacs Lisp,  Next: gettext,  Up: Other GNU Tools
  1049.  
  1050. Emacs Lisp
  1051. ==========
  1052.  
  1053.    Automake provides some support for Emacs Lisp.  The `LISP' primary
  1054. is used to hold a list of `.el' files.  Possible prefixes for this
  1055. primary are `lisp_' and `noinst_'.  Note that if `lisp_LISP' is
  1056. defined, then `configure.in' must run `AM_PATH_LISPDIR' (fixme xref).
  1057.  
  1058.    By default Automake will byte-compile all Emacs Lisp source files
  1059. using the Emacs found by `AM_PATH_LISPDIR'.  If you wish to avoid
  1060. byte-compiling, simply define the variable `ELCFILES' to be empty.
  1061.  
  1062. 
  1063. File: automake.info,  Node: gettext,  Prev: Emacs Lisp,  Up: Other GNU Tools
  1064.  
  1065. Gettext
  1066. =======
  1067.  
  1068.    If `ud_GNU_GETTEXT' is seen in `configure.in', then Automake turns
  1069. on support for GNU gettext, a message catalog system for
  1070. internationalization (*note GNU Gettext: (gettext.info)GNU Gettext.).
  1071.  
  1072.    The `gettext' support in Automake requires the addition of two
  1073. subdirectories to the package, `intl' and `po'.  Automake ensure that
  1074. these directories exist and are mentioned in `SUBDIRS'.
  1075.  
  1076.    Furthermore, Automake checks that the definition of `ALL_LINGUAS' in
  1077. `configure.in' corresponds to all the valid `.po' files, and nothing
  1078. more.
  1079.  
  1080. 
  1081. File: automake.info,  Node: Documentation,  Next: Install,  Prev: Other GNU Tools,  Up: Top
  1082.  
  1083. Building documentation
  1084. **********************
  1085.  
  1086.    Currently Automake provides support for Texinfo and man pages.
  1087.  
  1088. * Menu:
  1089.  
  1090. * Texinfo::                     Texinfo
  1091. * Man pages::                   Man pages
  1092.  
  1093. 
  1094. File: automake.info,  Node: Texinfo,  Next: Man pages,  Up: Documentation
  1095.  
  1096. Texinfo
  1097. =======
  1098.  
  1099.    If the current directory contains Texinfo source, you must declare it
  1100. with the `TEXINFOS' primary.  Generally Texinfo files are converted
  1101. into info, and thus the `info_TEXINFOS' macro is most commonly used
  1102. here.  Note that any Texinfo source file must end in the `.texi' or
  1103. `.texinfo' extension.
  1104.  
  1105.    If the `.texi' file `@include's `version.texi', then that file will
  1106. be automatically generated.  `version.texi' defines three Texinfo
  1107. macros you can reference: `EDITION', `VERSION', and `UPDATED'.  The
  1108. first two hold the version number of your package (but are kept
  1109. separate for clarity); the last is the date the primary file was last
  1110. modified.  The `version.texi' support requires the `mdate-sh' program;
  1111. this program is supplied with Automake.
  1112.  
  1113.    Sometimes an info file actually depends on more than one `.texi'
  1114. file.  For instance, in the `xdvik' distribution, `kpathsea.texi'
  1115. includes the files `install.texi', `copying.texi', and `freedom.texi'.
  1116. You can tell Automake about these dependencies using the
  1117. `texi_TEXINFOS' variable.  Here is how `xdvik' could do it:
  1118.  
  1119.      info_TEXINFOS = kpathsea.texi
  1120.      kpathsea_TEXINFOS = install.texi copying.texi freedom.texi
  1121.  
  1122.    By default, Automake requires the file `texinfo.tex' to appear in
  1123. the same directory as the Texinfo source.  However, if you used
  1124. `AC_CONFIG_AUX_DIR' in `configure.in', then `texinfo.tex' is looked for
  1125. there.  Automake supplies `texinfo.tex'.
  1126.  
  1127.    Automake generates an `install-info' target; some people apparently
  1128. use this.  By default, info pages are installed by `make install'.
  1129. This can be prevented via the `no-installinfo' option.
  1130.  
  1131. 
  1132. File: automake.info,  Node: Man pages,  Prev: Texinfo,  Up: Documentation
  1133.  
  1134. Man pages
  1135. =========
  1136.  
  1137.    A package can also include man pages.  (Though see the GNU standards
  1138. on this matter, *Note Man Pages: (standards.info)Man Pages.)  Man pages
  1139. are declared using the `MANS' primary.  Generally the `man_MANS' macro
  1140. is used.  Man pages are automatically installed in the correct
  1141. subdirectory of `mandir', based on the file extension.
  1142.  
  1143.    By default, man pages are installed by `make install'.  However,
  1144. since the GNU project does not require man pages, many maintainers do
  1145. not expend effort to keep the man pages up to date.  In these cases, the
  1146. `no-installman' option will prevent the man pages from being installed
  1147. by default.  The user can still explicitly install them via `make
  1148. install-man'.
  1149.  
  1150.    Here is how the documentation is handled in GNU `cpio' (which
  1151. includes both Texinfo documentation and man pages):
  1152.  
  1153.      info_TEXINFOS = cpio.texi
  1154.      man_MANS = cpio.1 mt.1
  1155.  
  1156.    Texinfo source, info pages and man pages are all considered to be
  1157. source for the purposes of making a distribution.
  1158.  
  1159. 
  1160. File: automake.info,  Node: Install,  Next: Clean,  Prev: Documentation,  Up: Top
  1161.  
  1162. What Gets Installed
  1163. *******************
  1164.  
  1165.    Naturally, Automake handles the details of actually installing your
  1166. program once it has been built.  All `PROGRAMS', `SCRIPTS',
  1167. `LIBRARIES', `LISP', `DATA' and `HEADERS' are automatically installed
  1168. in the appropriate places.
  1169.  
  1170.    Automake also handles installing any specified info and man pages.
  1171.  
  1172.    Automake generates separate `install-data' and `install-exec'
  1173. targets, in case the installer is installing on multiple machines which
  1174. share directory structure - these targets allow the machine-independent
  1175. parts to be installed only once.  The `install' target depends on both
  1176. of these targets.
  1177.  
  1178.    Automake also generates an `uninstall' target, and an `installdirs'
  1179. target.
  1180.  
  1181.    It is possible to extend this mechanism by defining an
  1182. `install-exec-local' or `install-data-local' target.  If these targets
  1183. exist, they will be run at `make install' time.
  1184.  
  1185. 
  1186. File: automake.info,  Node: Clean,  Next: Dist,  Prev: Install,  Up: Top
  1187.  
  1188. What Gets Cleaned
  1189. *****************
  1190.  
  1191.    The GNU Makefile Standards specify a number of different clean rules.
  1192. Generally the files that can cleaned are determined automatically by
  1193. Automake.  Of course, Automake also recognizes some variables that can
  1194. be defined to specify additional files to clean.  These variables are
  1195. `MOSTLYCLEANFILES', `CLEANFILES', `DISTCLEANFILES', and
  1196. `MAINTAINERCLEANFILES'.
  1197.  
  1198. 
  1199. File: automake.info,  Node: Dist,  Next: Tests,  Prev: Clean,  Up: Top
  1200.  
  1201. What Goes in a Distribution
  1202. ***************************
  1203.  
  1204.    The `dist' target in the generated `Makefile.in' can be used to
  1205. generate a gzip'd `tar' file for distribution.  The tar file is named
  1206. based on the PACKAGE and VERSION variables; more precisely it is named
  1207. `PACKAGE-VERSION.tar.gz'.
  1208.  
  1209.    For the most part, the files to distribute are automatically found by
  1210. Automake: all source files are automatically included in a distribution,
  1211. as are all `Makefile.am's and `Makefile.in's.  Automake also has a
  1212. built-in list of commonly used files which, if present in the current
  1213. directory, are automatically included.  This list is printed by
  1214. `automake --help'.  Also, files which are read by `configure' (ie, the
  1215. source files corresponding to the files specified in the `AC_OUTPUT'
  1216. invocation) are automatically distributed.
  1217.  
  1218.    Still, sometimes there are files which must be distributed, but which
  1219. are not covered in the automatic rules.  These files should be listed in
  1220. the `EXTRA_DIST' variable.
  1221.  
  1222.    Occasionally it is useful to be able to change the distribution
  1223. before it is packaged up.  If the `dist-hook' target exists, it is run
  1224. after the distribution directory is filled, but before the actual tar
  1225. (or shar) file is created.  One way to use this is for distributing file
  1226. in subdirectories for which a new `Makefile.am' is overkill:
  1227.  
  1228.      dist-hook:
  1229.              mkdir $(distdir)/random
  1230.              cp -p random/a1 random/a2 $(distdir)/random
  1231.  
  1232.    Automake also generates a `distcheck' target which can be help to
  1233. ensure that a given distribution will actually work.  `distcheck' makes
  1234. a distribution, and then tries to do a `VPATH' build.
  1235.  
  1236. 
  1237. File: automake.info,  Node: Tests,  Next: Options,  Prev: Dist,  Up: Top
  1238.  
  1239. Support for test suites
  1240. ***********************
  1241.  
  1242.    Automake supports a two forms of test suite.
  1243.  
  1244.    If the variable `TESTS' is defined, its value is taken to be a list
  1245. of programs to run in order to do the testing.  The programs can either
  1246. be derived objects or source objects; the generated rule will look both
  1247. in SRCDIR and `.'.  The number of failures will be printed at the end
  1248. of the run.  The variable `TESTS_ENVIRONMENT' can be used to set
  1249. environment variables for the test run; the environment variable
  1250. `srcdir' is set in the rule.
  1251.  
  1252.    If `dejagnu' appears in `AUTOMAKE_OPTIONS', then the a
  1253. `dejagnu'-based test suite is assumed.  The value of the variable
  1254. `DEJATOOL' is passed as the `--tool' argument to `runtest'; it defaults
  1255. to the name of the package.  The variables `EXPECT', `RUNTEST' and
  1256. `RUNTESTFLAGS' can also be overridden to provide project-specific
  1257. values.  For instance, you will need to do this if you are testing a
  1258. compiler toolchain, because the default values do not take into account
  1259. host and target names.
  1260.  
  1261.    In either case, the testing is done via `make check'.
  1262.  
  1263. 
  1264. File: automake.info,  Node: Options,  Next: Miscellaneous,  Prev: Tests,  Up: Top
  1265.  
  1266. Changing Automake's Behavior
  1267. ****************************
  1268.  
  1269.    Various features of Automake can be controlled by options in the
  1270. `Makefile.am'.  Such options are listed in a special variable named
  1271. `AUTOMAKE_OPTIONS'.  Currently understood options are:
  1272.  
  1273. `gnits'
  1274. `gnu'
  1275. `foreign'
  1276.      The same as the corresponding `--strictness' option.
  1277.  
  1278. `no-installman'
  1279.      The generated `Makefile.in' will not cause man pages to be
  1280.      installed by default.  However, an `install-man' target will still
  1281.      be available for optional installation.  This option is disallowed
  1282.      at `GNU' strictness and above.
  1283.  
  1284. `no-installinfo'
  1285.      The generated `Makefile.in' will not cause info pages to be built
  1286.      or installed by default.  However, `info' and `install-info'
  1287.      targets will still be available.  This option is disallowed at
  1288.      `GNU' strictness and above.
  1289.  
  1290. `ansi2knr'
  1291. `path/ansi2knr'
  1292.      Turn on automatic de-ANSI-fication.  *Note ANSI::.  If preceeded
  1293.      by a path, the generated `Makefile.in' will look in the specified
  1294.      directory to find the `ansi2knr' program.  Generally the path
  1295.      should be a relative path to another directory in the same
  1296.      distribution (though Automake currently does not check this).  It
  1297.      is up to you to make sure that the specified directory is built
  1298.      before the current directory; if `ansi2knr' does not exist then
  1299.      the build will fail.
  1300.  
  1301. `dejagnu'
  1302.      Cause `dejagnu'-specific rules to be generated.  *Note Tests::.
  1303.  
  1304. `dist-shar'
  1305.      Generate a `dist-shar' target as well as the ordinary `dist'
  1306.      target.  This new target will create a shar archive of the
  1307.      distribution.
  1308.  
  1309. `dist-zip'
  1310.      Generate a `dist-zip' target as well as the ordinary `dist'
  1311.      target.  This new target will create a zip archive of the
  1312.      distribution.
  1313.  
  1314. `dist-tarZ'
  1315.      Generate a `dist-tarZ' target as well as the ordinary `dist'
  1316.      target.  This new target will create a compressed tar archive of
  1317.      the distribution; a traditional `tar' and `compress' will be
  1318.      assumed.  Warning: if you are actually using `GNU tar', then the
  1319.      generated archive might contain nonportable constructs.
  1320.  
  1321. `no-dependencies'
  1322.      This is similar to using `--include-deps' on the command line, but
  1323.      is useful for those situations where you don't have the necessary
  1324.      bits to make automatic dependency tracking work *Note
  1325.      Dependencies::.  In this case the effect is to effectively disable
  1326.      automatic dependency tracking.
  1327.  
  1328. VERSION
  1329.      A version number (eg `0.30') can be specified.  If Automake is not
  1330.      newer than the version specified, creation of the `Makefile.in'
  1331.      will be suppressed.
  1332.  
  1333.    Unrecognized options are diagnosed by `automake'.
  1334.  
  1335.