TIVI-153: Adding automake14 as dep for iputils package
[profile/ivi/automake14.git] / automake.info-2
1 This is automake.info, produced by makeinfo version 4.1 from
2 automake.texi.
3
4 INFO-DIR-SECTION GNU admin
5 START-INFO-DIR-ENTRY
6 * automake: (automake).         Making Makefile.in's
7 END-INFO-DIR-ENTRY
8
9 INFO-DIR-SECTION Individual utilities
10 START-INFO-DIR-ENTRY
11 * aclocal: (automake)Invoking aclocal.          Generating aclocal.m4
12 END-INFO-DIR-ENTRY
13
14    This file documents GNU automake 1.4-p6
15
16    Copyright (C) 1995, 96, 97, 98 Free Software Foundation, Inc.
17
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.
21
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.
26
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.
31
32 \1f
33 File: automake.info,  Node: A Shared Library,  Next: Program variables,  Prev: LIBOBJS,  Up: Programs
34
35 Building a Shared Library
36 =========================
37
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.
41
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
46 in `libdir', write:
47
48      lib_LTLIBRARIES = libgettext.la
49
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
53 libraries".
54
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'.
59
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.
64
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.
71
72    *Note Using Automake with Libtool: (libtool)Using Automake, for more
73 information.
74
75 \1f
76 File: automake.info,  Node: Program variables,  Next: Yacc and Lex,  Prev: A Shared Library,  Up: Programs
77
78 Variables used when building a program
79 ======================================
80
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.
84
85    Some variables are inherited from Autoconf; these are `CC',
86 `CFLAGS', `CPPFLAGS', `DEFS', `LDFLAGS', and `LIBS'.
87
88    There are some additional variables which Automake itself defines:
89
90 `INCLUDES'
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
96      `AM_CONFIG_HEADER').
97
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.
101
102 `COMPILE'
103      This is the command used to actually compile a C source file.  The
104      filename is appended to form the complete command line.
105
106 `LINK'
107      This is the command used to actually link a C program.
108
109 \1f
110 File: automake.info,  Node: Yacc and Lex,  Next: C++ Support,  Prev: Program variables,  Up: Programs
111
112 Yacc and Lex support
113 ====================
114
115    Automake has somewhat idiosyncratic support for Yacc and Lex.
116
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).
121
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'.
126
127    Likewise, lex source files can be used to generate `C' or `C++'; the
128 extensions `.l', `.ll', `.l++', and `.lxx' are recognized.
129
130    You should never explicitly mention the intermediate (`C' or `C++')
131 file in any `SOURCES' variable; only list the source file.
132
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'.
136
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.).
141
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::).
148
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'.
158
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.
162
163    We recommend using the following renaming hack used in `gdb':
164      #define    yymaxdepth c_maxdepth
165      #define    yyparse c_parse
166      #define    yylex   c_lex
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
172      #define    yyr1    c_r1
173      #define    yyr2    c_r2
174      #define    yydef   c_def
175      #define    yychk   c_chk
176      #define    yypgo   c_pgo
177      #define    yyact   c_act
178      #define    yyexca  c_exca
179      #define yyerrflag c_errflag
180      #define yynerrs    c_nerrs
181      #define    yyps    c_ps
182      #define    yypv    c_pv
183      #define    yys     c_s
184      #define    yy_yys  c_yys
185      #define    yystate c_state
186      #define    yytmp   c_tmp
187      #define    yyv     c_v
188      #define    yy_yyv  c_yyv
189      #define    yyval   c_val
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
204
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.
209
210 \1f
211 File: automake.info,  Node: C++ Support,  Next: Fortran 77 Support,  Prev: Yacc and Lex,  Up: Programs
212
213 C++ Support
214 ===========
215
216    Automake includes full support for C++.
217
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.).
222
223    A few additional variables are defined when a C++ source file is
224 seen:
225
226 `CXX'
227      The name of the C++ compiler.
228
229 `CXXFLAGS'
230      Any flags to pass to the C++ compiler.
231
232 `CXXCOMPILE'
233      The command used to actually compile a C++ source file.  The file
234      name is appended to form the complete command line.
235
236 `CXXLINK'
237      The command used to actually link a C++ program.
238
239 \1f
240 File: automake.info,  Node: Fortran 77 Support,  Next: Support for Other Languages,  Prev: C++ Support,  Up: Programs
241
242 Fortran 77 Support
243 ==================
244
245    Automake includes full support for Fortran 77.
246
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::.
251
252    A few additional variables are defined when a Fortran 77 source file
253 is seen:
254
255 `F77'
256      The name of the Fortran 77 compiler.
257
258 `FFLAGS'
259      Any flags to pass to the Fortran 77 compiler.
260
261 `RFLAGS'
262      Any flags to pass to the Ratfor compiler.
263
264 `F77COMPILE'
265      The command used to actually compile a Fortran 77 source file.
266      The file name is appended to form the complete command line.
267
268 `FLINK'
269      The command used to actually link a pure Fortran 77 program or
270      shared library.
271
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
276 C++::).
277
278    These issues are covered in the following sections.
279
280 * Menu:
281
282 * Preprocessing Fortran 77::
283 * Compiling Fortran 77 Files::
284 * Mixing Fortran 77 With C and C++::
285 * Fortran 77 and Autoconf::
286
287    ---------- Footnotes ----------
288
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.
292
293 \1f
294 File: automake.info,  Node: Preprocessing Fortran 77,  Next: Compiling Fortran 77 Files,  Prev: Fortran 77 Support,  Up: Fortran 77 Support
295
296 Preprocessing Fortran 77
297 ------------------------
298
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
302 used is as follows:
303
304 `.F'
305      `$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
306      $(AM_FFLAGS) $(FFLAGS)'
307
308 `.r'
309      `$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)'
310
311 \1f
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
313
314 Compiling Fortran 77 Files
315 --------------------------
316
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:
319
320 `.f'
321      `$(F77) -c $(AM_FFLAGS) $(FFLAGS)'
322
323 `.F'
324      `$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
325      $(AM_FFLAGS) $(FFLAGS)'
326
327 `.r'
328      `$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)'
329
330 \1f
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
332
333 Mixing Fortran 77 With C and C++
334 --------------------------------
335
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).
341
342    Automake can help in two ways:
343
344   1. Automatic selection of the linker depending on which combinations
345      of source code.
346
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.
350
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.
356
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
365 `_LIBADD' variable.
366
367    For example, consider the following `Makefile.am':
368
369      bin_PROGRAMS = foo
370      foo_SOURCES  = main.cc foo.f
371      foo_LDADD    = libfoo.la @FLIBS@
372      
373      pkglib_LTLIBRARIES = libfoo.la
374      libfoo_la_SOURCES  = bar.f baz.c zardoz.cc
375      libfoo_la_LIBADD   = $(FLIBS)
376
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
380 a warning.
381
382 * Menu:
383
384 * How the Linker is Chosen::
385
386    ---------- Footnotes ----------
387
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.
393
394 \1f
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++
396
397 How the Linker is Chosen
398 ........................
399
400    The following diagram demonstrates under what conditions a particular
401 linker is chosen by Automake.
402
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'.
408
409                           \              Linker
410                source      \
411                 code        \     C        C++     Fortran
412           -----------------  +---------+---------+---------+
413                              |         |         |         |
414           C                  |    x    |         |         |
415                              |         |         |         |
416                              +---------+---------+---------+
417                              |         |         |         |
418               C++            |         |    x    |         |
419                              |         |         |         |
420                              +---------+---------+---------+
421                              |         |         |         |
422                     Fortran  |         |         |    x    |
423                              |         |         |         |
424                              +---------+---------+---------+
425                              |         |         |         |
426           C + C++            |         |    x    |         |
427                              |         |         |         |
428                              +---------+---------+---------+
429                              |         |         |         |
430           C +       Fortran  |         |         |    x    |
431                              |         |         |         |
432                              +---------+---------+---------+
433                              |         |         |         |
434               C++ + Fortran  |         |    x    |         |
435                              |         |         |         |
436                              +---------+---------+---------+
437                              |         |         |         |
438           C + C++ + Fortran  |         |    x    |         |
439                              |         |         |         |
440                              +---------+---------+---------+
441
442 \1f
443 File: automake.info,  Node: Fortran 77 and Autoconf,  Prev: Mixing Fortran 77 With C and C++,  Up: Fortran 77 Support
444
445 Fortran 77 and Autoconf
446 -----------------------
447
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.
452
453 \1f
454 File: automake.info,  Node: Support for Other Languages,  Next: ANSI,  Prev: Fortran 77 Support,  Up: Programs
455
456 Support for Other Languages
457 ===========================
458
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.
463
464 \1f
465 File: automake.info,  Node: ANSI,  Next: Dependencies,  Prev: Support for Other Languages,  Up: Programs
466
467 Automatic de-ANSI-fication
468 ==========================
469
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
472 (notably SunOS).
473
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
476 place.
477
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'.
481
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.
486
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
489 details.
490
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::).
495
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':
502
503      AUTOMAKE_OPTIONS = ../lib/ansi2knr
504
505    If no directory prefix is given, the files are assumed to be in the
506 current directory.
507
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:
514
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/'`
518
519 \1f
520 File: automake.info,  Node: Dependencies,  Prev: ANSI,  Up: Programs
521
522 Automatic dependency tracking
523 =============================
524
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'.
529
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
535 from non-GNU make.
536
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
544 get errors.
545
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.
554
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.
558
559    Automatic dependency tracking can be suppressed by putting
560 `no-dependencies' in the variable `AUTOMAKE_OPTIONS'.
561
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'.
564
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.
569
570 \1f
571 File: automake.info,  Node: Other objects,  Next: Other GNU Tools,  Prev: Programs,  Up: Top
572
573 Other Derived Objects
574 *********************
575
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.
580
581 * Menu:
582
583 * Scripts::                     Executable scripts
584 * Headers::                     Header files
585 * Data::                        Architecture-independent data files
586 * Sources::                     Derived sources
587
588 \1f
589 File: automake.info,  Node: Scripts,  Next: Headers,  Prev: Other objects,  Up: Other objects
590
591 Executable Scripts
592 ==================
593
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.
598
599    Automake does not assume that scripts are derived objects; such
600 objects must be deleted by hand (*note Clean::).
601
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:
604
605      bin_SCRIPTS = automake
606
607    Since `automake' appears in the `AC_OUTPUT' macro, a target for it
608 is automatically generated.
609
610    Script objects can be installed in `bindir', `sbindir',
611 `libexecdir', or `pkgdatadir'.
612
613 \1f
614 File: automake.info,  Node: Headers,  Next: Data,  Prev: Scripts,  Up: Other objects
615
616 Header files
617 ============
618
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.
622
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
627 `_HEADERS' variable.
628
629    Headers can be installed in `includedir', `oldincludedir', or
630 `pkgincludedir'.
631
632 \1f
633 File: automake.info,  Node: Data,  Next: Sources,  Prev: Headers,  Up: Other objects
634
635 Architecture-independent data files
636 ===================================
637
638    Automake supports the installation of miscellaneous data files using
639 the `DATA' family of variables.
640
641    Such data can be installed in the directories `datadir',
642 `sysconfdir', `sharedstatedir', `localstatedir', or `pkgdatadir'.
643
644    By default, data files are _not_ included in a distribution.
645
646    Here is how Automake installs its auxiliary data files:
647
648      pkgdata_DATA = clean-kr.am clean.am ...
649
650 \1f
651 File: automake.info,  Node: Sources,  Prev: Data,  Up: Other objects
652
653 Built sources
654 =============
655
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.
659
660    Built sources are also not compiled by default.  You must explicitly
661 mention them in some other `_SOURCES' variable for this to happen.
662
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.
668
669 \1f
670 File: automake.info,  Node: Other GNU Tools,  Next: Documentation,  Prev: Other objects,  Up: Top
671
672 Other GNU Tools
673 ***************
674
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.
677
678 * Menu:
679
680 * Emacs Lisp::                  Emacs Lisp
681 * gettext::                     Gettext
682 * Guile::                       Guile
683 * Libtool::                     Libtool
684 * Java::                        Java
685
686 \1f
687 File: automake.info,  Node: Emacs Lisp,  Next: gettext,  Prev: Other GNU Tools,  Up: Other GNU Tools
688
689 Emacs Lisp
690 ==========
691
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
696 Macros::).
697
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.
708
709 \1f
710 File: automake.info,  Node: gettext,  Next: Guile,  Prev: Emacs Lisp,  Up: Other GNU Tools
711
712 Gettext
713 =======
714
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.).
718
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'.
722
723    Furthermore, Automake checks that the definition of `ALL_LINGUAS' in
724 `configure.in' corresponds to all the valid `.po' files, and nothing
725 more.
726
727 \1f
728 File: automake.info,  Node: Guile,  Next: Libtool,  Prev: gettext,  Up: Other GNU Tools
729
730 Guile
731 =====
732
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'.
736
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.
740
741    * `AC_CONFIG_AUX_DIR' is run, with a path of `..'.
742
743    As the Guile module code matures, no doubt the Automake support will
744 grow as well.
745
746 \1f
747 File: automake.info,  Node: Libtool,  Next: Java,  Prev: Guile,  Up: Other GNU Tools
748
749 Libtool
750 =======
751
752    Automake provides support for GNU Libtool (*note Introduction:
753 (libtool)Top.) with the `LTLIBRARIES' primary.  *Note A Shared
754 Library::.
755
756 \1f
757 File: automake.info,  Node: Java,  Prev: Libtool,  Up: Other GNU Tools
758
759 Java
760 ====
761
762    Automake provides some minimal support for Java compilation with the
763 `JAVA' primary.
764
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
767 the distribution.
768
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.
774
775 \1f
776 File: automake.info,  Node: Documentation,  Next: Install,  Prev: Other GNU Tools,  Up: Top
777
778 Building documentation
779 **********************
780
781    Currently Automake provides support for Texinfo and man pages.
782
783 * Menu:
784
785 * Texinfo::                     Texinfo
786 * Man pages::                   Man pages
787
788 \1f
789 File: automake.info,  Node: Texinfo,  Next: Man pages,  Prev: Documentation,  Up: Documentation
790
791 Texinfo
792 =======
793
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.
799
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.
808
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:
813
814      info_TEXINFOS = hello.texi
815      hello_TEXINFOS = gpl.texi
816
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.
822
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':
827
828      TEXINFO_TEX = ../doc/texinfo.tex
829
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.
833
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.
837
838 \1f
839 File: automake.info,  Node: Man pages,  Prev: Texinfo,  Up: Documentation
840
841 Man pages
842 =========
843
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.
850
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
856 install-man'.
857
858    Here is how the documentation is handled in GNU `cpio' (which
859 includes both Texinfo documentation and man pages):
860
861      info_TEXINFOS = cpio.texi
862      man_MANS = cpio.1 mt.1
863      EXTRA_DIST = $(man_MANS)
864
865    Texinfo source and info pages are all considered to be source for the
866 purposes of making a distribution.
867
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.
871
872 \1f
873 File: automake.info,  Node: Install,  Next: Clean,  Prev: Documentation,  Up: Top
874
875 What Gets Installed
876 *******************
877
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.
882
883    Automake also handles installing any specified info and man pages.
884
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
889 of these targets.
890
891    Automake also generates an `uninstall' target, an `installdirs'
892 target, and an `install-strip' target.
893
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.
897
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'.
901
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'.
905
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'.
909
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:
915
916      make DESTDIR=/tmp/staging install
917
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'.
922
923    This feature is commonly used to build install images and packages.
924 For more information, see *Note Makefile Conventions:
925 (standards)Makefile Conventions.
926
927 \1f
928 File: automake.info,  Node: Clean,  Next: Dist,  Prev: Install,  Up: Top
929
930 What Gets Cleaned
931 *****************
932
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'.
939
940 \1f
941 File: automake.info,  Node: Dist,  Next: Tests,  Prev: Clean,  Up: Top
942
943 What Goes in a Distribution
944 ***************************
945
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'.
951
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.
960
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.
966
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.
974
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:
980
981      dist-hook:
982              mkdir $(distdir)/random
983              cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
984
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.
988
989 \1f
990 File: automake.info,  Node: Tests,  Next: Options,  Prev: Dist,  Up: Top
991
992 Support for test suites
993 ***********************
994
995    Automake supports two forms of test suites.
996
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::).
1005
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.
1010
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.
1016
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.
1021
1022    The variable `RUNTESTDEFAULTFLAGS' holds the `--tool' and `--srcdir'
1023 flags that are passed to dejagnu by default; this can be overridden if
1024 necessary.
1025
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.
1030
1031    In either case, the testing is done via `make check'.
1032
1033 \1f
1034 File: automake.info,  Node: Options,  Next: Miscellaneous,  Prev: Tests,  Up: Top
1035
1036 Changing Automake's Behavior
1037 ****************************
1038
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:
1042
1043 `gnits'
1044 `gnu'
1045 `foreign'
1046
1047 `cygnus'
1048      Set the strictness as appropriate.  The `gnits' option also implies
1049      `readme-alpha' and `check-news'.
1050
1051 `ansi2knr'
1052 `path/ansi2knr'
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).
1058
1059 `check-news'
1060      Cause `make dist' to fail unless the current version number appears
1061      in the first few lines of the `NEWS' file.
1062
1063 `dejagnu'
1064      Cause `dejagnu'-specific rules to be generated.  *Note Tests::.
1065
1066 `dist-shar'
1067      Generate a `dist-shar' target as well as the ordinary `dist'
1068      target.  This new target will create a shar archive of the
1069      distribution.
1070
1071 `dist-zip'
1072      Generate a `dist-zip' target as well as the ordinary `dist'
1073      target.  This new target will create a zip archive of the
1074      distribution.
1075
1076 `dist-tarZ'
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.
1082
1083 `no-dependencies'
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.
1089
1090 `no-installinfo'
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.
1095
1096 `no-installman'
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.
1101
1102 `no-texinfo.tex'
1103      Don't require `texinfo.tex', even if there are texinfo files in
1104      this directory.
1105
1106 `readme-alpha'
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.
1114
1115 VERSION
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'
1118      will be suppressed.
1119
1120    Unrecognized options are diagnosed by `automake'.
1121
1122 \1f
1123 File: automake.info,  Node: Miscellaneous,  Next: Include,  Prev: Options,  Up: Top
1124
1125 Miscellaneous Rules
1126 *******************
1127
1128    There are a few rules and variables that didn't fit anywhere else.
1129
1130 * Menu:
1131
1132 * Tags::                        Interfacing to etags and mkid
1133 * Suffixes::                    Handling new file extensions
1134
1135 \1f
1136 File: automake.info,  Node: Tags,  Next: Suffixes,  Prev: Miscellaneous,  Up: Miscellaneous
1137
1138 Interfacing to `etags'
1139 ======================
1140
1141    Automake will generate rules to generate `TAGS' files for use with
1142 GNU Emacs under some circumstances.
1143
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.
1146
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.
1150
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.
1154
1155    Here is how Automake generates tags for its source, and for nodes in
1156 its Texinfo file:
1157
1158      ETAGS_ARGS = automake.in --lang=none \
1159       --regex='/^@node[ \t]+\([^,]+\)/\1/' automake.texi
1160
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.
1164
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.
1167
1168 \1f
1169 File: automake.info,  Node: Suffixes,  Prev: Tags,  Up: Miscellaneous
1170
1171 Handling new file extensions
1172 ============================
1173
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.
1178
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:
1182
1183      SUFFIXES = .java .class
1184
1185 \1f
1186 File: automake.info,  Node: Include,  Next: Conditionals,  Prev: Miscellaneous,  Up: Top
1187
1188 Include
1189 *******
1190
1191    To include another file (perhaps for common rules), the following
1192 syntax is supported:
1193
1194    include ($(srcdir)|$(top_srcdir))/filename
1195
1196    Using files in the current directory:
1197      include $(srcdir)/Makefile.extra
1198
1199      include Makefile.generated
1200
1201    Using a file in the top level directory:
1202      include $(top_srcdir)/filename
1203
1204 \1f
1205 File: automake.info,  Node: Conditionals,  Next: Gnits,  Prev: Include,  Up: Top
1206
1207 Conditionals
1208 ************
1209
1210    Automake supports a simple type of conditionals.
1211
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.
1215
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.
1219
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.
1223
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.
1227
1228      AC_ARG_ENABLE(debug,
1229      [  --enable-debug    Turn on debugging],
1230      [case "${enableval}" in
1231        yes) debug=true ;;
1232        no)  debug=false ;;
1233        *) AC_MSG_ERROR(bad value ${enableval} for --enable-debug) ;;
1234      esac],[debug=false])
1235      AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
1236
1237    Here is an example of how to use that conditional in `Makefile.am':
1238
1239      if DEBUG
1240      DBG = debug
1241      else
1242      DBG =
1243      endif
1244      noinst_PROGRAMS = $(DBG)
1245
1246    This trivial example could also be handled using EXTRA_PROGRAMS
1247 (*note A Program::).
1248
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
1251 depth.
1252
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'.
1260
1261    Automake conditionals will work with any make program.
1262