1 This is automake.info, produced by makeinfo version 4.1 from
4 INFO-DIR-SECTION GNU admin
6 * automake: (automake). Making Makefile.in's
9 INFO-DIR-SECTION Individual utilities
11 * aclocal: (automake)Invoking aclocal. Generating aclocal.m4
14 This file documents GNU automake 1.4-p6
16 Copyright (C) 1995, 96, 97, 98 Free Software Foundation, Inc.
18 Permission is granted to make and distribute verbatim copies of this
19 manual provided the copyright notice and this permission notice are
20 preserved on all copies.
22 Permission is granted to copy and distribute modified versions of
23 this manual under the conditions for verbatim copying, provided that
24 the entire resulting derived work is distributed under the terms of a
25 permission notice identical to this one.
27 Permission is granted to copy and distribute translations of this
28 manual into another language, under the above conditions for modified
29 versions, except that this permission notice may be stated in a
30 translation approved by the Foundation.
33 File: automake.info, Node: A Shared Library, Next: Program variables, Prev: LIBOBJS, Up: Programs
35 Building a Shared Library
36 =========================
38 Building shared libraries is a relatively complex matter. For this
39 reason, GNU Libtool (*note Introduction: (libtool)Top.) was created to
40 help build shared libraries in a platform-independent way.
42 Automake uses Libtool to build libraries declared with the
43 `LTLIBRARIES' primary. Each `_LTLIBRARIES' variable is a list of
44 shared libraries to build. For instance, to create a library named
45 `libgettext.a' and its corresponding shared libraries, and install them
48 lib_LTLIBRARIES = libgettext.la
50 Note that shared libraries _must_ be installed, so
51 `check_LTLIBRARIES' is not allowed. However, `noinst_LTLIBRARIES' is
52 allowed. This feature should be used for libtool "convenience
55 For each library, the `LIBRARY_LIBADD' variable contains the names
56 of extra libtool objects (`.lo' files) to add to the shared library.
57 The `LIBRARY_LDFLAGS' variable contains any additional libtool flags,
58 such as `-version-info' or `-static'.
60 Where an ordinary library might include `@LIBOBJS@', a libtool
61 library must use `@LTLIBOBJS@'. This is required because the object
62 files that libtool operates on do not necessarily end in `.o'. The
63 libtool manual contains more details on this topic.
65 For libraries installed in some directory, Automake will
66 automatically supply the appropriate `-rpath' option. However, for
67 libraries determined at configure time (and thus mentioned in
68 `EXTRA_LTLIBRARIES'), Automake does not know the eventual installation
69 directory; for such libraries you must add the `-rpath' option to the
70 appropriate `_LDFLAGS' variable by hand.
72 *Note Using Automake with Libtool: (libtool)Using Automake, for more
76 File: automake.info, Node: Program variables, Next: Yacc and Lex, Prev: A Shared Library, Up: Programs
78 Variables used when building a program
79 ======================================
81 Occasionally it is useful to know which `Makefile' variables
82 Automake uses for compilations; for instance you might need to do your
83 own compilation in some special cases.
85 Some variables are inherited from Autoconf; these are `CC',
86 `CFLAGS', `CPPFLAGS', `DEFS', `LDFLAGS', and `LIBS'.
88 There are some additional variables which Automake itself defines:
91 A list of `-I' options. This can be set in your `Makefile.am' if
92 you have special directories you want to look in. Automake already
93 provides some `-I' options automatically. In particular it
94 generates `-I$(srcdir)' and a `-I' pointing to the directory
95 holding `config.h' (if you've used `AC_CONFIG_HEADER' or
98 `INCLUDES' can actually be used for other `cpp' options besides
99 `-I'. For instance, it is sometimes used to pass arbitrary `-D'
100 options to the compiler.
103 This is the command used to actually compile a C source file. The
104 filename is appended to form the complete command line.
107 This is the command used to actually link a C program.
110 File: automake.info, Node: Yacc and Lex, Next: C++ Support, Prev: Program variables, Up: Programs
115 Automake has somewhat idiosyncratic support for Yacc and Lex.
117 Automake assumes that the `.c' file generated by `yacc' (or `lex')
118 should be named using the basename of the input file. That is, for a
119 yacc source file `foo.y', Automake will cause the intermediate file to
120 be named `foo.c' (as opposed to `y.tab.c', which is more traditional).
122 The extension of a yacc source file is used to determine the
123 extension of the resulting `C' or `C++' file. Files with the extension
124 `.y' will be turned into `.c' files; likewise, `.yy' will become `.cc';
125 `.y++', `c++'; and `.yxx', `.cxx'.
127 Likewise, lex source files can be used to generate `C' or `C++'; the
128 extensions `.l', `.ll', `.l++', and `.lxx' are recognized.
130 You should never explicitly mention the intermediate (`C' or `C++')
131 file in any `SOURCES' variable; only list the source file.
133 The intermediate files generated by `yacc' (or `lex') will be
134 included in any distribution that is made. That way the user doesn't
135 need to have `yacc' or `lex'.
137 If a `yacc' source file is seen, then your `configure.in' must
138 define the variable `YACC'. This is most easily done by invoking the
139 macro `AC_PROG_YACC' (*note Particular Program Checks:
140 (autoconf)Particular Programs.).
142 Similarly, if a `lex' source file is seen, then your `configure.in'
143 must define the variable `LEX'. You can use `AC_PROG_LEX' to do this
144 (*note Particular Program Checks: (autoconf)Particular Programs.).
145 Automake's `lex' support also requires that you use the `AC_DECL_YYTEXT'
146 macro--automake needs to know the value of `LEX_OUTPUT_ROOT'. This is
147 all handled for you if you use the `AM_PROG_LEX' macro (*note Macros::).
149 Automake makes it possible to include multiple `yacc' (or `lex')
150 source files in a single program. Automake uses a small program called
151 `ylwrap' to run `yacc' (or `lex') in a subdirectory. This is necessary
152 because yacc's output filename is fixed, and a parallel make could
153 conceivably invoke more than one instance of `yacc' simultaneously.
154 The `ylwrap' program is distributed with Automake. It should appear in
155 the directory specified by `AC_CONFIG_AUX_DIR' (*note Finding
156 `configure' Input: (autoconf)Input.), or the current directory if that
157 macro is not used in `configure.in'.
159 For `yacc', simply managing locking is insufficient. The output of
160 `yacc' always uses the same symbol names internally, so it isn't
161 possible to link two `yacc' parsers into the same executable.
163 We recommend using the following renaming hack used in `gdb':
164 #define yymaxdepth c_maxdepth
165 #define yyparse c_parse
167 #define yyerror c_error
168 #define yylval c_lval
169 #define yychar c_char
170 #define yydebug c_debug
171 #define yypact c_pact
178 #define yyexca c_exca
179 #define yyerrflag c_errflag
180 #define yynerrs c_nerrs
185 #define yystate c_state
190 #define yylloc c_lloc
191 #define yyreds c_reds
192 #define yytoks c_toks
193 #define yylhs c_yylhs
194 #define yylen c_yylen
195 #define yydefred c_yydefred
196 #define yydgoto c_yydgoto
197 #define yysindex c_yysindex
198 #define yyrindex c_yyrindex
199 #define yygindex c_yygindex
200 #define yytable c_yytable
201 #define yycheck c_yycheck
202 #define yyname c_yyname
203 #define yyrule c_yyrule
205 For each define, replace the `c_' prefix with whatever you like.
206 These defines work for `bison', `byacc', and traditional `yacc's. If
207 you find a parser generator that uses a symbol not covered here, please
208 report the new name so it can be added to the list.
211 File: automake.info, Node: C++ Support, Next: Fortran 77 Support, Prev: Yacc and Lex, Up: Programs
216 Automake includes full support for C++.
218 Any package including C++ code must define the output variable `CXX'
219 in `configure.in'; the simplest way to do this is to use the
220 `AC_PROG_CXX' macro (*note Particular Program Checks:
221 (autoconf)Particular Programs.).
223 A few additional variables are defined when a C++ source file is
227 The name of the C++ compiler.
230 Any flags to pass to the C++ compiler.
233 The command used to actually compile a C++ source file. The file
234 name is appended to form the complete command line.
237 The command used to actually link a C++ program.
240 File: automake.info, Node: Fortran 77 Support, Next: Support for Other Languages, Prev: C++ Support, Up: Programs
245 Automake includes full support for Fortran 77.
247 Any package including Fortran 77 code must define the output variable
248 `F77' in `configure.in'; the simplest way to do this is to use the
249 `AC_PROG_F77' macro (*note Particular Program Checks:
250 (autoconf)Particular Programs.). *Note Fortran 77 and Autoconf::.
252 A few additional variables are defined when a Fortran 77 source file
256 The name of the Fortran 77 compiler.
259 Any flags to pass to the Fortran 77 compiler.
262 Any flags to pass to the Ratfor compiler.
265 The command used to actually compile a Fortran 77 source file.
266 The file name is appended to form the complete command line.
269 The command used to actually link a pure Fortran 77 program or
272 Automake can handle preprocessing Fortran 77 and Ratfor source files
273 in addition to compiling them(1). Automake also contains some support
274 for creating programs and shared libraries that are a mixture of
275 Fortran 77 and other languages (*note Mixing Fortran 77 With C and
278 These issues are covered in the following sections.
282 * Preprocessing Fortran 77::
283 * Compiling Fortran 77 Files::
284 * Mixing Fortran 77 With C and C++::
285 * Fortran 77 and Autoconf::
287 ---------- Footnotes ----------
289 (1) Much, if not most, of the information in the following sections
290 pertaining to preprocessing Fortran 77 programs was taken almost
291 verbatim from *Note Catalogue of Rules: (make)Catalogue of Rules.
294 File: automake.info, Node: Preprocessing Fortran 77, Next: Compiling Fortran 77 Files, Prev: Fortran 77 Support, Up: Fortran 77 Support
296 Preprocessing Fortran 77
297 ------------------------
299 `N.f' is made automatically from `N.F' or `N.r'. This rule runs
300 just the preprocessor to convert a preprocessable Fortran 77 or Ratfor
301 source file into a strict Fortran 77 source file. The precise command
305 `$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
306 $(AM_FFLAGS) $(FFLAGS)'
309 `$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)'
312 File: automake.info, Node: Compiling Fortran 77 Files, Next: Mixing Fortran 77 With C and C++, Prev: Preprocessing Fortran 77, Up: Fortran 77 Support
314 Compiling Fortran 77 Files
315 --------------------------
317 `N.o' is made automatically from `N.f', `N.F' or `N.r' by running
318 the Fortran 77 compiler. The precise command used is as follows:
321 `$(F77) -c $(AM_FFLAGS) $(FFLAGS)'
324 `$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
325 $(AM_FFLAGS) $(FFLAGS)'
328 `$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)'
331 File: automake.info, Node: Mixing Fortran 77 With C and C++, Next: Fortran 77 and Autoconf, Prev: Compiling Fortran 77 Files, Up: Fortran 77 Support
333 Mixing Fortran 77 With C and C++
334 --------------------------------
336 Automake currently provides _limited_ support for creating programs
337 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
338 However, there are many other issues related to mixing Fortran 77 with
339 other languages that are _not_ (currently) handled by Automake, but
340 that are handled by other packages(1).
342 Automake can help in two ways:
344 1. Automatic selection of the linker depending on which combinations
347 2. Automatic selection of the appropriate linker flags (e.g. `-L' and
348 `-l') to pass to the automatically selected linker in order to link
349 in the appropriate Fortran 77 intrinsic and run-time libraries.
351 These extra Fortran 77 linker flags are supplied in the output
352 variable `FLIBS' by the `AC_F77_LIBRARY_LDFLAGS' Autoconf macro
353 supplied with newer versions of Autoconf (Autoconf version 2.13 and
354 later). *Note Fortran 77 Compiler Characteristics:
355 (autoconf)Fortran 77 Compiler Characteristics.
357 If Automake detects that a program or shared library (as mentioned in
358 some `_PROGRAMS' or `_LTLIBRARIES' primary) contains source code that
359 is a mixture of Fortran 77 and C and/or C++, then it requires that the
360 macro `AC_F77_LIBRARY_LDFLAGS' be called in `configure.in', and that
361 either `$(FLIBS)' or `@FLIBS@' appear in the appropriate `_LDADD' (for
362 programs) or `_LIBADD' (for shared libraries) variables. It is the
363 responsibility of the person writing the `Makefile.am' to make sure
364 that `$(FLIBS)' or `@FLIBS@' appears in the appropriate `_LDADD' or
367 For example, consider the following `Makefile.am':
370 foo_SOURCES = main.cc foo.f
371 foo_LDADD = libfoo.la @FLIBS@
373 pkglib_LTLIBRARIES = libfoo.la
374 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
375 libfoo_la_LIBADD = $(FLIBS)
377 In this case, Automake will insist that `AC_F77_LIBRARY_LDFLAGS' is
378 mentioned in `configure.in'. Also, if `@FLIBS@' hadn't been mentioned
379 in `foo_LDADD' and `libfoo_la_LIBADD', then Automake would have issued
384 * How the Linker is Chosen::
386 ---------- Footnotes ----------
388 (1) For example, the cfortran package
389 (http://www-zeus.desy.de/~burow/cfortran/) addresses all of these
390 inter-language issues, and runs under nearly all Fortran 77, C and C++
391 compilers on nearly all platforms. However, `cfortran' is not yet Free
392 Software, but it will be in the next major release.
395 File: automake.info, Node: How the Linker is Chosen, Prev: Mixing Fortran 77 With C and C++, Up: Mixing Fortran 77 With C and C++
397 How the Linker is Chosen
398 ........................
400 The following diagram demonstrates under what conditions a particular
401 linker is chosen by Automake.
403 For example, if Fortran 77, C and C++ source code were to be compiled
404 into a program, then the C++ linker will be used. In this case, if the
405 C or Fortran 77 linkers required any special libraries that weren't
406 included by the C++ linker, then they must be manually added to an
407 `_LDADD' or `_LIBADD' variable by the user writing the `Makefile.am'.
412 ----------------- +---------+---------+---------+
416 +---------+---------+---------+
420 +---------+---------+---------+
424 +---------+---------+---------+
428 +---------+---------+---------+
430 C + Fortran | | | x |
432 +---------+---------+---------+
434 C++ + Fortran | | x | |
436 +---------+---------+---------+
438 C + C++ + Fortran | | x | |
440 +---------+---------+---------+
443 File: automake.info, Node: Fortran 77 and Autoconf, Prev: Mixing Fortran 77 With C and C++, Up: Fortran 77 Support
445 Fortran 77 and Autoconf
446 -----------------------
448 The current Automake support for Fortran 77 requires a recent enough
449 version Autoconf that also includes support for Fortran 77. Full
450 Fortran 77 support was added to Autoconf 2.13, so you will want to use
451 that version of Autoconf or later.
454 File: automake.info, Node: Support for Other Languages, Next: ANSI, Prev: Fortran 77 Support, Up: Programs
456 Support for Other Languages
457 ===========================
459 Automake currently only includes full support for C, C++ (*note C++
460 Support::)and Fortran 77 (*note Fortran 77 Support::). There is only
461 rudimentary support for other languages, support for which will be
462 improved based on user demand.
465 File: automake.info, Node: ANSI, Next: Dependencies, Prev: Support for Other Languages, Up: Programs
467 Automatic de-ANSI-fication
468 ==========================
470 Although the GNU standards allow the use of ANSI C, this can have the
471 effect of limiting portability of a package to some older compilers
474 Automake allows you to work around this problem on such machines by
475 "de-ANSI-fying" each source file before the actual compilation takes
478 If the `Makefile.am' variable `AUTOMAKE_OPTIONS' (*note Options::)
479 contains the option `ansi2knr' then code to handle de-ANSI-fication is
480 inserted into the generated `Makefile.in'.
482 This causes each C source file in the directory to be treated as
483 ANSI C. If an ANSI C compiler is available, it is used. If no ANSI C
484 compiler is available, the `ansi2knr' program is used to convert the
485 source files into K&R C, which is then compiled.
487 The `ansi2knr' program is simple-minded. It assumes the source code
488 will be formatted in a particular way; see the `ansi2knr' man page for
491 Support for de-ANSI-fication requires the source files `ansi2knr.c'
492 and `ansi2knr.1' to be in the same package as the ANSI C source; these
493 files are distributed with Automake. Also, the package `configure.in'
494 must call the macro `AM_C_PROTOTYPES' (*note Macros::).
496 Automake also handles finding the `ansi2knr' support files in some
497 other directory in the current package. This is done by prepending the
498 relative path to the appropriate directory to the `ansi2knr' option.
499 For instance, suppose the package has ANSI C code in the `src' and
500 `lib' subdirs. The files `ansi2knr.c' and `ansi2knr.1' appear in
501 `lib'. Then this could appear in `src/Makefile.am':
503 AUTOMAKE_OPTIONS = ../lib/ansi2knr
505 If no directory prefix is given, the files are assumed to be in the
508 Files mentioned in `LIBOBJS' which need de-ANSI-fication will not be
509 automatically handled. That's because `configure' will generate an
510 object name like `regex.o', while `make' will be looking for `regex_.o'
511 (when de-ANSI-fying). Eventually this problem will be fixed via
512 `autoconf' magic, but for now you must put this code into your
513 `configure.in', just before the `AC_OUTPUT' call:
515 # This is necessary so that .o files in LIBOBJS are also built via
516 # the ANSI2KNR-filtering rules.
517 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
520 File: automake.info, Node: Dependencies, Prev: ANSI, Up: Programs
522 Automatic dependency tracking
523 =============================
525 As a developer it is often painful to continually update the
526 `Makefile.in' whenever the include-file dependencies change in a
527 project. Automake supplies a way to automatically track dependency
528 changes, and distribute the dependencies in the generated `Makefile.in'.
530 Currently this support requires the use of GNU `make' and `gcc'. It
531 might become possible in the future to supply a different dependency
532 generating program, if there is enough demand. In the meantime, this
533 mode is enabled by default if any C program or library is defined in
534 the current directory, so you may get a `Must be a separator' error
537 When you decide to make a distribution, the `dist' target will
538 re-run `automake' with `--include-deps' and other options. *Note
539 Invoking Automake::, and *Note Options::. This will cause the
540 previously generated dependencies to be inserted into the generated
541 `Makefile.in', and thus into the distribution. This step also turns
542 off inclusion of the dependency generation code, so that those who
543 download your distribution but don't use GNU `make' and `gcc' will not
546 When added to the `Makefile.in', the dependencies have all
547 system-specific dependencies automatically removed. This can be done by
548 listing the files in `OMIT_DEPENDENCIES'. For instance all references
549 to system header files are removed by Automake. Sometimes it is useful
550 to specify that a certain header file should be removed. For instance
551 if your `configure.in' uses `AM_WITH_REGEX', then any dependency on
552 `rx.h' or `regex.h' should be removed, because the correct one cannot
553 be known until the user configures the package.
555 As it turns out, Automake is actually smart enough to handle the
556 particular case of the regular expression header. It will also
557 automatically omit `libintl.h' if `AM_GNU_GETTEXT' is used.
559 Automatic dependency tracking can be suppressed by putting
560 `no-dependencies' in the variable `AUTOMAKE_OPTIONS'.
562 If you unpack a distribution made by `make dist', and you want to
563 turn on the dependency-tracking code again, simply re-run `automake'.
565 The actual dependency files are put under the build directory, in a
566 subdirectory named `.deps'. These dependencies are machine specific.
567 It is safe to delete them if you like; they will be automatically
568 recreated during the next build.
571 File: automake.info, Node: Other objects, Next: Other GNU Tools, Prev: Programs, Up: Top
573 Other Derived Objects
574 *********************
576 Automake can handle derived objects which are not C programs.
577 Sometimes the support for actually building such objects must be
578 explicitly supplied, but Automake will still automatically handle
579 installation and distribution.
583 * Scripts:: Executable scripts
584 * Headers:: Header files
585 * Data:: Architecture-independent data files
586 * Sources:: Derived sources
589 File: automake.info, Node: Scripts, Next: Headers, Prev: Other objects, Up: Other objects
594 It is possible to define and install programs which are scripts.
595 Such programs are listed using the `SCRIPTS' primary name. Automake
596 doesn't define any dependencies for scripts; the `Makefile.am' should
597 include the appropriate rules.
599 Automake does not assume that scripts are derived objects; such
600 objects must be deleted by hand (*note Clean::).
602 The `automake' program itself is a Perl script that is generated at
603 configure time from `automake.in'. Here is how this is handled:
605 bin_SCRIPTS = automake
607 Since `automake' appears in the `AC_OUTPUT' macro, a target for it
608 is automatically generated.
610 Script objects can be installed in `bindir', `sbindir',
611 `libexecdir', or `pkgdatadir'.
614 File: automake.info, Node: Headers, Next: Data, Prev: Scripts, Up: Other objects
619 Header files are specified by the `HEADERS' family of variables.
620 Generally header files are not installed, so the `noinst_HEADERS'
621 variable will be the most used.
623 All header files must be listed somewhere; missing ones will not
624 appear in the distribution. Often it is clearest to list uninstalled
625 headers with the rest of the sources for a program. *Note A Program::.
626 Headers listed in a `_SOURCES' variable need not be listed in any
629 Headers can be installed in `includedir', `oldincludedir', or
633 File: automake.info, Node: Data, Next: Sources, Prev: Headers, Up: Other objects
635 Architecture-independent data files
636 ===================================
638 Automake supports the installation of miscellaneous data files using
639 the `DATA' family of variables.
641 Such data can be installed in the directories `datadir',
642 `sysconfdir', `sharedstatedir', `localstatedir', or `pkgdatadir'.
644 By default, data files are _not_ included in a distribution.
646 Here is how Automake installs its auxiliary data files:
648 pkgdata_DATA = clean-kr.am clean.am ...
651 File: automake.info, Node: Sources, Prev: Data, Up: Other objects
656 Occasionally a file which would otherwise be called `source' (e.g. a
657 C `.h' file) is actually derived from some other file. Such files
658 should be listed in the `BUILT_SOURCES' variable.
660 Built sources are also not compiled by default. You must explicitly
661 mention them in some other `_SOURCES' variable for this to happen.
663 Note that, in some cases, `BUILT_SOURCES' will work in somewhat
664 surprising ways. In order to get the built sources to work with
665 automatic dependency tracking, the `Makefile' must depend on
666 `$(BUILT_SOURCES)'. This can cause these sources to be rebuilt at what
667 might seem like funny times.
670 File: automake.info, Node: Other GNU Tools, Next: Documentation, Prev: Other objects, Up: Top
675 Since Automake is primarily intended to generate `Makefile.in's for
676 use in GNU programs, it tries hard to interoperate with other GNU tools.
680 * Emacs Lisp:: Emacs Lisp
687 File: automake.info, Node: Emacs Lisp, Next: gettext, Prev: Other GNU Tools, Up: Other GNU Tools
692 Automake provides some support for Emacs Lisp. The `LISP' primary
693 is used to hold a list of `.el' files. Possible prefixes for this
694 primary are `lisp_' and `noinst_'. Note that if `lisp_LISP' is
695 defined, then `configure.in' must run `AM_PATH_LISPDIR' (*note
698 By default Automake will byte-compile all Emacs Lisp source files
699 using the Emacs found by `AM_PATH_LISPDIR'. If you wish to avoid
700 byte-compiling, simply define the variable `ELCFILES' to be empty.
701 Byte-compiled Emacs Lisp files are not portable among all versions of
702 Emacs, so it makes sense to turn this off if you expect sites to have
703 more than one version of Emacs installed. Furthermore, many packages
704 don't actually benefit from byte-compilation. Still, we recommend that
705 you leave it enabled by default. It is probably better for sites with
706 strange setups to cope for themselves than to make the installation less
707 nice for everybody else.
710 File: automake.info, Node: gettext, Next: Guile, Prev: Emacs Lisp, Up: Other GNU Tools
715 If `AM_GNU_GETTEXT' is seen in `configure.in', then Automake turns
716 on support for GNU gettext, a message catalog system for
717 internationalization (*note GNU Gettext: (gettext)GNU Gettext.).
719 The `gettext' support in Automake requires the addition of two
720 subdirectories to the package, `intl' and `po'. Automake insures that
721 these directories exist and are mentioned in `SUBDIRS'.
723 Furthermore, Automake checks that the definition of `ALL_LINGUAS' in
724 `configure.in' corresponds to all the valid `.po' files, and nothing
728 File: automake.info, Node: Guile, Next: Libtool, Prev: gettext, Up: Other GNU Tools
733 Automake provides some automatic support for writing Guile modules.
734 Automake will turn on Guile support if the `AM_INIT_GUILE_MODULE' macro
735 is used in `configure.in'.
737 Right now Guile support just means that the `AM_INIT_GUILE_MODULE'
738 macro is understood to mean:
739 * `AM_INIT_AUTOMAKE' is run.
741 * `AC_CONFIG_AUX_DIR' is run, with a path of `..'.
743 As the Guile module code matures, no doubt the Automake support will
747 File: automake.info, Node: Libtool, Next: Java, Prev: Guile, Up: Other GNU Tools
752 Automake provides support for GNU Libtool (*note Introduction:
753 (libtool)Top.) with the `LTLIBRARIES' primary. *Note A Shared
757 File: automake.info, Node: Java, Prev: Libtool, Up: Other GNU Tools
762 Automake provides some minimal support for Java compilation with the
765 Any `.java' files listed in a `_JAVA' variable will be compiled with
766 `JAVAC' at build time. By default, `.class' files are not included in
769 Currently Automake enforces the restriction that only one `_JAVA'
770 primary can be used in a given `Makefile.am'. The reason for this
771 restriction is that, in general, it isn't possible to know which
772 `.class' files were generated from which `.java' files - so it would be
773 impossible to know which files to install where.
776 File: automake.info, Node: Documentation, Next: Install, Prev: Other GNU Tools, Up: Top
778 Building documentation
779 **********************
781 Currently Automake provides support for Texinfo and man pages.
786 * Man pages:: Man pages
789 File: automake.info, Node: Texinfo, Next: Man pages, Prev: Documentation, Up: Documentation
794 If the current directory contains Texinfo source, you must declare it
795 with the `TEXINFOS' primary. Generally Texinfo files are converted
796 into info, and thus the `info_TEXINFOS' macro is most commonly used
797 here. Note that any Texinfo source file must end in the `.texi' or
798 `.texinfo' extension.
800 If the `.texi' file `@include's `version.texi', then that file will
801 be automatically generated. The file `version.texi' defines three
802 Texinfo macros you can reference: `EDITION', `VERSION', and `UPDATED'.
803 The first two hold the version number of your package (but are kept
804 separate for clarity); the last is the date the primary file was last
805 modified. The `version.texi' support requires the `mdate-sh' program;
806 this program is supplied with Automake and automatically included when
807 `automake' is invoked with the `--add-missing' option.
809 Sometimes an info file actually depends on more than one `.texi'
810 file. For instance, in GNU Hello, `hello.texi' includes the file
811 `gpl.texi'. You can tell Automake about these dependencies using the
812 `TEXI_TEXINFOS' variable. Here is how GNU Hello does it:
814 info_TEXINFOS = hello.texi
815 hello_TEXINFOS = gpl.texi
817 By default, Automake requires the file `texinfo.tex' to appear in
818 the same directory as the Texinfo source. However, if you used
819 `AC_CONFIG_AUX_DIR' in `configure.in' (*note Finding `configure' Input:
820 (autoconf)Input.), then `texinfo.tex' is looked for there. Automake
821 supplies `texinfo.tex' if `--add-missing' is given.
823 If your package has Texinfo files in many directories, you can use
824 the variable `TEXINFO_TEX' to tell Automake where to find the canonical
825 `texinfo.tex' for your package. The value of this variable should be
826 the relative path from the current `Makefile.am' to `texinfo.tex':
828 TEXINFO_TEX = ../doc/texinfo.tex
830 The option `no-texinfo.tex' can be used to eliminate the requirement
831 for `texinfo.tex'. Use of the variable `TEXINFO_TEX' is preferable,
832 however, because that allows the `dvi' target to still work.
834 Automake generates an `install-info' target; some people apparently
835 use this. By default, info pages are installed by `make install'.
836 This can be prevented via the `no-installinfo' option.
839 File: automake.info, Node: Man pages, Prev: Texinfo, Up: Documentation
844 A package can also include man pages (but see the GNU standards on
845 this matter, *Note Man Pages: (standards)Man Pages.) Man pages are
846 declared using the `MANS' primary. Generally the `man_MANS' macro is
847 used. Man pages are automatically installed in the correct
848 subdirectory of `mandir', based on the file extension. They are not
849 automatically included in the distribution.
851 By default, man pages are installed by `make install'. However,
852 since the GNU project does not require man pages, many maintainers do
853 not expend effort to keep the man pages up to date. In these cases, the
854 `no-installman' option will prevent the man pages from being installed
855 by default. The user can still explicitly install them via `make
858 Here is how the documentation is handled in GNU `cpio' (which
859 includes both Texinfo documentation and man pages):
861 info_TEXINFOS = cpio.texi
862 man_MANS = cpio.1 mt.1
863 EXTRA_DIST = $(man_MANS)
865 Texinfo source and info pages are all considered to be source for the
866 purposes of making a distribution.
868 Man pages are not currently considered to be source, because it is
869 not uncommon for man pages to be automatically generated. For the same
870 reason, they are not automatically included in the distribution.
873 File: automake.info, Node: Install, Next: Clean, Prev: Documentation, Up: Top
878 Naturally, Automake handles the details of actually installing your
879 program once it has been built. All `PROGRAMS', `SCRIPTS',
880 `LIBRARIES', `LISP', `DATA' and `HEADERS' are automatically installed
881 in the appropriate places.
883 Automake also handles installing any specified info and man pages.
885 Automake generates separate `install-data' and `install-exec'
886 targets, in case the installer is installing on multiple machines which
887 share directory structure--these targets allow the machine-independent
888 parts to be installed only once. The `install' target depends on both
891 Automake also generates an `uninstall' target, an `installdirs'
892 target, and an `install-strip' target.
894 It is possible to extend this mechanism by defining an
895 `install-exec-local' or `install-data-local' target. If these targets
896 exist, they will be run at `make install' time.
898 Variables using the standard directory prefixes `data', `info',
899 `man', `include', `oldinclude', `pkgdata', or `pkginclude' (e.g.
900 `data_DATA') are installed by `install-data'.
902 Variables using the standard directory prefixes `bin', `sbin',
903 `libexec', `sysconf', `localstate', `lib', or `pkglib' (e.g.
904 `bin_PROGRAMS') are installed by `install-exec'.
906 Any variable using a user-defined directory prefix with `exec' in
907 the name (e.g. `myexecbin_PROGRAMS' is installed by `install-exec'.
908 All other user-defined prefixes are installed by `install-data'.
910 Automake generates support for the `DESTDIR' variable in all install
911 rules. `DESTDIR' is used during the `make install' step to relocate
912 install objects into a staging area. Each object and path is prefixed
913 with the value of `DESTDIR' before being copied into the install area.
914 Here is an example of typical DESTDIR usage:
916 make DESTDIR=/tmp/staging install
918 This places install objects in a directory tree built under
919 `/tmp/staging'. If `/gnu/bin/foo' and `/gnu/share/aclocal/foo.m4' are
920 to be installed, the above command would install
921 `/tmp/staging/gnu/bin/foo' and `/tmp/staging/gnu/share/aclocal/foo.m4'.
923 This feature is commonly used to build install images and packages.
924 For more information, see *Note Makefile Conventions:
925 (standards)Makefile Conventions.
928 File: automake.info, Node: Clean, Next: Dist, Prev: Install, Up: Top
933 The GNU Makefile Standards specify a number of different clean rules.
934 Generally the files that can be cleaned are determined automatically by
935 Automake. Of course, Automake also recognizes some variables that can
936 be defined to specify additional files to clean. These variables are
937 `MOSTLYCLEANFILES', `CLEANFILES', `DISTCLEANFILES', and
938 `MAINTAINERCLEANFILES'.
941 File: automake.info, Node: Dist, Next: Tests, Prev: Clean, Up: Top
943 What Goes in a Distribution
944 ***************************
946 The `dist' target in the generated `Makefile.in' can be used to
947 generate a gzip'd `tar' file for distribution. The tar file is named
948 based on the `PACKAGE' and `VERSION' variables; more precisely it is
949 named `PACKAGE-VERSION.tar.gz'. You can use the `make' variable
950 `GZIP_ENV' to control how gzip is run. The default setting is `--best'.
952 For the most part, the files to distribute are automatically found by
953 Automake: all source files are automatically included in a distribution,
954 as are all `Makefile.am's and `Makefile.in's. Automake also has a
955 built-in list of commonly used files which, if present in the current
956 directory, are automatically included. This list is printed by
957 `automake --help'. Also, files which are read by `configure' (i.e. the
958 source files corresponding to the files specified in the `AC_OUTPUT'
959 invocation) are automatically distributed.
961 Still, sometimes there are files which must be distributed, but which
962 are not covered in the automatic rules. These files should be listed in
963 the `EXTRA_DIST' variable. You can mention files from subdirectories
964 in `EXTRA_DIST'. You can also mention a directory there; in this case
965 the entire directory will be recursively copied into the distribution.
967 If you define `SUBDIRS', Automake will recursively include the
968 subdirectories in the distribution. If `SUBDIRS' is defined
969 conditionally (*note Conditionals::), Automake will normally include all
970 directories that could possibly appear in `SUBDIRS' in the
971 distribution. If you need to specify the set of directories
972 conditionally, you can set the variable `DIST_SUBDIRS' to the exact
973 list of subdirectories to include in the distribution.
975 Occasionally it is useful to be able to change the distribution
976 before it is packaged up. If the `dist-hook' target exists, it is run
977 after the distribution directory is filled, but before the actual tar
978 (or shar) file is created. One way to use this is for distributing
979 files in subdirectories for which a new `Makefile.am' is overkill:
982 mkdir $(distdir)/random
983 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
985 Automake also generates a `distcheck' target which can be help to
986 ensure that a given distribution will actually work. `distcheck' makes
987 a distribution, and then tries to do a `VPATH' build.
990 File: automake.info, Node: Tests, Next: Options, Prev: Dist, Up: Top
992 Support for test suites
993 ***********************
995 Automake supports two forms of test suites.
997 If the variable `TESTS' is defined, its value is taken to be a list
998 of programs to run in order to do the testing. The programs can either
999 be derived objects or source objects; the generated rule will look both
1000 in `srcdir' and `.'. Programs needing data files should look for them
1001 in `srcdir' (which is both an environment variable and a make variable)
1002 so they work when building in a separate directory (*note Build
1003 Directories: (autoconf)Build Directories.), and in particular for the
1004 `distcheck' target (*note Dist::).
1006 The number of failures will be printed at the end of the run. If a
1007 given test program exits with a status of 77, then its result is ignored
1008 in the final count. This feature allows non-portable tests to be
1009 ignored in environments where they don't make sense.
1011 The variable `TESTS_ENVIRONMENT' can be used to set environment
1012 variables for the test run; the environment variable `srcdir' is set in
1013 the rule. If all your test programs are scripts, you can also set
1014 `TESTS_ENVIRONMENT' to an invocation of the shell (e.g. `$(SHELL)
1015 -x'); this can be useful for debugging the tests.
1017 If `dejagnu' (ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz)
1018 appears in `AUTOMAKE_OPTIONS', then a `dejagnu'-based test suite is
1019 assumed. The value of the variable `DEJATOOL' is passed as the
1020 `--tool' argument to `runtest'; it defaults to the name of the package.
1022 The variable `RUNTESTDEFAULTFLAGS' holds the `--tool' and `--srcdir'
1023 flags that are passed to dejagnu by default; this can be overridden if
1026 The variables `EXPECT', `RUNTEST' and `RUNTESTFLAGS' can also be
1027 overridden to provide project-specific values. For instance, you will
1028 need to do this if you are testing a compiler toolchain, because the
1029 default values do not take into account host and target names.
1031 In either case, the testing is done via `make check'.
1034 File: automake.info, Node: Options, Next: Miscellaneous, Prev: Tests, Up: Top
1036 Changing Automake's Behavior
1037 ****************************
1039 Various features of Automake can be controlled by options in the
1040 `Makefile.am'. Such options are listed in a special variable named
1041 `AUTOMAKE_OPTIONS'. Currently understood options are:
1048 Set the strictness as appropriate. The `gnits' option also implies
1049 `readme-alpha' and `check-news'.
1053 Turn on automatic de-ANSI-fication. *Note ANSI::. If preceded by
1054 a path, the generated `Makefile.in' will look in the specified
1055 directory to find the `ansi2knr' program. Generally the path
1056 should be a relative path to another directory in the same
1057 distribution (though Automake currently does not check this).
1060 Cause `make dist' to fail unless the current version number appears
1061 in the first few lines of the `NEWS' file.
1064 Cause `dejagnu'-specific rules to be generated. *Note Tests::.
1067 Generate a `dist-shar' target as well as the ordinary `dist'
1068 target. This new target will create a shar archive of the
1072 Generate a `dist-zip' target as well as the ordinary `dist'
1073 target. This new target will create a zip archive of the
1077 Generate a `dist-tarZ' target as well as the ordinary `dist'
1078 target. This new target will create a compressed tar archive of
1079 the distribution; a traditional `tar' and `compress' will be
1080 assumed. Warning: if you are actually using `GNU tar', then the
1081 generated archive might contain nonportable constructs.
1084 This is similar to using `--include-deps' on the command line, but
1085 is useful for those situations where you don't have the necessary
1086 bits to make automatic dependency tracking work *Note
1087 Dependencies::. In this case the effect is to effectively disable
1088 automatic dependency tracking.
1091 The generated `Makefile.in' will not cause info pages to be built
1092 or installed by default. However, `info' and `install-info'
1093 targets will still be available. This option is disallowed at
1094 `GNU' strictness and above.
1097 The generated `Makefile.in' will not cause man pages to be
1098 installed by default. However, an `install-man' target will still
1099 be available for optional installation. This option is disallowed
1100 at `GNU' strictness and above.
1103 Don't require `texinfo.tex', even if there are texinfo files in
1107 If this release is an alpha release, and the file `README-alpha'
1108 exists, then it will be added to the distribution. If this option
1109 is given, version numbers are expected to follow one of two forms.
1110 The first form is `MAJOR.MINOR.ALPHA', where each element is a
1111 number; the final period and number should be left off for
1112 non-alpha releases. The second form is `MAJOR.MINORALPHA', where
1113 ALPHA is a letter; it should be omitted for non-alpha releases.
1116 A version number (e.g. `0.30') can be specified. If Automake is
1117 not newer than the version specified, creation of the `Makefile.in'
1120 Unrecognized options are diagnosed by `automake'.
1123 File: automake.info, Node: Miscellaneous, Next: Include, Prev: Options, Up: Top
1128 There are a few rules and variables that didn't fit anywhere else.
1132 * Tags:: Interfacing to etags and mkid
1133 * Suffixes:: Handling new file extensions
1136 File: automake.info, Node: Tags, Next: Suffixes, Prev: Miscellaneous, Up: Miscellaneous
1138 Interfacing to `etags'
1139 ======================
1141 Automake will generate rules to generate `TAGS' files for use with
1142 GNU Emacs under some circumstances.
1144 If any C, C++ or Fortran 77 source code or headers are present, then
1145 `tags' and `TAGS' targets will be generated for the directory.
1147 At the topmost directory of a multi-directory package, a `tags'
1148 target file will be generated which, when run, will generate a `TAGS'
1149 file that includes by reference all `TAGS' files from subdirectories.
1151 Also, if the variable `ETAGS_ARGS' is defined, a `tags' target will
1152 be generated. This variable is intended for use in directories which
1153 contain taggable source that `etags' does not understand.
1155 Here is how Automake generates tags for its source, and for nodes in
1158 ETAGS_ARGS = automake.in --lang=none \
1159 --regex='/^@node[ \t]+\([^,]+\)/\1/' automake.texi
1161 If you add filenames to `ETAGS_ARGS', you will probably also want to
1162 set `TAGS_DEPENDENCIES'. The contents of this variable are added
1163 directly to the dependencies for the `tags' target.
1165 Automake will also generate an `ID' target which will run `mkid' on
1166 the source. This is only supported on a directory-by-directory basis.
1169 File: automake.info, Node: Suffixes, Prev: Tags, Up: Miscellaneous
1171 Handling new file extensions
1172 ============================
1174 It is sometimes useful to introduce a new implicit rule to handle a
1175 file type that Automake does not know about. If this is done, you must
1176 notify GNU Make of the new suffixes. This can be done by putting a list
1177 of new suffixes in the `SUFFIXES' variable.
1179 For instance, currently Automake does not provide any Java support.
1180 If you wrote a macro to generate `.class' files from `.java' source
1181 files, you would also need to add these suffixes to the list:
1183 SUFFIXES = .java .class
1186 File: automake.info, Node: Include, Next: Conditionals, Prev: Miscellaneous, Up: Top
1191 To include another file (perhaps for common rules), the following
1192 syntax is supported:
1194 include ($(srcdir)|$(top_srcdir))/filename
1196 Using files in the current directory:
1197 include $(srcdir)/Makefile.extra
1199 include Makefile.generated
1201 Using a file in the top level directory:
1202 include $(top_srcdir)/filename
1205 File: automake.info, Node: Conditionals, Next: Gnits, Prev: Include, Up: Top
1210 Automake supports a simple type of conditionals.
1212 Before using a conditional, you must define it by using
1213 `AM_CONDITIONAL' in the `configure.in' file (*note Macros::). The
1214 `AM_CONDITIONAL' macro takes two arguments.
1216 The first argument to `AM_CONDITIONAL' is the name of the
1217 conditional. This should be a simple string starting with a letter and
1218 containing only letters, digits, and underscores.
1220 The second argument to `AM_CONDITIONAL' is a shell condition,
1221 suitable for use in a shell `if' statement. The condition is evaluated
1222 when `configure' is run.
1224 Conditionals typically depend upon options which the user provides to
1225 the `configure' script. Here is an example of how to write a
1226 conditional which is true if the user uses the `--enable-debug' option.
1228 AC_ARG_ENABLE(debug,
1229 [ --enable-debug Turn on debugging],
1230 [case "${enableval}" in
1233 *) AC_MSG_ERROR(bad value ${enableval} for --enable-debug) ;;
1234 esac],[debug=false])
1235 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
1237 Here is an example of how to use that conditional in `Makefile.am':
1244 noinst_PROGRAMS = $(DBG)
1246 This trivial example could also be handled using EXTRA_PROGRAMS
1247 (*note A Program::).
1249 You may only test a single variable in an `if' statement. The
1250 `else' statement may be omitted. Conditionals may be nested to any
1253 Note that conditionals in Automake are not the same as conditionals
1254 in GNU Make. Automake conditionals are checked at configure time by the
1255 `configure' script, and affect the translation from `Makefile.in' to
1256 `Makefile'. They are based on options passed to `configure' and on
1257 results that `configure' has discovered about the host system. GNU
1258 Make conditionals are checked at `make' time, and are based on
1259 variables passed to the make program or defined in the `Makefile'.
1261 Automake conditionals will work with any make program.