This is automake.info, produced by makeinfo version 4.2 from automake.texi. INFO-DIR-SECTION GNU programming tools START-INFO-DIR-ENTRY * automake: (automake). Making Makefile.in's END-INFO-DIR-ENTRY INFO-DIR-SECTION Individual utilities START-INFO-DIR-ENTRY * aclocal: (automake)Invoking aclocal. Generating aclocal.m4 END-INFO-DIR-ENTRY This file documents GNU automake 1.6.3 Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.  File: automake.info, Node: Top level, Next: Alternative, Prev: configure, Up: Top The top-level `Makefile.am' *************************** In packages with subdirectories, the top level `Makefile.am' must tell Automake which subdirectories are to be built. This is done via the `SUBDIRS' variable. The `SUBDIRS' macro holds a list of subdirectories in which building of various sorts can occur. Many targets (e.g. `all') in the generated `Makefile' will run both locally and in all specified subdirectories. Note that the directories listed in `SUBDIRS' are not required to contain `Makefile.am's; only `Makefile's (after configuration). This allows inclusion of libraries from packages which do not use Automake (such as `gettext'). The directories mentioned in `SUBDIRS' must be direct children of the current directory. For instance, you cannot put `src/subdir' into `SUBDIRS'. In packages that use subdirectories, the top-level `Makefile.am' is often very short. For instance, here is the `Makefile.am' from the GNU Hello distribution: EXTRA_DIST = BUGS ChangeLog.O README-alpha SUBDIRS = doc intl po src tests It is possible to override the `SUBDIRS' variable if, like in the case of GNU `Inetutils', you want to only build a subset of the entire package. In your `Makefile.am' include: SUBDIRS = @MY_SUBDIRS@ Then in your `configure.in' you can specify: MY_SUBDIRS="src doc lib po" AC_SUBST(MY_SUBDIRS) (Note that we don't use the variable name `SUBDIRS' in our `configure.in'; that would cause Automake to believe that every `Makefile.in' should recurse into the listed subdirectories.) The upshot of this is that Automake is tricked into building the package to take the subdirs, but doesn't actually bind that list until `configure' is run. Although the `SUBDIRS' macro can contain configure substitutions (e.g. `@DIRS@'); Automake itself does not actually examine the contents of this variable. If `SUBDIRS' is defined, then your `configure.in' must include `AC_PROG_MAKE_SET'. When Automake invokes `make' in a subdirectory, it uses the value of the `MAKE' variable. It passes the value of the variable `AM_MAKEFLAGS' to the `make' invocation; this can be set in `Makefile.am' if there are flags you must always pass to `make'. The use of `SUBDIRS' is not restricted to just the top-level `Makefile.am'. Automake can be used to construct packages of arbitrary depth. By default, Automake generates `Makefiles' which work depth-first (`postfix'). However, it is possible to change this ordering. You can do this by putting `.' into `SUBDIRS'. For instance, putting `.' first will cause a `prefix' ordering of directories. All `clean' targets are run in reverse order of build targets. Sometimes, such as when running `make dist', you want all possible subdirectories to be examined. In this case Automake will use `DIST_SUBDIRS', instead of `SUBDIRS', to determine where to recurse. This variable will also be used when the user runs `distclean' or `maintainer-clean'. It should be set to the full list of subdirectories in the project. If this macro is not set, Automake will attempt to set it for you.  File: automake.info, Node: Alternative, Next: Rebuilding, Prev: Top level, Up: Top An Alternative Approach to Subdirectories ***************************************** If you've ever read Peter Miller's excellent paper, Recursive Make Considered Harmful (http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html), the preceding section on the use of subdirectories will probably come as unwelcome advice. For those who haven't read the paper, Miller's main thesis is that recursive `make' invocations are both slow and error-prone. Automake provides sufficient cross-directory support (1) to enable you to write a single `Makefile.am' for a complex multi-directory package. By default an installable file specified in a subdirectory will have its directory name stripped before installation. For instance, in this example, the header file will be installed as `$(includedir)/stdio.h': include_HEADERS = inc/stdio.h However, the `nobase_' prefix can be used to circumvent this path stripping. In this example, the header file will be installed as `$(includedir)/sys/types.h': nobase_include_HEADERS = sys/types.h `nobase_' should be specified first when used in conjonction with either `dist_' or `nodist_' (*note Dist::). For instance: nobase_dist_pkgdata_DATA = images/vortex.pgm ---------- Footnotes ---------- (1) We believe. This work is new and there are probably warts. *Note Introduction::, for information on reporting bugs.  File: automake.info, Node: Rebuilding, Next: Programs, Prev: Alternative, Up: Top Rebuilding Makefiles ******************** Automake generates rules to automatically rebuild `Makefile's, `configure', and other derived files like `Makefile.in'. If you are using `AM_MAINTAINER_MODE' in `configure.in', then these automatic rebuilding rules are only enabled in maintainer mode. Sometimes you need to run `aclocal' with an argument like `-I' to tell it where to find `.m4' files. Since sometimes `make' will automatically run `aclocal', you need a way to specify these arguments. You can do this by defining `ACLOCAL_AMFLAGS'; this holds arguments which are passed verbatim to `aclocal'. This macro is only useful in the top-level `Makefile.am'.  File: automake.info, Node: Programs, Next: Other objects, Prev: Rebuilding, Up: Top Building Programs and Libraries ******************************* A large part of Automake's functionality is dedicated to making it easy to build programs and libraries. * Menu: * A Program:: Building a program * A Library:: Building a library * A Shared Library:: Building a Libtool library * Program and Library Variables:: Variables controlling program and library builds * LIBOBJS:: Special handling for LIBOBJS and ALLOCA * Program variables:: Variables used when building a program * Yacc and Lex:: Yacc and Lex support * C++ Support:: * Assembly Support:: * Fortran 77 Support:: * Java Support:: * Support for Other Languages:: * ANSI:: Automatic de-ANSI-fication * Dependencies:: Automatic dependency tracking * EXEEXT:: Support for executable extensions  File: automake.info, Node: A Program, Next: A Library, Prev: Programs, Up: Programs Building a program ================== In order to build a program, you need to tell Automake which sources are part of it, and which libraries it should be linked with. This section also covers conditional compilation of sources or programs. Most of the comments about these also apply to libraries (*note A Library::) and Libtool libraries (*note A Shared Library::). * Menu: * Program Sources:: Defining program sources * Linking:: Linking with libraries or extra objects * Conditional Sources:: Handling conditional sources * Conditional Programs:: Building program conditionally  File: automake.info, Node: Program Sources, Next: Linking, Prev: A Program, Up: A Program Defining program sources ------------------------ In a directory containing source that gets built into a program (as opposed to a library or a script), the `PROGRAMS' primary is used. Programs can be installed in `bindir', `sbindir', `libexecdir', `pkglibdir', or not at all (`noinst'). They can also be built only for `make check', in which case the prefix is `check'. For instance: bin_PROGRAMS = hello In this simple case, the resulting `Makefile.in' will contain code to generate a program named `hello'. Associated with each program are several assisting variables which are named after the program. These variables are all optional, and have reasonable defaults. Each variable, its use, and default is spelled out below; we use the "hello" example throughout. The variable `hello_SOURCES' is used to specify which source files get built into an executable: hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h This causes each mentioned `.c' file to be compiled into the corresponding `.o'. Then all are linked to produce `hello'. If `hello_SOURCES' is not specified, then it defaults to the single file `hello.c'; that is, the default is to compile a single C file whose base name is the name of the program itself. (This is a terrible default but we are stuck with it for historical reasons.) Multiple programs can be built in a single directory. Multiple programs can share a single source file, which must be listed in each `_SOURCES' definition. Header files listed in a `_SOURCES' definition will be included in the distribution but otherwise ignored. In case it isn't obvious, you should not include the header file generated by `configure' in a `_SOURCES' variable; this file should not be distributed. Lex (`.l') and Yacc (`.y') files can also be listed; see *Note Yacc and Lex::.  File: automake.info, Node: Linking, Next: Conditional Sources, Prev: Program Sources, Up: A Program Linking the program ------------------- If you need to link against libraries that are not found by `configure', you can use `LDADD' to do so. This variable is used to specify additional objects or libraries to link with; it is inappropriate for specifying specific linker flags, you should use `AM_LDFLAGS' for this purpose. Sometimes, multiple programs are built in one directory but do not share the same link-time requirements. In this case, you can use the `PROG_LDADD' variable (where PROG is the name of the program as it appears in some `_PROGRAMS' variable, and usually written in lowercase) to override the global `LDADD'. If this variable exists for a given program, then that program is not linked using `LDADD'. For instance, in GNU cpio, `pax', `cpio' and `mt' are linked against the library `libcpio.a'. However, `rmt' is built in the same directory, and has no such link requirement. Also, `mt' and `rmt' are only built on certain architectures. Here is what cpio's `src/Makefile.am' looks like (abridged): bin_PROGRAMS = cpio pax @MT@ libexec_PROGRAMS = @RMT@ EXTRA_PROGRAMS = mt rmt LDADD = ../lib/libcpio.a @INTLLIBS@ rmt_LDADD = cpio_SOURCES = ... pax_SOURCES = ... mt_SOURCES = ... rmt_SOURCES = ... `PROG_LDADD' is inappropriate for passing program-specific linker flags (except for `-l', `-L', `-dlopen' and `-dlpreopen'). So, use the `PROG_LDFLAGS' variable for this purpose. It is also occasionally useful to have a program depend on some other target which is not actually part of that program. This can be done using the `PROG_DEPENDENCIES' variable. Each program depends on the contents of such a variable, but no further interpretation is done. If `PROG_DEPENDENCIES' is not supplied, it is computed by Automake. The automatically-assigned value is the contents of `PROG_LDADD', with most configure substitutions, `-l', `-L', `-dlopen' and `-dlpreopen' options removed. The configure substitutions that are left in are only `@LIBOBJS@' and `@ALLOCA@'; these are left because it is known that they will not cause an invalid value for `PROG_DEPENDENCIES' to be generated.  File: automake.info, Node: Conditional Sources, Next: Conditional Programs, Prev: Linking, Up: A Program Conditional compilation of sources ---------------------------------- You can't put a configure substitution (e.g., `@FOO@') into a `_SOURCES' variable. The reason for this is a bit hard to explain, but suffice to say that it simply won't work. Automake will give an error if you try to do this. Fortunatly there are two other ways to achieve the same result. One is to use configure substitutions in `_LDADD' variables, the other is to use an Automake conditional. Conditional compilation using `_LDADD' substitutions .................................................... Automake must know all the source files that could possibly go into a program, even if not all the files are built in every circumstance. Any files which are only conditionally built should be listed in the appropriate `EXTRA_' variable. For instance, if `hello-linux.c' or `hello-generic.c' were conditionally included in `hello', the `Makefile.am' would contain: bin_PROGRAMS = hello hello_SOURCES = hello-common.c EXTRA_hello_SOURCES = hello-linux.c hello-generic.c hello_LDADD = @HELLO_SYSTEM@ hello_DEPENDENCIES = @HELLO_SYSTEM@ You can then setup the `@HELLO_SYSTEM@' substitution from `configure.in': ... case $host in *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;; *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;; esac AC_SUBST([HELLO_SYSTEM]) ... In this case, `HELLO_SYSTEM' should be replaced by `hello-linux.o' or `hello-bsd.o', and added to `hello_DEPENDENCIES' and `hello_LDADD' in order to be built and linked in. Conditional compilation using Automake conditionals ................................................... An often simpler way to compile source files conditionally is to use Automake conditionals. For instance, you could use this `Makefile.am' construct to build the same `hello' example: bin_PROGRAMS = hello if LINUX hello_SOURCES = hello-linux.c hello-common.c else hello_SOURCES = hello-generic.c hello-common.c endif In this case, your `configure.in' should setup the `LINUX' conditional using `AM_CONDITIONAL' (*note Conditionals::). When using conditionals like this you don't need to use the `EXTRA_' variable, because Automake will examine the contents of each variable to construct the complete list of source files. If your program uses a lot of files, you will probably prefer to use an intermediate variable to hold conditional sources. bin_PROGRAMS = hello if LINUX hello_cond = hello-linux.c else hello_cond = hello-generic.c endif hello_SOURCES = hello-common.c $(hello_cond)  File: automake.info, Node: Conditional Programs, Prev: Conditional Sources, Up: A Program Conditional compilation of programs ----------------------------------- Sometimes it is useful to determine the programs that are to be built at configure time. For instance, GNU `cpio' only builds `mt' and `rmt' under special circumstances. In this case, you must notify Automake of all the programs that can possibly be built, but at the same time cause the generated `Makefile.in' to use the programs specified by `configure'. This is done by having `configure' substitute values into each `_PROGRAMS' definition, while listing all optionally built programs in `EXTRA_PROGRAMS'. Of course you can use Automake conditionals to determine the programs to be built.  File: automake.info, Node: A Library, Next: A Shared Library, Prev: A Program, Up: Programs Building a library ================== Building a library is much like building a program. In this case, the name of the primary is `LIBRARIES'. Libraries can be installed in `libdir' or `pkglibdir'. *Note A Shared Library::, for information on how to build shared libraries using Libtool and the `LTLIBRARIES' primary. Each `_LIBRARIES' variable is a list of the libraries to be built. For instance to create a library named `libcpio.a', but not install it, you would write: noinst_LIBRARIES = libcpio.a The sources that go into a library are determined exactly as they are for programs, via the `_SOURCES' variables. Note that the library name is canonicalized (*note Canonicalization::), so the `_SOURCES' variable corresponding to `liblob.a' is `liblob_a_SOURCES', not `liblob.a_SOURCES'. Extra objects can be added to a library using the `LIBRARY_LIBADD' variable. This should be used for objects determined by `configure'. Again from `cpio': libcpio_a_LIBADD = @LIBOBJS@ @ALLOCA@ In addition, sources for extra objects that will not exist until configure-time must be added to the `BUILT_SOURCES' variable (*note Sources::).  File: automake.info, Node: A Shared Library, Next: Program and Library Variables, Prev: A Library, Up: Programs Building a Shared Library ========================= Building shared libraries is a relatively complex matter. For this reason, GNU Libtool (*note Introduction: (libtool)Top.) was created to help build shared libraries in a platform-independent way. Automake uses Libtool to build libraries declared with the `LTLIBRARIES' primary. Each `_LTLIBRARIES' variable is a list of shared libraries to build. For instance, to create a library named `libgettext.a' and its corresponding shared libraries, and install them in `libdir', write: lib_LTLIBRARIES = libgettext.la Note that shared libraries _must_ be installed in order to work properly, so `check_LTLIBRARIES' is not allowed. However, `noinst_LTLIBRARIES' is allowed. This feature should be used for libtool "convenience libraries". For each library, the `LIBRARY_LIBADD' variable contains the names of extra libtool objects (`.lo' files) to add to the shared library. The `LIBRARY_LDFLAGS' variable contains any additional libtool flags, such as `-version-info' or `-static'. Where an ordinary library might include `@LIBOBJS@', a libtool library must use `@LTLIBOBJS@'. This is required because the object files that libtool operates on do not necessarily end in `.o'. The libtool manual contains more details on this topic. For libraries installed in some directory, Automake will automatically supply the appropriate `-rpath' option. However, for libraries determined at configure time (and thus mentioned in `EXTRA_LTLIBRARIES'), Automake does not know the eventual installation directory; for such libraries you must add the `-rpath' option to the appropriate `_LDFLAGS' variable by hand. Ordinarily, Automake requires that a shared library's name start with `lib'. However, if you are building a dynamically loadable module then you might wish to use a "nonstandard" name. In this case, put `-module' into the `_LDFLAGS' variable. *Note Using Automake with Libtool: (libtool)Using Automake, for more information.  File: automake.info, Node: Program and Library Variables, Next: LIBOBJS, Prev: A Shared Library, Up: Programs Program and Library Variables ============================= Associated with each program are a collection of variables which can be used to modify how that program is built. There is a similar list of such variables for each library. The canonical name of the program (or library) is used as a base for naming these variables. In the list below, we use the name "maude" to refer to the program or library. In your `Makefile.am' you would replace this with the canonical name of your program. This list also refers to "maude" as a program, but in general the same rules apply for both static and dynamic libraries; the documentation below notes situations where programs and libraries differ. `maude_SOURCES' This variable, if it exists, lists all the source files which are compiled to build the program. These files are added to the distribution by default. When building the program, Automake will cause each source file to be compiled to a single `.o' file (or `.lo' when using libtool). Normally these object files are named after the source file, but other factors can change this. If a file in the `_SOURCES' variable has an unrecognized extension, Automake will do one of two things with it. If a suffix rule exists for turning files with the unrecognized extension into `.o' files, then automake will treat this file as it will any other source file (*note Support for Other Languages::). Otherwise, the file will be ignored as though it were a header file. The prefixes `dist_' and `nodist_' can be used to control whether files listed in a `_SOURCES' variable are distributed. `dist_' is redundant, as sources are distributed by default, but it can be specified for clarity if desired. It is possible to have both `dist_' and `nodist_' variants of a given `_SOURCES' variable at once; this lets you easily distribute some files and not others, for instance: nodist_maude_SOURCES = nodist.c dist_maude_SOURCES = dist-me.c By default the output file (on Unix systems, the `.o' file) will be put into the current build directory. However, if the option `subdir-objects' is in effect in the current directory then the `.o' file will be put into the subdirectory named after the source file. For instance, with `subdir-objects' enabled, `sub/dir/file.c' will be compiled to `sub/dir/file.o'. Some people prefer this mode of operation. You can specify `subdir-objects' in `AUTOMAKE_OPTIONS' (*note Options::). `EXTRA_maude_SOURCES' Automake needs to know the list of files you intend to compile _statically_. For one thing, this is the only way Automake has of knowing what sort of language support a given `Makefile.in' requires. (1) This means that, for example, you can't put a configure substitution like `@my_sources@' into a `_SOURCES' variable. If you intend to conditionally compile source files and use `configure' to substitute the appropriate object names into, e.g., `_LDADD' (see below), then you should list the corresponding source files in the `EXTRA_' variable. This variable also supports `dist_' and `nodist_' prefixes, e.g., `nodist_EXTRA_maude_SOURCES'. `maude_AR' A static library is created by default by invoking `$(AR) cru' followed by the name of the library and then the objects being put into the library. You can override this by setting the `_AR' variable. This is usually used with C++; some C++ compilers require a special invocation in order to instantiate all the templates which should go into a library. For instance, the SGI C++ compiler likes this macro set like so: libmaude_a_AR = $(CXX) -ar -o `maude_LIBADD' Extra objects can be added to a static library using the `_LIBADD' variable. This should be used for objects determined by `configure'. Note that `_LIBADD' is not used for shared libraries; there you must use `_LDADD'. `maude_LDADD' Extra objects can be added to a shared library or a program by listing them in the `_LDADD' variable. This should be used for objects determined by `configure'. `_LDADD' and `_LIBADD' are inappropriate for passing program-specific linker flags (except for `-l', `-L', `-dlopen' and `-dlpreopen'). Use the `_LDFLAGS' variable for this purpose. For instance, if your `configure.in' uses `AC_PATH_XTRA', you could link your program against the X libraries like so: maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS) `maude_LDFLAGS' This variable is used to pass extra flags to the link step of a program or a shared library. `maude_LINK' You can override the linker on a per-program basis. By default the linker is chosen according to the languages used by the program. For instance, a program that includes C++ source code would use the C++ compiler to link. The `_LINK' variable must hold the name of a command which can be passed all the `.o' file names as arguments. Note that the name of the underlying program is _not_ passed to `_LINK'; typically one uses `$@': maude_LINK = $(CCLD) -magic -o $@ `maude_CFLAGS' Automake allows you to set compilation flags on a per-program (or per-library) basis. A single source file can be included in several programs, and it will potentially be compiled with different flags for each program. This works for any language directly supported by Automake. The flags are `_CFLAGS', `_CXXFLAGS', `_OBJCFLAGS', `_LFLAGS', `_YFLAGS', `_CCASFLAGS', `_FFLAGS', `_RFLAGS', and `_GCJFLAGS'. When using a per-program compilation flag, Automake will choose a different name for the intermediate object files. Ordinarily a file like `sample.c' will be compiled to produce `sample.o'. However, if the program's `_CFLAGS' variable is set, then the object file will be named, for instance, `maude-sample.o'. In compilations with per-program flags, the ordinary `AM_' form of the flags variable is _not_ automatically included in the compilation (however, the user form of the variable _is_ included). So for instance, if you want the hypothetical `maude' compilations to also use the value of `AM_CFLAGS', you would need to write: maude_CFLAGS = ... your flags ... $(AM_CFLAGS) `maude_DEPENDENCIES' It is also occasionally useful to have a program depend on some other target which is not actually part of that program. This can be done using the `_DEPENDENCIES' variable. Each program depends on the contents of such a variable, but no further interpretation is done. If `_DEPENDENCIES' is not supplied, it is computed by Automake. The automatically-assigned value is the contents of `_LDADD' or `_LIBADD', with most configure substitutions, `-l', `-L', `-dlopen' and `-dlpreopen' options removed. The configure substitutions that are left in are only `@LIBOBJS@' and `@ALLOCA@'; these are left because it is known that they will not cause an invalid value for `_DEPENDENCIES' to be generated. `maude_SHORTNAME' On some platforms the allowable file names are very short. In order to support these systems and per-program compilation flags at the same time, Automake allows you to set a "short name" which will influence how intermediate object files are named. For instance, if you set `maude_SHORTNAME' to `m', then in the above per-program compilation flag example the object file would be named `m-sample.o' rather than `maude-sample.o'. This facility is rarely needed in practice, and we recommend avoiding it until you find it is required. ---------- Footnotes ---------- (1) There are other, more obscure reasons reasons for this limitation as well.  File: automake.info, Node: LIBOBJS, Next: Program variables, Prev: Program and Library Variables, Up: Programs Special handling for LIBOBJS and ALLOCA ======================================= Automake explicitly recognizes the use of `@LIBOBJS@' and `@ALLOCA@', and uses this information, plus the list of `LIBOBJS' files derived from `configure.in' to automatically include the appropriate source files in the distribution (*note Dist::). These source files are also automatically handled in the dependency-tracking scheme; see *Note Dependencies::. `@LIBOBJS@' and `@ALLOCA@' are specially recognized in any `_LDADD' or `_LIBADD' variable.  File: automake.info, Node: Program variables, Next: Yacc and Lex, Prev: LIBOBJS, Up: Programs Variables used when building a program ====================================== Occasionally it is useful to know which `Makefile' variables Automake uses for compilations; for instance you might need to do your own compilation in some special cases. Some variables are inherited from Autoconf; these are `CC', `CFLAGS', `CPPFLAGS', `DEFS', `LDFLAGS', and `LIBS'. There are some additional variables which Automake itself defines: `AM_CPPFLAGS' The contents of this macro are passed to every compilation which invokes the C preprocessor; it is a list of arguments to the preprocessor. For instance, `-I' and `-D' options should be listed here. Automake already provides some `-I' options automatically. In particular it generates `-I$(srcdir)', `-I.', and a `-I' pointing to the directory holding `config.h' (if you've used `AC_CONFIG_HEADER' or `AM_CONFIG_HEADER'). You can disable the default `-I' options using the `nostdinc' option. `INCLUDES' This does the same job as `AM_CPPFLAGS'. It is an older name for the same functionality. This macro is deprecated; we suggest using `AM_CPPFLAGS' instead. `AM_CFLAGS' This is the variable which the `Makefile.am' author can use to pass in additional C compiler flags. It is more fully documented elsewhere. In some situations, this is not used, in preference to the per-executable (or per-library) `_CFLAGS'. `COMPILE' This is the command used to actually compile a C source file. The filename is appended to form the complete command line. `AM_LDFLAGS' This is the variable which the `Makefile.am' author can use to pass in additional linker flags. In some situations, this is not used, in preference to the per-executable (or per-library) `_LDFLAGS'. `LINK' This is the command used to actually link a C program. It already includes `-o $@' and the usual variable references (for instance, `CFLAGS'); it takes as "arguments" the names of the object files and libraries to link in.  File: automake.info, Node: Yacc and Lex, Next: C++ Support, Prev: Program variables, Up: Programs Yacc and Lex support ==================== Automake has somewhat idiosyncratic support for Yacc and Lex. Automake assumes that the `.c' file generated by `yacc' (or `lex') should be named using the basename of the input file. That is, for a yacc source file `foo.y', Automake will cause the intermediate file to be named `foo.c' (as opposed to `y.tab.c', which is more traditional). The extension of a yacc source file is used to determine the extension of the resulting `C' or `C++' file. Files with the extension `.y' will be turned into `.c' files; likewise, `.yy' will become `.cc'; `.y++', `c++'; and `.yxx', `.cxx'. Likewise, lex source files can be used to generate `C' or `C++'; the extensions `.l', `.ll', `.l++', and `.lxx' are recognized. You should never explicitly mention the intermediate (`C' or `C++') file in any `SOURCES' variable; only list the source file. The intermediate files generated by `yacc' (or `lex') will be included in any distribution that is made. That way the user doesn't need to have `yacc' or `lex'. If a `yacc' source file is seen, then your `configure.in' must define the variable `YACC'. This is most easily done by invoking the macro `AC_PROG_YACC' (*note Particular Program Checks: (autoconf)Particular Programs.). When `yacc' is invoked, it is passed `YFLAGS' and `AM_YFLAGS'. The former is a user variable and the latter is intended for the `Makefile.am' author. Similarly, if a `lex' source file is seen, then your `configure.in' must define the variable `LEX'. You can use `AC_PROG_LEX' to do this (*note Particular Program Checks: (autoconf)Particular Programs.), but using `AM_PROG_LEX' macro (*note Macros::) is recommended. When `lex' is invoked, it is passed `LFLAGS' and `AM_LFLAGS'. The former is a user variable and the latter is intended for the `Makefile.am' author. Automake makes it possible to include multiple `yacc' (or `lex') source files in a single program. Automake uses a small program called `ylwrap' to run `yacc' (or `lex') in a subdirectory. This is necessary because yacc's output filename is fixed, and a parallel make could conceivably invoke more than one instance of `yacc' simultaneously. The `ylwrap' program is distributed with Automake. It should appear in the directory specified by `AC_CONFIG_AUX_DIR' (*note Finding `configure' Input: (autoconf)Input.), or the current directory if that macro is not used in `configure.in'. For `yacc', simply managing locking is insufficient. The output of `yacc' always uses the same symbol names internally, so it isn't possible to link two `yacc' parsers into the same executable. We recommend using the following renaming hack used in `gdb': #define yymaxdepth c_maxdepth #define yyparse c_parse #define yylex c_lex #define yyerror c_error #define yylval c_lval #define yychar c_char #define yydebug c_debug #define yypact c_pact #define yyr1 c_r1 #define yyr2 c_r2 #define yydef c_def #define yychk c_chk #define yypgo c_pgo #define yyact c_act #define yyexca c_exca #define yyerrflag c_errflag #define yynerrs c_nerrs #define yyps c_ps #define yypv c_pv #define yys c_s #define yy_yys c_yys #define yystate c_state #define yytmp c_tmp #define yyv c_v #define yy_yyv c_yyv #define yyval c_val #define yylloc c_lloc #define yyreds c_reds #define yytoks c_toks #define yylhs c_yylhs #define yylen c_yylen #define yydefred c_yydefred #define yydgoto c_yydgoto #define yysindex c_yysindex #define yyrindex c_yyrindex #define yygindex c_yygindex #define yytable c_yytable #define yycheck c_yycheck #define yyname c_yyname #define yyrule c_yyrule For each define, replace the `c_' prefix with whatever you like. These defines work for `bison', `byacc', and traditional `yacc's. If you find a parser generator that uses a symbol not covered here, please report the new name so it can be added to the list.  File: automake.info, Node: C++ Support, Next: Assembly Support, Prev: Yacc and Lex, Up: Programs C++ Support =========== Automake includes full support for C++. Any package including C++ code must define the output variable `CXX' in `configure.in'; the simplest way to do this is to use the `AC_PROG_CXX' macro (*note Particular Program Checks: (autoconf)Particular Programs.). A few additional variables are defined when a C++ source file is seen: `CXX' The name of the C++ compiler. `CXXFLAGS' Any flags to pass to the C++ compiler. `AM_CXXFLAGS' The maintainer's variant of `CXXFLAGS'. `CXXCOMPILE' The command used to actually compile a C++ source file. The file name is appended to form the complete command line. `CXXLINK' The command used to actually link a C++ program.  File: automake.info, Node: Assembly Support, Next: Fortran 77 Support, Prev: C++ Support, Up: Programs Assembly Support ================ Automake includes some support for assembly code. The variable `CCAS' holds the name of the compiler used to build assembly code. This compiler must work a bit like a C compiler; in particular it must accept `-c' and `-o'. The value of `CCASFLAGS' is passed to the compilation. You are required to set `CCAS' and `CCASFLAGS' via `configure.in'. The autoconf macro `AM_PROG_AS' will do this for you. Unless they are already set, it simply sets `CCAS' to the C compiler and `CCASFLAGS' to the C compiler flags. Only the suffixes `.s' and `.S' are recognized by `automake' as being files containing assembly code.  File: automake.info, Node: Fortran 77 Support, Next: Java Support, Prev: Assembly Support, Up: Programs Fortran 77 Support ================== Automake includes full support for Fortran 77. Any package including Fortran 77 code must define the output variable `F77' in `configure.in'; the simplest way to do this is to use the `AC_PROG_F77' macro (*note Particular Program Checks: (autoconf)Particular Programs.). *Note Fortran 77 and Autoconf::. A few additional variables are defined when a Fortran 77 source file is seen: `F77' The name of the Fortran 77 compiler. `FFLAGS' Any flags to pass to the Fortran 77 compiler. `AM_FFLAGS' The maintainer's variant of `FFLAGS'. `RFLAGS' Any flags to pass to the Ratfor compiler. `AM_RFLAGS' The maintainer's variant of `RFLAGS'. `F77COMPILE' The command used to actually compile a Fortran 77 source file. The file name is appended to form the complete command line. `FLINK' The command used to actually link a pure Fortran 77 program or shared library. Automake can handle preprocessing Fortran 77 and Ratfor source files in addition to compiling them(1). Automake also contains some support for creating programs and shared libraries that are a mixture of Fortran 77 and other languages (*note Mixing Fortran 77 With C and C++::). These issues are covered in the following sections. * Menu: * Preprocessing Fortran 77:: * Compiling Fortran 77 Files:: * Mixing Fortran 77 With C and C++:: * Fortran 77 and Autoconf:: ---------- Footnotes ---------- (1) Much, if not most, of the information in the following sections pertaining to preprocessing Fortran 77 programs was taken almost verbatim from *Note Catalogue of Rules: (make)Catalogue of Rules.  File: automake.info, Node: Preprocessing Fortran 77, Next: Compiling Fortran 77 Files, Prev: Fortran 77 Support, Up: Fortran 77 Support Preprocessing Fortran 77 ------------------------ `N.f' is made automatically from `N.F' or `N.r'. This rule runs just the preprocessor to convert a preprocessable Fortran 77 or Ratfor source file into a strict Fortran 77 source file. The precise command used is as follows: `.F' `$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)' `.r' `$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)'  File: automake.info, Node: Compiling Fortran 77 Files, Next: Mixing Fortran 77 With C and C++, Prev: Preprocessing Fortran 77, Up: Fortran 77 Support Compiling Fortran 77 Files -------------------------- `N.o' is made automatically from `N.f', `N.F' or `N.r' by running the Fortran 77 compiler. The precise command used is as follows: `.f' `$(F77) -c $(AM_FFLAGS) $(FFLAGS)' `.F' `$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)' `.r' `$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)'  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 Mixing Fortran 77 With C and C++ -------------------------------- Automake currently provides _limited_ support for creating programs and shared libraries that are a mixture of Fortran 77 and C and/or C++. However, there are many other issues related to mixing Fortran 77 with other languages that are _not_ (currently) handled by Automake, but that are handled by other packages(1). Automake can help in two ways: 1. Automatic selection of the linker depending on which combinations of source code. 2. Automatic selection of the appropriate linker flags (e.g. `-L' and `-l') to pass to the automatically selected linker in order to link in the appropriate Fortran 77 intrinsic and run-time libraries. These extra Fortran 77 linker flags are supplied in the output variable `FLIBS' by the `AC_F77_LIBRARY_LDFLAGS' Autoconf macro supplied with newer versions of Autoconf (Autoconf version 2.13 and later). *Note Fortran 77 Compiler Characteristics: (autoconf)Fortran 77 Compiler Characteristics. If Automake detects that a program or shared library (as mentioned in some `_PROGRAMS' or `_LTLIBRARIES' primary) contains source code that is a mixture of Fortran 77 and C and/or C++, then it requires that the macro `AC_F77_LIBRARY_LDFLAGS' be called in `configure.in', and that either `$(FLIBS)' or `@FLIBS@' appear in the appropriate `_LDADD' (for programs) or `_LIBADD' (for shared libraries) variables. It is the responsibility of the person writing the `Makefile.am' to make sure that `$(FLIBS)' or `@FLIBS@' appears in the appropriate `_LDADD' or `_LIBADD' variable. For example, consider the following `Makefile.am': bin_PROGRAMS = foo foo_SOURCES = main.cc foo.f foo_LDADD = libfoo.la @FLIBS@ pkglib_LTLIBRARIES = libfoo.la libfoo_la_SOURCES = bar.f baz.c zardoz.cc libfoo_la_LIBADD = $(FLIBS) In this case, Automake will insist that `AC_F77_LIBRARY_LDFLAGS' is mentioned in `configure.in'. Also, if `@FLIBS@' hadn't been mentioned in `foo_LDADD' and `libfoo_la_LIBADD', then Automake would have issued a warning. * Menu: * How the Linker is Chosen:: ---------- Footnotes ---------- (1) For example, the cfortran package (http://www-zeus.desy.de/~burow/cfortran/) addresses all of these inter-language issues, and runs under nearly all Fortran 77, C and C++ compilers on nearly all platforms. However, `cfortran' is not yet Free Software, but it will be in the next major release.  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++ How the Linker is Chosen ........................ The following diagram demonstrates under what conditions a particular linker is chosen by Automake. For example, if Fortran 77, C and C++ source code were to be compiled into a program, then the C++ linker will be used. In this case, if the C or Fortran 77 linkers required any special libraries that weren't included by the C++ linker, then they must be manually added to an `_LDADD' or `_LIBADD' variable by the user writing the `Makefile.am'. \ Linker source \ code \ C C++ Fortran ----------------- +---------+---------+---------+ | | | | C | x | | | | | | | +---------+---------+---------+ | | | | C++ | | x | | | | | | +---------+---------+---------+ | | | | Fortran | | | x | | | | | +---------+---------+---------+ | | | | C + C++ | | x | | | | | | +---------+---------+---------+ | | | | C + Fortran | | | x | | | | | +---------+---------+---------+ | | | | C++ + Fortran | | x | | | | | | +---------+---------+---------+ | | | | C + C++ + Fortran | | x | | | | | | +---------+---------+---------+  File: automake.info, Node: Fortran 77 and Autoconf, Prev: Mixing Fortran 77 With C and C++, Up: Fortran 77 Support Fortran 77 and Autoconf ----------------------- The current Automake support for Fortran 77 requires a recent enough version of Autoconf that also includes support for Fortran 77. Full Fortran 77 support was added to Autoconf 2.13, so you will want to use that version of Autoconf or later.  File: automake.info, Node: Java Support, Next: Support for Other Languages, Prev: Fortran 77 Support, Up: Programs Java Support ============ Automake includes support for compiled Java, using `gcj', the Java front end to the GNU Compiler Collection. Any package including Java code to be compiled must define the output variable `GCJ' in `configure.in'; the variable `GCJFLAGS' must also be defined somehow (either in `configure.in' or `Makefile.am'). The simplest way to do this is to use the `AM_PROG_GCJ' macro. By default, programs including Java source files are linked with `gcj'. As always, the contents of `AM_GCJFLAGS' are passed to every compilation invoking `gcj' (in its role as an ahead-of-time compiler - when invoking it to create `.class' files, `AM_JAVACFLAGS' is used instead). If it is necessary to pass options to `gcj' from `Makefile.am', this macro, and not the user macro `GCJFLAGS', should be used. `gcj' can be used to compile `.java', `.class', `.zip', or `.jar' files. When linking, `gcj' requires that the main class be specified using the `--main=' option. The easiest way to do this is to use the `_LDFLAGS' variable for the program.  File: automake.info, Node: Support for Other Languages, Next: ANSI, Prev: Java Support, Up: Programs Support for Other Languages =========================== Automake currently only includes full support for C, C++ (*note C++ Support::), Fortran 77 (*note Fortran 77 Support::), and Java (*note Java Support::). There is only rudimentary support for other languages, support for which will be improved based on user demand. Some limited support for adding your own languages is available via the suffix rule handling; see *Note Suffixes::.  File: automake.info, Node: ANSI, Next: Dependencies, Prev: Support for Other Languages, Up: Programs Automatic de-ANSI-fication ========================== Although the GNU standards allow the use of ANSI C, this can have the effect of limiting portability of a package to some older compilers (notably the SunOS C compiler). Automake allows you to work around this problem on such machines by "de-ANSI-fying" each source file before the actual compilation takes place. If the `Makefile.am' variable `AUTOMAKE_OPTIONS' (*note Options::) contains the option `ansi2knr' then code to handle de-ANSI-fication is inserted into the generated `Makefile.in'. This causes each C source file in the directory to be treated as ANSI C. If an ANSI C compiler is available, it is used. If no ANSI C compiler is available, the `ansi2knr' program is used to convert the source files into K&R C, which is then compiled. The `ansi2knr' program is simple-minded. It assumes the source code will be formatted in a particular way; see the `ansi2knr' man page for details. Support for de-ANSI-fication requires the source files `ansi2knr.c' and `ansi2knr.1' to be in the same package as the ANSI C source; these files are distributed with Automake. Also, the package `configure.in' must call the macro `AM_C_PROTOTYPES' (*note Macros::). Automake also handles finding the `ansi2knr' support files in some other directory in the current package. This is done by prepending the relative path to the appropriate directory to the `ansi2knr' option. For instance, suppose the package has ANSI C code in the `src' and `lib' subdirs. The files `ansi2knr.c' and `ansi2knr.1' appear in `lib'. Then this could appear in `src/Makefile.am': AUTOMAKE_OPTIONS = ../lib/ansi2knr If no directory prefix is given, the files are assumed to be in the current directory. Files mentioned in `LIBOBJS' which need de-ANSI-fication will not be automatically handled. That's because `configure' will generate an object name like `regex.o', while `make' will be looking for `regex_.o' (when de-ANSI-fying). Eventually this problem will be fixed via `autoconf' magic, but for now you must put this code into your `configure.in', just before the `AC_OUTPUT' call: # This is necessary so that .o files in LIBOBJS are also built via # the ANSI2KNR-filtering rules. LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'` Note that automatic de-ANSI-fication will not work when the package is being built for a different host architecture. That is because automake currently has no way to build `ansi2knr' for the build machine.  File: automake.info, Node: Dependencies, Next: EXEEXT, Prev: ANSI, Up: Programs Automatic dependency tracking ============================= As a developer it is often painful to continually update the `Makefile.in' whenever the include-file dependencies change in a project. Automake supplies a way to automatically track dependency changes. Automake always uses complete dependencies for a compilation, including system headers. Automake's model is that dependency computation should be a side effect of the build. To this end, dependencies are computed by running all compilations through a special wrapper program called `depcomp'. `depcomp' understands how to coax many different C and C++ compilers into generating dependency information in the format it requires. `automake -a' will install `depcomp' into your source tree for you. If `depcomp' can't figure out how to properly invoke your compiler, dependency tracking will simply be disabled for your build. Experience with earlier versions of Automake (1) taught us that it is not reliable to generate dependencies only on the maintainer's system, as configurations vary too much. So instead Automake implements dependency tracking at build time. Automatic dependency tracking can be suppressed by putting `no-dependencies' in the variable `AUTOMAKE_OPTIONS', or passing `no-dependencies' as an argument to `AM_INIT_AUTOMAKE' (this should be the prefered way). Or, you can invoke `automake' with the `-i' option. Dependency tracking is enabled by default. The person building your package also can choose to disable dependency tracking by configuring with `--disable-dependency-tracking'. ---------- Footnotes ---------- (1) See `http://sources.redhat.com/automake/dependencies.html' for more information on the history and experiences with automatic dependency tracking in Automake