* doc/autoconf.texi (Installation Directory Variables): New

section, Eved off from `Preset Output Variables', i.e., was a
small part of it, grew independent, and is its equal (at least).
(Coding Style): `$#' padding.
* Makefile.am (editsh, editpl): Do what the doc says you do: use
@datadir\@ instead of @''datadir''@.

diff --git a/ChangeLog b/ChangeLog
index 8d55f5c97a62e5fa853af9c824c4954e995cc6f3..9336b522fd617e36a667e403380dcddabef57be8 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2000-07-28  Akim Demaille  <akim@epita.fr>
+
+       * doc/autoconf.texi (Installation Directory Variables): New
+       section, Eved off from `Preset Output Variables', i.e., was a
+       small part of it, grew independent, and is its equal (at least).
+       (Coding Style): `$#' padding.
+       * Makefile.am (editsh, editpl): Do what the doc says you do: use
+       @datadir\@ instead of @''datadir''@.
+
 2000-07-28  Akim Demaille  <akim@epita.fr>
 
        * aclang.m4 (_AC_PROG_CC_GNU, _AC_PROG_CXX_GNU,

diff --git a/Makefile.am b/Makefile.am
index 1ed8a10a3ce3922746048408fb9eaf8f2a413f03..6d6b690f025ab86bf2a3f34c4a30f3365b2601cb 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -76,20 +76,20 @@ MAINTAINERCLEANFILES = INSTALL.txt
 # The scripts.
 
 editsh = sed \
-       -e 's,@''datadir''@,$(pkgdatadir),g' \
-       -e 's,@''M4''@,$(M4),g' \
-       -e 's,@''AWK''@,$(AWK),g' \
-       -e 's,@''SHELL''@,$(SHELL),g' \
-       -e 's,@''VERSION''@,$(VERSION),g' \
-       -e 's,@''PACKAGE''@,$(PACKAGE),g' \
-       -e 's,@autoconf-name@,'`echo autoconf | sed '$(transform)'`',g' \
-       -e 's,@autoheader-name@,'`echo autoheader | sed '$(transform)'`',g'
+       -e 's,@datadir\@,$(pkgdatadir),g' \
+       -e 's,@M4\@,$(M4),g' \
+       -e 's,@AWK\@,$(AWK),g' \
+       -e 's,@SHELL\@,$(SHELL),g' \
+       -e 's,@VERSION\@,$(VERSION),g' \
+       -e 's,@PACKAGE\@,$(PACKAGE),g' \
+       -e 's,@autoconf-name\@,'`echo autoconf | sed '$(transform)'`',g' \
+       -e 's,@autoheader-name\@,'`echo autoheader | sed '$(transform)'`',g'
 
 editpl = sed \
-       -e 's,@''datadir''@,$(pkgdatadir),g' \
-       -e 's,@''PERL''@,$(PERL),g' \
-       -e 's,@''VERSION''@,$(VERSION),g' \
-       -e 's,@''PACKAGE''@,$(PACKAGE),g'
+       -e 's,@datadir\@,$(pkgdatadir),g' \
+       -e 's,@PERL\@,$(PERL),g' \
+       -e 's,@VERSION\@,$(VERSION),g' \
+       -e 's,@PACKAGE\@,$(PACKAGE),g'
 
 .sh:
        rm -f $@ $@.tmp

diff --git a/Makefile.in b/Makefile.in
index b83dff3354da121ad28f69ecd0362ddc3203f310..cfba23c8dd403de3d8bf4335832aa8ada6bfad03 100644 (file)
--- a/Makefile.in
+++ b/Makefile.in
@@ -100,10 +100,10 @@ MAINTAINERCLEANFILES = INSTALL.txt
 
 # The scripts.
 
-editsh = sed   -e 's,@''datadir''@,$(pkgdatadir),g'    -e 's,@''M4''@,$(M4),g'         -e 's,@''AWK''@,$(AWK),g'       -e 's,@''SHELL''@,$(SHELL),g'   -e 's,@''VERSION''@,$(VERSION),g'       -e 's,@''PACKAGE''@,$(PACKAGE),g'       -e 's,@autoconf-name@,'`echo autoconf | sed '$(transform)'`',g'         -e 's,@autoheader-name@,'`echo autoheader | sed '$(transform)'`',g'
+editsh = sed   -e 's,@datadir\@,$(pkgdatadir),g'       -e 's,@M4\@,$(M4),g'    -e 's,@AWK\@,$(AWK),g'  -e 's,@SHELL\@,$(SHELL),g'      -e 's,@VERSION\@,$(VERSION),g'  -e 's,@PACKAGE\@,$(PACKAGE),g'  -e 's,@autoconf-name\@,'`echo autoconf | sed '$(transform)'`',g'        -e 's,@autoheader-name\@,'`echo autoheader | sed '$(transform)'`',g'
 
 
-editpl = sed   -e 's,@''datadir''@,$(pkgdatadir),g'    -e 's,@''PERL''@,$(PERL),g'     -e 's,@''VERSION''@,$(VERSION),g'       -e 's,@''PACKAGE''@,$(PACKAGE),g'
+editpl = sed   -e 's,@datadir\@,$(pkgdatadir),g'       -e 's,@PERL\@,$(PERL),g'        -e 's,@VERSION\@,$(VERSION),g'  -e 's,@PACKAGE\@,$(PACKAGE),g'
 
 
 common = libm4.m4 acgeneral.m4 acspecific.m4 acoldnames.m4 acversion.m4          aclang.m4

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 435534ce4c72747ccbda72b873daba9a350d0188..b23c1c71c6925ea63f2c5438576a7fb3181ccdf7 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -183,6 +183,7 @@ Initialization and Output Files
 Substitutions in Makefiles
 
 * Preset Output Variables::     Output variables that are always set
+* Installation Directory Variables::  Other preset output variables
 * Build Directories::           Supporting multiple concurrent compiles
 * Automatic Remaking::          Makefile rules for configuring
 
@@ -1571,24 +1572,33 @@ GNU Coding Standards}, for more information on what to put in
 
 @menu
 * Preset Output Variables::     Output variables that are always set
+* Installation Directory Variables::  Other preset output variables
 * Build Directories::           Supporting multiple concurrent compiles
 * Automatic Remaking::          Makefile rules for configuring
 @end menu
 
-@node Preset Output Variables, Build Directories, Makefile Substitutions, Makefile Substitutions
+@node Preset Output Variables, Installation Directory Variables, Makefile Substitutions, Makefile Substitutions
 @subsection Preset Output Variables
 
 Some output variables are preset by the Autoconf macros.  Some of the
 Autoconf macros set additional output variables, which are mentioned in
 the descriptions for those macros.  @xref{Output Variable Index}, for a
-complete list of output variables.  Here is what each of the preset ones
-contains.  @xref{Directory Variables,, Variables for Installation
-Directories, standards, The GNU Coding Standards}, for more information
-about the variables with names that end in @samp{dir}.
+complete list of output variables.  @xref{Installation Directory
+Variables}, for the list of the preset ones related to installation
+directories.  Below are listed the other preset ones.
 
-@defvar bindir
-@ovindex bindir
-The directory for installing executables that users run.
+@c Just say no to ASCII sorting!  We're humans, not computers.
+@c These variables are listed as they would be in a dictionary:
+@c actor
+@c Actress
+@c actress
+
+@defvar CFLAGS
+@ovindex CFLAGS
+Debugging and optimization options for the C compiler.  If it is not set
+in the environment when @code{configure} runs, the default value is set
+when you call @code{AC_PROG_CC} (or empty if you don't).  @code{configure}
+uses this variable when compiling programs to test for C features.
 @end defvar
 
 @defvar configure_input
@@ -1610,6 +1620,101 @@ The presence of that line also reminds people editing the file that it
 needs to be processed by @code{configure} in order to be used.
 @end defvar
 
+@defvar CPPFLAGS
+@ovindex CPPFLAGS
+Header file search directory (@option{-I@var{dir}}) and any other
+miscellaneous options for the C and C++ preprocessors and compilers.  If
+it is not set in the environment when @code{configure} runs, the default
+value is empty.  @code{configure} uses this variable when compiling or
+preprocessing programs to test for C features.
+@end defvar
+
+@defvar CXXFLAGS
+@ovindex CXXFLAGS
+Debugging and optimization options for the C++ compiler.  If it is not
+set in the environment when @code{configure} runs, the default value is
+set when you call @code{AC_PROG_CXX} (or empty if you don't).
+@code{configure} uses this variable when compiling programs to test for
+C++ features.
+@end defvar
+
+@defvar DEFS
+@ovindex DEFS
+@option{-D} options to pass to the C compiler.  If @code{AC_CONFIG_HEADERS}
+is called, @code{configure} replaces @samp{@@DEFS@@} with
+@option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}).  This
+variable is not defined while @code{configure} is performing its tests,
+only when creating the output files.  @xref{Setting Output Variables}, for
+how to check the results of previous tests.
+@end defvar
+
+@defvar ECHO_C
+@defvarx ECHO_N
+@defvarx ECHO_T
+@ovindex ECHO_C
+@ovindex ECHO_N
+@ovindex ECHO_T
+How to suppress the trailing newline from @code{echo} for
+question... answer reports:
+
+@example
+echo $ECHO_N "And the winner is... $ECHO_C"
+sleep 100000000000
+echo "$@{ECHO_T@}dead."
+@end example
+
+@noindent
+Some old and uncommon @code{echo} offer no means to achieve this, in
+which case @code{ECHO_T} is set to tab.  You might not want to use it.
+@end defvar
+
+@defvar FFLAGS
+@ovindex FFLAGS
+Debugging and optimization options for the Fortran 77 compiler.  If it
+is not set in the environment when @code{configure} runs, the default
+value is set when you call @code{AC_PROG_F77} (or empty if you don't).
+@code{configure} uses this variable when compiling programs to test for
+Fortran 77 features.
+@end defvar
+
+@defvar LDFLAGS
+@ovindex LDFLAGS
+Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous
+options for the linker.  If it is not set in the environment when
+@code{configure} runs, the default value is empty.  @code{configure}
+uses this variable when linking programs to test for C features.
+@end defvar
+
+@defvar LIBS
+@ovindex LIBS
+@option{-l} options to pass to the linker.
+@end defvar
+
+@defvar srcdir
+@ovindex srcdir
+The directory that contains the source code for that @file{Makefile}.
+@end defvar
+
+@defvar top_srcdir
+@ovindex top_srcdir
+The top-level source code directory for the package.  In the top-level
+directory, this is the same as @code{srcdir}.
+@end defvar
+
+@node Installation Directory Variables, Build Directories, Preset Output Variables, Makefile Substitutions
+@subsection Installation Directory Variables
+
+The following variables specify the directories where the package will
+be installed, see @ref{Directory Variables,, Variables for Installation
+Directories, standards, The GNU Coding Standards}, for more information.
+See the end of this section for details on when and how to use these
+variables.
+
+@defvar bindir
+@ovindex bindir
+The directory for installing executables that users run.
+@end defvar
+
 @defvar datadir
 @ovindex datadir
 The directory for installing read-only architecture-independent data.
@@ -1671,101 +1776,76 @@ administrators run.
 The directory for installing modifiable architecture-independent data.
 @end defvar
 
-@defvar srcdir
-@ovindex srcdir
-The directory that contains the source code for that @file{Makefile}.
-@end defvar
-
 @defvar sysconfdir
 @ovindex sysconfdir
 The directory for installing read-only single-machine data.
 @end defvar
 
-@defvar top_srcdir
-@ovindex top_srcdir
-The top-level source code directory for the package.  In the top-level
-directory, this is the same as @code{srcdir}.
-@end defvar
 
-@defvar CFLAGS
-@ovindex CFLAGS
-Debugging and optimization options for the C compiler.  If it is not set
-in the environment when @code{configure} runs, the default value is set
-when you call @code{AC_PROG_CC} (or empty if you don't).  @code{configure}
-uses this variable when compiling programs to test for C features.
-@end defvar
+Most of these variables have values which rely on @code{prefix} or
+@code{exec_prefix}.  It is on purpose that the directory output
+variables keep them unexpanded: typically @samp{@@datadir@@} will be
+replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}.
 
-@defvar CPPFLAGS
-@ovindex CPPFLAGS
-Header file search directory (@option{-I@var{dir}}) and any other
-miscellaneous options for the C and C++ preprocessors and compilers.  If
-it is not set in the environment when @code{configure} runs, the default
-value is empty.  @code{configure} uses this variable when compiling or
-preprocessing programs to test for C features.
-@end defvar
+This behavior is mandated by the @sc{gnu} coding standards, so that when
+the user runs:
 
-@defvar CXXFLAGS
-@ovindex CXXFLAGS
-Debugging and optimization options for the C++ compiler.  If it is not
-set in the environment when @code{configure} runs, the default value is
-set when you call @code{AC_PROG_CXX} (or empty if you don't).
-@code{configure} uses this variable when compiling programs to test for
-C++ features.
-@end defvar
+@table @samp
+@item make
+she can still specify a different prefix from the one specified to
+@command{configure}, in which case, if needed, the package shall hard
+code dependencies to her late desires.
+
+@item make install
+she can specify a different installation location, in which case the
+package @emph{must} still depend on the location which were compiled in
+(i.e., never recompile when @samp{make install} is run).  This is an
+extremely important feature, as many people may decide to install all
+the files of a package grouped together, and then install links from
+the final locations to there.
+@end table
 
-@defvar DEFS
-@ovindex DEFS
-@option{-D} options to pass to the C compiler.  If @code{AC_CONFIG_HEADERS}
-is called, @code{configure} replaces @samp{@@DEFS@@} with
-@option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}).  This
-variable is not defined while @code{configure} is performing its tests,
-only when creating the output files.  @xref{Setting Output Variables}, for
-how to check the results of previous tests.
-@end defvar
+In order to support these features, it is essential that @code{datadir}
+remains being defined as @samp{$@{prefix@}/share} to depend upon the
+current value of @code{prefix}.
 
-@defvar ECHO_C
-@defvarx ECHO_N
-@defvarx ECHO_T
-@ovindex ECHO_C
-@ovindex ECHO_N
-@ovindex ECHO_T
-How to suppress the trailing newline from @code{echo} for
-question... answer reports:
+A corollary is that you should not use these variables but in
+Makefiles.  For instance instead of trying to resolve the dependencies
+of @code{datadir} upon @code{prefix} and using
+@samp{AC_DEFINE_UNQUOTED(DATADIR, $datadir)}, you should add
+@samp{-DDATADIR=$(datadir)} to your @code{CFLAGS}.
+
+Similarly you should not rely on @code{AC_OUTPUT_FILES} to replace
+@code{datadir} and friends in your shell scripts and other files, rather
+let @command{make} their replacement.  For instance Autoconf ships
+templates of its shell scripts ending with @samp{.sh}, and uses this
+Makefile snippet:
 
 @example
-echo $ECHO_N "And the winner is... $ECHO_C"
-sleep 100000000000
-echo "$@{ECHO_T@}dead."
+.sh:
+        rm -f $@@ $@@.tmp
+        set 's,@@datadir\@@,$(pkgdatadir),g' $< >$@@.tmp
+        chmod +x $@@.tmp
+        mv $@@.tmp $@@
 @end example
 
-@noindent
-Some old and uncommon @code{echo} offer no means to achieve this, in
-which case @code{ECHO_T} is set to tab.  You might not want to use it.
-@end defvar
+Three things are noteworthy:
 
-@defvar FFLAGS
-@ovindex FFLAGS
-Debugging and optimization options for the Fortran 77 compiler.  If it
-is not set in the environment when @code{configure} runs, the default
-value is set when you call @code{AC_PROG_F77} (or empty if you don't).
-@code{configure} uses this variable when compiling programs to test for
-Fortran 77 features.
-@end defvar
+@table @samp
+@item @@datadir\@@
+The backslash prevents @command{configure} from replacing
+@samp{@@datadir@@}.
 
-@defvar LDFLAGS
-@ovindex LDFLAGS
-Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous
-options for the linker.  If it is not set in the environment when
-@code{configure} runs, the default value is empty.  @code{configure}
-uses this variable when linking programs to test for C features.
-@end defvar
+@item $(pkgdatadir)
+Don't use @samp{@@datadir@@}!
 
-@defvar LIBS
-@ovindex LIBS
-@option{-l} options to pass to the linker.
-@end defvar
+@item ,
+Don't use @samp{/} since most probably @samp{$(pkgdatadir)} will have
+some.
+@end table
 
-@node Build Directories, Automatic Remaking, Preset Output Variables, Makefile Substitutions
+
+@node Build Directories, Automatic Remaking, Installation Directory Variables, Makefile Substitutions
 @subsection Build Directories
 
 You can support compiling a software package for several architectures
@@ -6781,6 +6861,11 @@ object of an @code{AC_REQUIRE} directive, then use @code{define}.  In
 case of doubt, use @code{AC_DEFUN}.  All the @code{AC_REQUIRE}
 statements should be at the beginning of the macro, @code{dnl}'ed.
 
+You should not rely on the number of arguments: instead of checking
+whether an argument is missing, test that it is not empty.  It both
+provides a simpler and more predictable interface to the user, and saves
+room for further arguments.
+
 Unless the macro is short, try to leave the closing @samp{])} at the
 beginning of a line, followed by a comment which repeats the name of the
 macro being defined.  If you want to avoid the new-line which is then