From 177acb535afc978a9fcdfc90a4e9e63448710eb0 Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Tue, 29 May 2001 21:04:10 +0000 Subject: [PATCH] * automake.texi (A Program): Mention `check' prefix. (Program and Library Variables): New node. (Texinfo): Document UPDATED-MONTH, MAKEINFOFLAGS, and AM_MAKEINFOFLAGS. (etags): Mention per-program flags. (Tests): Document AM_RUNTESTFLAGS; added sectioning; more updates. --- ChangeLog | 8 ++ Makefile.in | 19 ++-- NEWS | 3 +- TODO | 40 ++----- automake.texi | 228 +++++++++++++++++++++++++++++++++++---- lib/Automake/Makefile.in | 2 - lib/Makefile.in | 12 +-- m4/Makefile.in | 2 - stamp-vti | 2 +- tests/Makefile.in | 2 - version.texi | 2 +- 11 files changed, 240 insertions(+), 80 deletions(-) diff --git a/ChangeLog b/ChangeLog index 56783d72..2a66093c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,13 @@ 2001-05-29 Tom Tromey + * automake.texi (A Program): Mention `check' prefix. + (Program and Library Variables): New node. + (Texinfo): Document UPDATED-MONTH, MAKEINFOFLAGS, and + AM_MAKEINFOFLAGS. + (etags): Mention per-program flags. + (Tests): Document AM_RUNTESTFLAGS; added sectioning; more + updates. + * lib/am/texinfos.am (.PHONY): Always list uninstall-info-am and install-info-am. diff --git a/Makefile.in b/Makefile.in index 014b3b25..7e904aad 100644 --- a/Makefile.in +++ b/Makefile.in @@ -528,15 +528,16 @@ uninstall-info: uninstall-info-recursive dvi-recursive info info-am info-recursive install install-am \ install-binSCRIPTS install-data install-data-am \ install-data-recursive install-exec install-exec-am \ - install-exec-recursive install-info install-info-recursive \ - install-man install-recursive install-strip installcheck \ - installcheck-am installdirs installdirs-am \ - installdirs-recursive maintainer-clean maintainer-clean-aminfo \ - maintainer-clean-generic maintainer-clean-recursive \ - maintainer-clean-vti mostlyclean mostlyclean-aminfo \ - mostlyclean-generic mostlyclean-recursive mostlyclean-vti tags \ - tags-recursive uninstall uninstall-am uninstall-binSCRIPTS \ - uninstall-info-recursive uninstall-recursive + install-exec-recursive install-info install-info-am \ + install-info-recursive install-man install-recursive \ + install-strip installcheck installcheck-am installdirs \ + installdirs-am installdirs-recursive maintainer-clean \ + maintainer-clean-aminfo maintainer-clean-generic \ + maintainer-clean-recursive maintainer-clean-vti mostlyclean \ + mostlyclean-aminfo mostlyclean-generic mostlyclean-recursive \ + mostlyclean-vti tags tags-recursive uninstall uninstall-am \ + uninstall-binSCRIPTS uninstall-info-am uninstall-info-recursive \ + uninstall-recursive ################################################################ diff --git a/NEWS b/NEWS index 66033d45..e0ad5aae 100644 --- a/NEWS +++ b/NEWS @@ -6,7 +6,6 @@ New in 1.4f: * Faster AM_INIT_AUTOMAKE (requires update of `missing' script) * User-side dependency tracking. Developers no longer need GNU make * Python support -* Many bug fixes * Uses DIST_SUBDIRS in some situations when SUBDIRS is conditional * Many files (but not all) are correctly handled if they appear in subdirs For instance, a _DATA file can appear in a subdir @@ -14,7 +13,7 @@ New in 1.4f: * Added support for `dist_' and `nodist_' prefixes * Compiled Java support * Support for per-executable and per-library compilation flags -* The usual bug fixes +* Many bug fixes New in 1.4: * Added support for the Fortran 77 programming language. diff --git a/TODO b/TODO index 54a4368c..fd2e6407 100644 --- a/TODO +++ b/TODO @@ -55,20 +55,18 @@ Alex Hornby > 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 ] @@ -83,6 +81,11 @@ Alex Hornby 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. @@ -102,11 +105,6 @@ Alex Hornby ** 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 @@ -278,19 +276,10 @@ Alex Hornby 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 @@ -337,9 +326,6 @@ non-C source in a libtool library specification. 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 @@ -484,18 +470,6 @@ Need way to say there are no suffixes in a Makefile (Franc,ois' 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... diff --git a/automake.texi b/automake.texi index a6c2d5f1..b4868171 100644 --- a/automake.texi +++ b/automake.texi @@ -748,6 +748,28 @@ ctags._o: etags._c $(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} @@ -1495,6 +1517,9 @@ to build programs and libraries. @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 @@ -1521,7 +1546,8 @@ to build programs and libraries. 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: @@ -1530,9 +1556,15 @@ bin_PROGRAMS = hello @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 @@ -1545,8 +1577,10 @@ corresponding @samp{.o}. Then all are linked to produce @file{hello}. @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 @@ -1564,6 +1598,11 @@ should not include the header file generated by @file{configure} in an (@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 @@ -1652,8 +1691,10 @@ configure substitutions that are left in are only @samp{@@LIBOBJS@@} and 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 @@ -1704,7 +1745,102 @@ configure-time must be added to the @code{BUILT_SOURCES} variable (@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 @@ -2742,30 +2878,45 @@ Currently Automake provides support for Texinfo and man pages. 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 @@ -2773,6 +2924,18 @@ file for each Texinfo file. Automake will treat any include in a 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 @@ -3097,6 +3260,8 @@ standard mechanism. 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 @@ -3122,6 +3287,23 @@ set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g. @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 @@ -3134,7 +3316,7 @@ The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and 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 @@ -3143,13 +3325,15 @@ names. @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}. diff --git a/lib/Automake/Makefile.in b/lib/Automake/Makefile.in index 7cb55c8a..ca51201a 100644 --- a/lib/Automake/Makefile.in +++ b/lib/Automake/Makefile.in @@ -196,8 +196,6 @@ mostlyclean-am: mostlyclean-generic uninstall-am: uninstall-dist_perllibDATA uninstall-info-am -uninstall-info: uninstall-info-am - .PHONY: all all-am check check-am clean clean-generic distclean \ distclean-generic distdir dvi dvi-am info info-am install \ install-am install-data install-data-am \ diff --git a/lib/Makefile.in b/lib/Makefile.in index 5f27f399..c45be601 100644 --- a/lib/Makefile.in +++ b/lib/Makefile.in @@ -342,15 +342,15 @@ uninstall-info: uninstall-info-recursive install-data install-data-am install-data-recursive \ install-dist_pkgdataDATA install-dist_scriptDATA install-exec \ install-exec-am install-exec-recursive install-info \ - install-info-recursive install-man install-recursive \ - install-strip installcheck installcheck-am installcheck-local \ - installdirs installdirs-am installdirs-recursive \ - maintainer-clean maintainer-clean-generic \ + install-info-am install-info-recursive install-man \ + install-recursive install-strip installcheck installcheck-am \ + installcheck-local installdirs installdirs-am \ + installdirs-recursive maintainer-clean maintainer-clean-generic \ maintainer-clean-recursive mostlyclean mostlyclean-generic \ mostlyclean-recursive tags tags-recursive uninstall \ uninstall-am uninstall-dist_pkgdataDATA \ - uninstall-dist_scriptDATA uninstall-info-recursive \ - uninstall-recursive + uninstall-dist_scriptDATA uninstall-info-am \ + uninstall-info-recursive uninstall-recursive install-data-hook: diff --git a/m4/Makefile.in b/m4/Makefile.in index d55009e2..c69295cd 100644 --- a/m4/Makefile.in +++ b/m4/Makefile.in @@ -205,8 +205,6 @@ mostlyclean-am: mostlyclean-generic uninstall-am: uninstall-info-am uninstall-m4dataDATA -uninstall-info: uninstall-info-am - .PHONY: all all-am check check-am clean clean-generic distclean \ distclean-generic distdir dvi dvi-am info info-am install \ install-am install-data install-data-am install-exec \ diff --git a/stamp-vti b/stamp-vti index 0d462d85..bea77afa 100644 --- a/stamp-vti +++ b/stamp-vti @@ -1,4 +1,4 @@ -@set UPDATED 21 May 2001 +@set UPDATED 29 May 2001 @set UPDATED-MONTH May 2001 @set EDITION 1.4g @set VERSION 1.4g diff --git a/tests/Makefile.in b/tests/Makefile.in index 840995bc..0b28d75c 100644 --- a/tests/Makefile.in +++ b/tests/Makefile.in @@ -529,8 +529,6 @@ mostlyclean-am: mostlyclean-generic uninstall-am: uninstall-info-am -uninstall-info: uninstall-info-am - .PHONY: all all-am check check-TESTS check-am clean clean-generic \ distclean distclean-generic distclean-local distdir dvi dvi-am \ info info-am install install-am install-data install-data-am \ diff --git a/version.texi b/version.texi index 0d462d85..bea77afa 100644 --- a/version.texi +++ b/version.texi @@ -1,4 +1,4 @@ -@set UPDATED 21 May 2001 +@set UPDATED 29 May 2001 @set UPDATED-MONTH May 2001 @set EDITION 1.4g @set VERSION 1.4g -- 2.43.5