> If you install to locations other that bin_ and lib_ then a larger fix
> is necessary, but this should fix the 90% case.
-* Document why putting @FOO@ in _SOURCES doesn't work.
- This must be done for 1.5
-
* think about how per-object flags should work. in particular:
* how should they be specified?
using the object name is confusing when .lo/.obj in use
however, the object name provides a nice interaction with
per-exe flags
* how should they interact with per-executable flags?
+ [ this is probably a feature in search of a problem ]
* cross-compilation support:
programs built and used by the build process need to be
built for CC_FOR_BUILD
- introduce a new variable for this
+ introduce a new prefxi for this, e.g. `build_PROGRAMS'
[ we can do this in an automatic way I think.
unfortunately it isn't that useful until autoconf has support
for this sort of thing as well ]
diff -u $@-1 $@-2
rm -f $@-1 $@-2
+* one performance enhancement would be to have autoconf write
+ a single file containing all the macro assignments.
+ then read this file via `include'
+ unfortunately this can't be done because of conditionals
+
* support prog_LIBS as override for LIBS
* Scan configure.in using traces as autoheader does.
** per-exe flags don't work for CPPFLAGS/YFLAGS/LFLAGS. Fix.
** LIBOBJS shouldn't be used when there are per-exe flags (?)
-* Need a way to pass flags to makeinfo
- esp --no-split
-
-* test `make clean' with subdir-objects
-
* Test nodist_SOURCES with lex, yacc, etc.
* Support subdir-objects with fortran
Then have automake know about fnmatch.h.
[ probably should wait for autoconf to get right functionality ]
-* Every program foo has FOOFLAGS right now.
- It should also have AM_FOOFLAGS, which can be set in Makefile.am.
-DONE: but needs to be documented
-
* "make diff" capability
look at gcc's Makefile.in to see what to do
or look at maint program
-* BUILT_SOURCES should not be distributed, even when they appear in
- another _SOURCES line. [? or maybe just leave this up to the
- to-be-defined generic distribution method ]
- must completely revisit the entire BUILT_SOURCES idea
-
* in --cygnus, clean-info not generated at top level
* what if an element of a scanned variable looks like
strictness should only cover requirements
You should be able to pick and choose options
-should clean up texinfos.am; one rule is repeated 3 times, but
-shouldn't be
-
* rewrite in guile (RMS request)
at the same time, consider adding a GUI
could use the same parsing code for the GUI and the standalone version
Check to make sure various scripts are executable (IE when looking for
them in a directory)
-Use recode in dist target when MAINT_CHARSET specified. Read caveats
-in automake.in before doing this. Note the same problem used to apply
-to the no-dependencies option; maybe it still should? Note also that
-each Makefile.am must be rewritten at "make dist" time if
-MAINT_CHARSET and DIST_CHARSET are not identical. NOTE: gettext must
-arrange for all .po files not to be recoded. In the long term this
-might be a problem (consider when some systems use Unicode but the
-rest do not)
- MAINT_CHARSET *must* be local to each Makefile.am, to enable
- merged distributions.
- DIST_CHARSET must be passed down to subdir makes during a "make dist"
-
Handle dist-zoo. Generally add more DOS support. Maybe run "doschk"
(why isn't this merged with "pathchk"?) when doing a dist. Do
whatever else François says here...
$(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
@end example
+As it turns out, there is also a much easier way to do this same task.
+Some of the above techniques are useful enough that we've kept the
+example in the manual. However if you were to build @code{etags} and
+@code{ctags} in real life, you would probably use per-program
+compilation flags, like so:
+
+@example
+bin_PROGRAMS = ctags etags
+
+ctags_SOURCES = etags.c
+ctags_CFLAGS = -DCTAGS
+
+etags_SOURCES = etags.c
+etags_CFLAGS = -DETAGS_REGEXPS
+@end example
+
+In this case Automake will cause @file{etags.c} to be compiled twice,
+with different flags. De-ANSI-fication will work automatically. In
+this instance, the names of the object files would be chosen by
+automake; they would be @file{ctags-etags.c} and @file{etags-etags.o}.
+(The name of the object files rarely matters.)
+
@node Invoking Automake, configure, Examples, Top
@chapter Creating a @file{Makefile.in}
@menu
* A Program:: Building a program
* A Library:: Building a library
+* Program and Library Variables::
+ Variables controlling program and
+ library builds
* LIBOBJS:: Special handling for LIBOBJS and ALLOCA
* A Shared Library:: Building a Libtool library
* Program variables:: Variables used when building a program
In a directory containing source that gets built into a program (as
opposed to a library), the @samp{PROGRAMS} primary is used. Programs
can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
-@code{pkglibdir}, or not at all (@samp{noinst}).
+@code{pkglibdir}, or not at all (@samp{noinst}). They can also be built
+only for @code{make check}, in which case the prefix is @samp{check}.
For instance:
@end example
In this simple case, the resulting @file{Makefile.in} will contain code
-to generate a program named @code{hello}. The variable
-@code{hello_SOURCES} is used to specify which source files get built
-into an executable:
+to generate a program named @code{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 @code{hello_SOURCES} is used to specify which source files
+get built into an executable:
@example
hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
@cindex SOURCES primary, defined
@cindex Primary variable, SOURCES
-If @samp{@var{prog}_SOURCES} is needed, but not specified, then it
-defaults to the single file @file{prog.c}.
+If @samp{hello_SOURCES} is not specified, then it defaults to the single
+file @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.)
@vindex _SOURCES
@vindex SOURCES
(@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
and Lex}.
+You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
+@samp{_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.
+
@cindex EXTRA_prog_SOURCES, defined
Automake must know all the source files that could possibly go into a
cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
generated.
+Sometimes you want to compile a single source file two different ways
-@node A Library, LIBOBJS, A Program, Programs
+
+@node A Library, Program and Library Variables, A Program, Programs
@section Building a library
@cindex _LIBRARIES primary, defined
(@pxref{Sources}).
-@node LIBOBJS, A Shared Library, A Library, Programs
+@node Program and Library Variables, LIBOBJS, A Library, Programs
+@section 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 @file{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.
+
+@table @samp
+@item 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 @file{.o} file (or
+@file{.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 @samp{_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 @file{.o} files, then
+automake will treat this file as it will any other source file
+(@pxref{Support for Other Languages}). Otherwise, the file will be
+ignored as though it were a header file.
+
+The prefixes @samp{dist_} and @samp{nodist_} can be used to control
+whether files listed in a @samp{_SOURCES} variable are distributed.
+@samp{dist_} is redundant, as sources are distributed by default, but it
+can be specified for clarity if desired.
+
+It is possible to have both @samp{dist_} and @samp{nodist_} variants of
+a given @samp{_SOURCES} variable at once; this lets you easily
+distribute some files and not others, for instance:
+
+@example
+nodist_maude_SOURCES = nodist.c
+dist_maude_SOURCES = dist-me.c
+@end example
+
+
+@item EXTRA_maude_SOURCES
+Automake needs to know the list of files you intend to compile
+@emph{statically}. For one thing, this is the only way Automake has of
+knowing what sort of language support a given @file{Makefile.in}
+requires. @footnote{There are other, more obscure reasons reasons for
+this limitation as well.} This means that, for example, you can't put a
+configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
+variable. If you intend to conditionally compile source files and use
+@file{configure} to substitute the appropriate object names into, e.g.,
+@samp{_LDADD} (see below), then you should list the corresponding source
+files in the @samp{EXTRA_} variable.
+
+This variable also supports @samp{dist_} and @samp{nodist_} prefixes,
+e.g., @samp{nodist_EXTRA_maude_SOURCES}.
+
+@item maude_LIBADD
+@item maude_LDADD
+@item maude_LDFLAGS
+
+@item 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 @samp{_CFLAGS}, @samp{_CXXFLAGS},
+@samp{_OBJCFLAGS}, @samp{_YFLAGS}, @samp{_ASFLAGS}, @samp{_FFLAGS},
+@samp{_RFLAGS}, and @samp{_GCJFLAGS}.
+
+When using a per-program compilation flag, Automake will choose a
+different name for the intermediate object files. Ordinarily a file
+like @file{sample.c} will be compiled to produce @file{sample.o}.
+However, if the program's @samp{_CFLAGS} variable is set, then the
+object file will be named, for instance, @file{maude-sample.o}.
+
+@item maude_DEPENDENCIES
+
+
+@item 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
+@samp{maude_SHORTNAME} to @samp{m}, then in the above per-program
+compilation flag example the object file would be named
+@file{m-sample.o} rather than @file{maude-sample.o}. This facility is
+rarely needed in practice, and we recommend avoiding it until you find
+it is required.
+@end table
+
+
+@node LIBOBJS, A Shared Library, Program and Library Variables, Programs
@section Special handling for LIBOBJS and ALLOCA
@cindex @@LIBOBJS@@, special handling
If the current directory contains Texinfo source, you must declare it
with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
into info, and thus the @code{info_TEXINFOS} macro is most commonly used
-here. Note that any Texinfo source file must end in the @file{.texi} or
-@file{.texinfo} extension.
+here. Any Texinfo source file must end in the @file{.texi},
+@file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
+for new manuals.
@vindex TEXINFOS
@vindex info_TEXINFOS
@cindex Texinfo macro, VERSION
@cindex Texinfo macro, UPDATED
@cindex Texinfo macro, EDITION
+@cindex Texinfo macro, UPDATED-MONTH
@cindex VERSION Texinfo macro
@cindex UPDATED Texinfo macro
@cindex EDITION Texinfo macro
+@cindex UPDATED-MONTH Texinfo macro
@cindex mdate-sh
If the @file{.texi} file @code{@@include}s @file{version.texi}, then
that file will be automatically generated. The file @file{version.texi}
-defines three Texinfo macros you can reference: @code{EDITION},
-@code{VERSION}, and @code{UPDATED}. The first two hold the version
-number of your package (but are kept separate for clarity); the last is
-the date the primary file was last modified. The @file{version.texi}
-support requires the @code{mdate-sh} program; this program is supplied
-with Automake and automatically included when @code{automake} is invoked
-with the @code{--add-missing} option.
+defines four Texinfo macros you can reference:
+
+@table @code
+@item EDITION
+@itemx VERSION
+Both of these macros hold the version number of your program. They are
+kept separate for clarity.
+
+@item UPDATED
+This holds the date the primary @file{.texi} file was last modified.
+
+@item UPDATED-MONTH
+This holds the name of the month in which the primary @file{.texi} file
+was last modified.
+@end table
+
+The @file{version.texi} support requires the @code{mdate-sh} program;
+this program is supplied with Automake and automatically included when
+@code{automake} is invoked with the @code{--add-missing} option.
If you have multiple Texinfo files, and you want to use the
@file{version.texi} feature, then you have to have a separate version
Texinfo file that matches @samp{vers*.texi} just as an automatically
generated version file.
+When an info file is rebuilt, the program named by the @code{MAKEINFO}
+variable is used to invoke it. If the @code{makeinfo} program is found
+on the system then it will be used by default; otherwise @code{missing}
+will be used instead. The flags in the variables @code{MAKEINFOFLAGS}
+and @code{AM_MAKEINFOFLAGS} will be passed to the @code{makeinfo}
+invocation; the first of these is intended for use by the user
+(@pxref{User Variables}) and the second by the @file{Makefile.am}
+writer.
+@vindex MAKEINFO
+@vindex MAKEINFOFLAGS
+@vindex AM_MAKEINFOFLAGS
+
Sometimes an info file actually depends on more than one @file{.texi}
file. For instance, in GNU Hello, @file{hello.texi} includes the file
@file{gpl.texi}. You can tell Automake about these dependencies using
Automake supports two forms of test suites.
+@section Simple Tests
+
If the variable @code{TESTS} is defined, its value is taken to be a list
of programs to run in order to do the testing. The programs can either
be derived objects or source objects; the generated rule will look both
@vindex TESTS
@vindex TESTS_ENVIRONMENT
+@cindex Tests, expected failure
+@cindex Expected test failure
+
+You may define the variable @code{XFAIL_TESTS} to a list of tests
+(usually a subset of @code{TESTS}) that are expected to fail. This will
+reverse the result of those tests.
+@vindex XFAIL_TESTS
+
+Automake ensures that each program listed in @code{TESTS} is built
+before any tests are run; you can list both source and derived programs
+in @code{TESTS}. For instance, you might want to run a C program as a
+test. To do this you would list its name in @code{TESTS} and also in
+@code{check_PROGRAMS}, and then specify it as you would any other
+program.
+
+@section DejaGNU Tests
+
If @uref{ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz,
@samp{dejagnu}} appears in @code{AUTOMAKE_OPTIONS}, then a
@code{dejagnu}-based test suite is assumed. The variable
overridden if necessary.
@vindex RUNTESTDEFAULTFLAGS
-The variables @code{EXPECT}, @code{RUNTEST} and @code{RUNTESTFLAGS} can
+The variables @code{EXPECT} and @code{RUNTEST} can
also be overridden to provide project-specific values. For instance,
you will need to do this if you are testing a compiler toolchain,
because the default values do not take into account host and target
@vindex DEJATOOL
@vindex EXPECT
@vindex RUNTEST
+
+The contents of the variable @code{RUNTESTFLAGS} are passed to the
+@code{runtest} invocation. This is considered a ``user variable''
+(@pxref{User Variables}). If you need to set @code{runtest} flags in
+@file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
@vindex RUNTESTFLAGS
+@vindex AM_RUNTESTFLAGS
@c FIXME xref dejagnu
-If you're not using dejagnu, you may define the variable
-@samp{XFAIL_TESTS} to a list of tests (usually a subset of @samp{TESTS})
-that are expected to fail. This will reverse the result of those tests.
-
In either case, the testing is done via @samp{make check}.
git://sourceware.org / automake.git / commitdiff