diff options
Diffstat (limited to 'doc/automake.texi')
| -rw-r--r-- | doc/automake.texi | 150 |
1 files changed, 47 insertions, 103 deletions
diff --git a/doc/automake.texi b/doc/automake.texi index 050c9811d..347d74535 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -193,6 +193,7 @@ Auto-generating aclocal.m4 Autoconf macros supplied with Automake * Public Macros:: Macros that you can use. +* Obsolete Macros:: Obsolete macros you should no longer use * Private Macros:: Macros that you should not use. Directories @@ -3334,15 +3335,10 @@ way as it is for @command{automake} (@pxref{automake Invocation}). @cindex Macro search path @cindex @command{aclocal} search path -By default, @command{aclocal} searches for @file{.m4} files in the following -directories, in this order: +By default, @command{aclocal} searches for @file{.m4} files in the +following directories, in this order: @table @code -@item @var{acdir-APIVERSION} -This is where the @file{.m4} macros distributed with Automake itself -are stored. @var{APIVERSION} depends on the Automake release used; -for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}. - @item @var{acdir} This directory is intended for third party @file{.m4} files, and is configured when @command{automake} itself is built. This is @@ -3350,14 +3346,19 @@ configured when @command{automake} itself is built. This is expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in value of @var{acdir}, use the @option{--print-ac-dir} option (@pxref{aclocal Options}). + +@item @var{acdir-APIVERSION} +This is where the @file{.m4} macros distributed with Automake itself +are stored. @var{APIVERSION} depends on the Automake release used; +for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}. @end table As an example, suppose that @command{automake-1.11.2} was configured with @option{--prefix=@-/usr/local}. Then, the search path would be: @enumerate -@item @file{/usr/local/share/aclocal-1.11.2/} @item @file{/usr/local/share/aclocal/} +@item @file{/usr/local/share/aclocal-1.11.2/} @end enumerate The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can @@ -3379,8 +3380,8 @@ Any extra directories specified using @option{-I} options @enumerate @item @file{/foo} @item @file{/bar} -@item @var{acdir}-@var{APIVERSION} @item @var{acdir} +@item @var{acdir}-@var{APIVERSION} @end enumerate @subsubheading Modifying the Macro Search Path: @file{dirlist} @@ -3407,13 +3408,14 @@ and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options. Then, the search path would be @c @code looks better than @file here +@c See test aclocal-dirlist.sh @enumerate @item @code{/foo} @item @code{/bar} -@item @var{acdir}-@var{APIVERSION} @item @var{acdir} @item @code{/test1} @item @code{/test2} +@item @var{acdir}-@var{APIVERSION} @end enumerate @noindent @@ -3430,19 +3432,22 @@ If the @option{--system-acdir=@var{dir}} option is used, then directories are @c @code looks better than @file here +@c Keep in sync with aclocal-path-precedence.sh @enumerate -@item @code{/usr/share/aclocal-1.11/} @item @code{/usr/share/aclocal/} +@item @code{/usr/share/aclocal-1.11/} @end enumerate -However, suppose further that many packages have been manually -installed on the system, with $prefix=/usr/local, as is typical. In +However, suppose further that many packages have been manually installed +on the system, with @code{$@{prefix@}=/usr/local}, as is typical. In that case, many of these ``extra'' @file{.m4} files are in -@file{/usr/local/share/aclocal}. The only way to force -@file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to -always call @samp{aclocal -I /usr/local/share/aclocal}. This is -inconvenient. With @file{dirlist}, one may create a file -@file{/usr/share/aclocal/dirlist} containing only the single line +@file{/usr/local/share/aclocal}. A way to force @file{/usr/bin/aclocal} +to find these ``extra'' @file{.m4} files is to export @code{ACLOCAL_PATH} +to @samp{/usr/local/share/aclocal}. This is a little inconvenient, +since it requires either explicit user cooperation, or editing of the +system global shell initialization file. With @file{dirlist}, one may +create a file @file{/usr/share/aclocal/dirlist} containing only the +single line @example /usr/local/share/aclocal @@ -3451,20 +3456,18 @@ inconvenient. With @file{dirlist}, one may create a file Now, the ``default'' search path on the affected system is @c @code looks better than @file here +@c See test aclocal-dirlist.sh @enumerate -@item @code{/usr/share/aclocal-1.11/} @item @code{/usr/share/aclocal/} @item @code{/usr/local/share/aclocal/} +@item @code{/usr/share/aclocal-1.11/} @end enumerate -without the need for @option{-I} options; @option{-I} options can be reserved -for project-specific needs (@file{my-source-dir/m4/}), rather than -using it to work around local system-dependent tool installation -directories. +without the need of any explicit @code{ACLOCAL_PATH} setting. Similarly, @file{dirlist} can be handy if you have installed a local -copy of Automake in your account and want @command{aclocal} to look for -macros installed at other places on the system. +copy of Automake in your account and want @command{aclocal} to look +for macros installed at other places on the system. @anchor{ACLOCAL_PATH} @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH} @@ -3492,16 +3495,6 @@ Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are using a global copy of Automake and want @command{aclocal} to look for macros somewhere under your home directory. -@subsubheading Planned future incompatibilities - -The order in which the directories in the macro search path are currently -looked up is confusing and/or suboptimal in various aspects, and is -probably going to be changed in the future Automake release. In -particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}} -might end up taking precedence over @file{@var{acdir-APIVERSION}}, and -directories in @file{@var{acdir}/dirlist} might end up taking precedence -over @file{@var{acdir}}. @emph{This is a possible future incompatibility!} - @node Extending aclocal @subsection Writing your own aclocal macros @@ -3529,7 +3522,7 @@ aclocal_DATA = mymacro.m4 myothermacro.m4 @noindent Please do use @file{$(datadir)/aclocal}, and not something based on the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install -Paths}, for arguments). It might also be helpful to suggest to +Paths}, for rationale). It might also be helpful to suggest to the user to add the @file{$(datadir)/aclocal} directory to his @env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that @command{aclocal} will find the @file{.m4} files installed by your @@ -3896,7 +3889,7 @@ Automake ships with several Autoconf macros that you can use from your @menu * Public Macros:: Macros that you can use. -* Obsolete Macros:: Macros that will soon be removed. +* Obsolete Macros:: Obsolete macros you should no longer use * Private Macros:: Macros that you should not use. @end menu @@ -4072,18 +4065,14 @@ define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}. @node Obsolete Macros -@subsection Obsolete Macros +@subsection Obsolete macros you should no longer use @cindex obsolete macros -@cindex autoupdate Although using some of the following macros was required in past -releases, you should not use any of them in new code. @emph{All -these macros will be removed in the next major Automake version}; -if you are still using them, running @command{autoupdate} should -adjust your @file{configure.ac} automatically (@pxref{autoupdate -Invocation, , Using @command{autoupdate} to Modernize -@file{configure.ac}, autoconf, The Autoconf Manual}). -@emph{Do it NOW!} +releases, you should not use any of them in new code. Also, most +of these macros will probably be @emph{removed in some future Automake +version}, so you should consider updating your @file{configure.ac} +to avoid problems in the future. @table @code @@ -4109,7 +4098,6 @@ in a future major Automake release. @end table - @node Private Macros @subsection Private Macros @@ -5656,18 +5644,13 @@ nodist_maude_SOURCES = nodist.c dist_maude_SOURCES = dist-me.c @end example -By default the output file (on Unix systems, the @file{.o} file) will -be put into the current build directory. However, if the option -@option{subdir-objects} is in effect in the current directory then the -@file{.o} file will be put into the subdirectory named after the -source file. For instance, with @option{subdir-objects} enabled, -@file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some -people prefer this mode of operation. You can specify -@option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}). +The output file (on Unix systems, the @file{.o} file) will be put into the +subdirectory named after the source file. For instance @file{file.c} will +compiled to @file{file.o}, while @file{sub/dir/file.c} will be compiled to +@file{sub/dir/file.o}. @cindex Subdirectory, objects in @cindex Objects in subdirectory - @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 @@ -6061,19 +6044,15 @@ tool1_SOURCES = @dots{} tool2_SOURCES = @dots{} @end example -When option @option{subdir-objects} is not used, as in the above -example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only -be used in the directory where their sources lie. E.g., here it would -be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in -@file{src/Makefile.am}. However if both @option{subdir-objects} and -@code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables +The variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} are typically +used in the directory where their sources lie. However, if +@code{AC_CONFIG_LIBOBJ_DIR} is used, it is OK to use these variables in other directories. For instance @file{src/Makefile.am} could be changed as follows. @example # src/Makefile.am -AUTOMAKE_OPTIONS = subdir-objects LDADD = $(LIBOBJS) $(ALLOCA) bin_PROGRAMS = tool1 tool2 @dots{} @@ -8734,20 +8713,6 @@ default compression ratio, but with a progress indicator: Generate a @samp{zip} archive of the distribution. @trindex dist-zip -@item @code{dist-tarZ} -Generate a tar archive of the distribution, compressed with the -historical (and obsolescent) program @command{compress}. This -option is deprecated, and it and the corresponding functionality -will be removed altogether in Automake 2.0. -@trindex dist-tarZ - -@item @code{dist-shar} -Generate a @samp{shar} archive of the distribution. This format -archive is obsolescent, and use of this option is deprecated. -It and the corresponding functionality will be removed altogether -in Automake 2.0. -@trindex dist-shar - @end table The rule @code{dist} (and its historical synonym @code{dist-all}) @@ -10121,23 +10086,6 @@ Hook @code{dist-xz} to @code{dist}. Hook @code{dist-zip} to @code{dist}. @trindex dist-zip -@item @option{dist-shar} -@cindex Option, @option{dist-shar} -@opindex dist-shar -Hook @code{dist-shar} to @code{dist}. Use of this option -is deprecated, as the @samp{shar} format is obsolescent and -problematic. Support for it will be removed altogether in -Automake 2.0. -@trindex dist-shar - -@item @option{dist-tarZ} -@cindex Option, @option{dist-tarZ} -@opindex dist-tarZ -Hook @code{dist-tarZ} to @code{dist}. Use of this option -is deprecated, as the @samp{compress} program is obsolete. -Support for it will be removed altogether in Automake 2.0. -@trindex dist-tarZ - @item @option{filename-length-max=99} @cindex Option, @option{filename-length-max=99} @opindex filename-length-max=99 @@ -10290,11 +10238,8 @@ AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh @item @option{subdir-objects} @cindex Options, @option{subdir-objects} @opindex subdir-objects -If this option is specified, then objects are placed into the -subdirectory of the build directory corresponding to the subdirectory of -the source file. For instance, if the source file is -@file{subdir/file.cxx}, then the output file would be -@file{subdir/file.o}. +This option does nothing; it exists solely for compatibility with +older Automake versions. @anchor{tar-formats} @item @option{tar-v7} @@ -10314,8 +10259,7 @@ the source file. For instance, if the source file is These three mutually exclusive options select the tar format to use when generating tarballs with @samp{make dist}. (The tar file created is then compressed according to the set of @option{no-dist-gzip}, -@option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and -@option{dist-tarZ} options in use.) +@option{dist-bzip2}, @option{dist-lzip} and @option{dist-xz} in use). These options must be passed as arguments to @code{AM_INIT_AUTOMAKE} (@pxref{Macros}) because they can require additional configure checks. @@ -13192,11 +13136,11 @@ suite failures, please attach the @file{test-suite.log} file. @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean -@c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp +@c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip exp @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS -@c LocalWords: installcheck gzipped tarZ std utils etags mkid cd +@c LocalWords: installcheck gzipped std utils etags mkid cd @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE |