[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[automake-commit] branch master updated: doc: wording.
|
From: |
Karl Berry |
|
Subject: |
[automake-commit] branch master updated: doc: wording. |
|
Date: |
Tue, 18 May 2021 21:35:09 -0400 |
This is an automated email from the git hooks/post-receive script.
karl pushed a commit to branch master
in repository automake.
View the commit online:
https://git.savannah.gnu.org/gitweb/?p=automake.git;a=commitdiff;h=337c4baedfd782ae86a1202a978fe3df053d41ac
The following commit(s) were added to refs/heads/master by this push:
new 337c4ba doc: wording.
337c4ba is described below
commit 337c4baedfd782ae86a1202a978fe3df053d41ac
Author: Karl Berry <karl@freefriends.org>
AuthorDate: Tue May 18 18:34:56 2021 -0700
doc: wording.
* README:
* t/python-virtualenv.sh:
* doc/automake.texi: wording, typos, etc.
---
README | 10 +-
doc/automake.texi | 331 ++++++++++++++++++++++++-------------------------
t/python-virtualenv.sh | 2 +-
3 files changed, 170 insertions(+), 173 deletions(-)
diff --git a/README b/README
index d992825..c9d0a9e 100644
--- a/README
+++ b/README
@@ -23,11 +23,11 @@ for aclocal is currently found in the Automake manual.
Automake has a test suite. Use "make check" to run it. For more
information, see the file t/README.
-Automake has a page on the web. See:
+Automake's home page:
https://www.gnu.org/software/automake/
-Automake also has three mailing lists:
+Automake has three mailing lists:
* automake@gnu.org
For general discussions of Automake and its interactions with other
@@ -40,8 +40,8 @@ Automake also has three mailing lists:
Where to send patches, and discuss the automake development process
and the design of new features.
-To obtain more information about these list, or to subscribe to them,
-refer to <https://www.gnu.org/software/automake/#mailinglists>
+To see the archives of these lists, or to (un)subscribe to them,
+refer to <https://www.gnu.org/software/automake/#mailinglists>.
New releases are announced to autotools-announce@gnu.org. If you want to
be informed, subscribe to that list by following the instructions at
@@ -52,7 +52,7 @@ the range specifies every single year in that closed interval.
-----
-Copyright (C) 1994-2020 Free Software Foundation, Inc.
+Copyright (C) 1994-2021 Free Software Foundation, Inc.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
diff --git a/doc/automake.texi b/doc/automake.texi
index 0accec8..e6356cd 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -441,10 +441,6 @@ Automake requires @command{perl} in order to generate the
fully GNU standards-compliant, and do not require @command{perl} in order
to be built.
-@cindex Bugs, reporting
-@cindex Reporting bugs
-@cindex E-mail, bug reports
-
For more information on bug reports, @xref{Reporting Bugs}.
@node Autotools Introduction
@@ -1102,8 +1098,8 @@ create output.
For instance when installing GCC, the GNU Compiler Collection, we can
use @option{--target=@/@var{target}} to specify that we want to build
GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
-@option{--target}, we can actually cross-compile a cross-compiler;
-such a three-way cross-compilation is known as a @dfn{Canadian cross}.
+@option{--target}, we can cross-compile a cross-compiler; such a
+three-way cross-compilation is known as a @dfn{Canadian cross}.
@xref{Specifying Names, , Specifying the System Type, autoconf, The
Autoconf Manual}, for more information about these @command{configure}
@@ -1936,7 +1932,7 @@ The strictness levels are:
@opindex --gnu
This is the default level of strictness. Automake will check for
basic compliance with the GNU standards for software packaging.
-@xref{Top,,, standards, The GNU Coding Standards} for full details
+@xref{Top,,, standards, The GNU Coding Standards}, for full details
of these standards. Currently the following checks are made:
@itemize @bullet
@@ -1987,7 +1983,7 @@ Automake will check for compliance to the
as-yet-unwritten @dfn{Gnits
standards}. These are based on the GNU standards, but are even more
detailed. Unless you are a Gnits standards contributor, it is
recommended that you avoid this option until such time as the Gnits
-standard is actually published (which may never happen).
+standard is published (which is unlikely to ever happen).
Currently, @option{--gnits} does all the checks that
@option{--gnu} does, and checks the following as well:
@@ -3249,9 +3245,9 @@ macros installed in a system-wide directory;
@pxref{aclocal Invocation}).
@cindex Invoking @command{aclocal}
@cindex @command{aclocal}, Invoking
-Automake includes a number of Autoconf macros that can be used in
-your package (@pxref{Macros}); some of them are actually required by
-Automake in certain situations. These macros must be defined in your
+Automake includes a number of Autoconf macros that can be used in your
+package (@pxref{Macros}); some of them are required by Automake in
+certain situations. These macros must be defined in your
@file{aclocal.m4}; otherwise they will not be seen by
@command{autoconf}.
@@ -3344,8 +3340,8 @@ This option implies @option{--install} and
@option{--dry-run}.
@item --dry-run
@opindex --dry-run
-Do not actually overwrite (or create) @file{aclocal.m4} and M4
-files installed by @option{--install}.
+Do not overwrite (or create) @file{aclocal.m4} and M4 files installed
+by @option{--install}.
@item --help
@opindex --help
@@ -3689,10 +3685,10 @@ AX_BAR
@end example
Wrapping the @code{AC_PREREQ} call inside the macro ensures that
-Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not actually
-used. Most importantly, quoting the first argument of @code{AC_DEFUN}
-allows the macro to be redefined or included twice (otherwise this
-first argument would be expanded during the second definition). For
+Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not used.
+Most importantly, quoting the first argument of @code{AC_DEFUN} allows
+the macro to be redefined or included twice (otherwise this first
+argument would be expanded during the second definition). For
consistency we like to quote even arguments such as @code{2.68} that
do not require it.
@@ -3742,7 +3738,7 @@ system-wide directories, as explained in @ref{Macro
Search Path}.
Custom macros should be distributed for the same reason that
@file{configure.ac} is: so that other people have all the sources of
-your package if they want to work on it. Actually, this distribution
+your package if they want to work on it. In fact, this distribution
happens automatically because all @code{m4_include}d files are
distributed.
@@ -3976,12 +3972,12 @@ Many packages come with a script called
@file{bootstrap} or
@file{autogen.sh}, that will just call @command{aclocal},
@command{libtoolize}, @command{gettextize} or @command{autopoint},
@command{autoconf}, @command{autoheader}, and @command{automake} in
-the right order. Actually this is precisely what @command{autoreconf}
+the right order. In fact, this is precisely what @command{autoreconf}
can do for you. If your package has such a @file{bootstrap} or
@file{autogen.sh} script, consider using @command{autoreconf}. That
-should simplify its logic a lot (less things to maintain, yum!), it's
-even likely you will not need the script anymore, and more to the point
-you will not call @command{aclocal} directly anymore.
+should simplify its logic a lot (less things to maintain, all to the
+good), it's even likely you will not need the script anymore, and more
+to the point you will not call @command{aclocal} directly anymore.
For the time being, third-party packages should continue to install
public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
@@ -4557,7 +4553,7 @@ which directories listed in the latter should be built.
@item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
must be configured.
-I.e., the @file{Makefile} must exist or the recursive @command{make}
+That is, the @file{Makefile} must exist or the recursive @command{make}
rules will not be able to process the directory.
@item Any configured directory must be listed in @code{DIST_SUBDIRS}.
@@ -4757,14 +4753,14 @@ copies of @file{install-sh}: one in the top-level of
the @code{arm}
package, and another one in the @file{hand/} subdirectory for the
@code{hand} package.
-The historical default is to search for these auxiliary scripts in
-the parent directory and the grandparent directory. So if the
+The historical default is to search for these auxiliary scripts in the
+parent directory and the grandparent directory. So if the
@samp{AC_CONFIG_AUX_DIR([.])} line was removed from
@file{hand/configure.ac}, that subpackage would share the auxiliary
script of the @code{arm} package. This may look like a gain in size
-(a few kilobytes), but it is actually a loss of modularity as the
-@code{hand} subpackage is no longer self-contained (@samp{make dist}
-in the subdirectory will not work anymore).
+(a few kilobytes), but more importantly, it is a loss of modularity as
+the @code{hand} subpackage is no longer self-contained (@samp{make
+dist} in the subdirectory will not work anymore).
Packages that do not use Automake need more work to be integrated this
way. @xref{Third-Party Makefiles}.
@@ -4937,7 +4933,7 @@ this purpose.
@vindex maude_DEPENDENCIES
@vindex EXTRA_maude_DEPENDENCIES
It is also occasionally useful to have a program depend on some other
-target that is not actually part of that program. This can be done
+target that is not in fact part of that program. This can be done
using either the @code{@var{prog}_DEPENDENCIES} or the
@code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on
the contents both variables, but no further interpretation is done.
@@ -5447,7 +5443,7 @@ into one big installed library.
Libtool convenience libraries are declared by directory-less variables
such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
@code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
-not need an @option{-rpath} flag at link time (actually this is the only
+not need an @option{-rpath} flag at link time (this is in fact the only
difference).
Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
@@ -5855,7 +5851,7 @@ the compiler or linker flags). @xref{Libtool Flags}.
@item maude_DEPENDENCIES
@itemx EXTRA_maude_DEPENDENCIES
It is also occasionally useful to have a target (program or library)
-depend on some other file that is not actually part of that target.
+depend on some other file that is not in fact part of that target.
This can be done using the @code{_DEPENDENCIES} variable. Each
target depends on the contents of such a variable, but no further
interpretation is done.
@@ -6269,8 +6265,8 @@ not used, in preference to the per-executable (or
per-library)
@code{_CFLAGS}.
@item COMPILE
-This is the command used to actually compile a C source file. The
-file name is appended to form the complete command line.
+This is the command used to compile a C source file. The file name is
+appended to form the complete command line.
@item AM_LDFLAGS
This is the variable the @file{Makefile.am} author can use to pass
@@ -6278,12 +6274,13 @@ in additional linker flags. In some situations, this
is not used, in
preference to the per-executable (or per-library) @code{_LDFLAGS}.
@item LINK
-This is the command used to actually link a C program. It already
-includes @samp{-o $@@} and the usual variable references (for instance,
-@code{CFLAGS}); it takes as ``arguments'' the names of the object files
-and libraries to link in. This variable is not used when the linker is
-overridden with a per-target @code{_LINK} variable or per-target flags
-cause Automake to define such a @code{_LINK} variable.
+This is the command used to link a C program. It already includes
+@samp{-o $@@} and the usual variable references (for instance,
+@code{CFLAGS}); it takes as ``arguments'' the names of the object
+files and libraries to link in. This variable is not used when the
+linker is overridden with a per-target @code{_LINK} variable or
+per-target flags cause Automake to define such a @code{_LINK}
+variable.
@end vtable
@@ -6465,11 +6462,11 @@ Any flags to pass to the C++ compiler.
The maintainer's variant of @code{CXXFLAGS}.
@item CXXCOMPILE
-The command used to actually compile a C++ source file. The file name
-is appended to form the complete command line.
+The command used to compile a C++ source file. The file name is
+appended to form the complete command line.
@item CXXLINK
-The command used to actually link a C++ program.
+The command used to link a C++ program.
@end vtable
@@ -6500,11 +6497,11 @@ Any flags to pass to the Objective C compiler.
The maintainer's variant of @code{OBJCFLAGS}.
@item OBJCCOMPILE
-The command used to actually compile an Objective C source file. The
-file name is appended to form the complete command line.
+The command used to compile an Objective C source file. The file name
+is appended to form the complete command line.
@item OBJCLINK
-The command used to actually link an Objective C program.
+The command used to link an Objective C program.
@end vtable
@@ -6535,11 +6532,11 @@ Any flags to pass to the Objective C++ compiler.
The maintainer's variant of @code{OBJCXXFLAGS}.
@item OBJCXXCOMPILE
-The command used to actually compile an Objective C++ source file. The
-file name is appended to form the complete command line.
+The command used to compile an Objective C++ source file. The file
+name is appended to form the complete command line.
@item OBJCXXLINK
-The command used to actually link an Objective C++ program.
+The command used to link an Objective C++ program.
@end vtable
@@ -6569,11 +6566,11 @@ Any flags to pass to the Unified Parallel C compiler.
The maintainer's variant of @code{UPCFLAGS}.
@item UPCCOMPILE
-The command used to actually compile a Unified Parallel C source file.
-The file name is appended to form the complete command line.
+The command used to compile a Unified Parallel C source file. The
+file name is appended to form the complete command line.
@item UPCLINK
-The command used to actually link a Unified Parallel C program.
+The command used to link a Unified Parallel C program.
@end vtable
@@ -6641,13 +6638,11 @@ Any flags to pass to the Ratfor compiler.
The maintainer's variant of @code{RFLAGS}.
@item F77COMPILE
-The command used to actually compile a Fortran 77 source file. The file
-name is appended to form the complete command line.
+The command used to compile a Fortran 77 source file. The file name
+is appended to form the complete command line.
@item FLINK
-The command used to actually link a pure Fortran 77 program or shared
-library.
-
+The command used to link a pure Fortran 77 program or shared library.
@end vtable
Automake can handle preprocessing Fortran 77 and Ratfor source files in
@@ -6878,13 +6873,11 @@ Any flags to pass to the Fortran 9x compiler.
The maintainer's variant of @code{FCFLAGS}.
@item FCCOMPILE
-The command used to actually compile a Fortran 9x source file. The file
-name is appended to form the complete command line.
+The command used to compile a Fortran 9x source file. The file name
+is appended to form the complete command line.
@item FCLINK
-The command used to actually link a pure Fortran 9x program or shared
-library.
-
+The command used to link a pure Fortran 9x program or shared library.
@end vtable
@menu
@@ -7148,9 +7141,9 @@ the @option{no-exeext} option, this use will give a
diagnostic.
@node Other Objects
@chapter Other Derived Objects
-Automake can handle derived objects that are not C programs. Sometimes
-the support for actually building such objects must be explicitly
-supplied, but Automake will still automatically handle installation and
+Automake can handle derived objects that are not C programs.
+Sometimes the support for building such objects must be explicitly
+supplied, but Automake can still automatically handle installation and
distribution.
@menu
@@ -7301,7 +7294,7 @@ will install the two files as @file{$(includedir)/foo.h}
and
Usually, only header files that accompany installed libraries need to
be installed. Headers used by programs or convenience libraries are
not installed. The @code{noinst_HEADERS} variable can be used for
-such headers. However when the header actually belongs to a single
+such headers. However, when the header belongs to a single
convenience library or program, we recommend listing it in the
program's or library's @code{_SOURCES} variable (@pxref{Program
Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
@@ -7393,12 +7386,12 @@ So, to conclude our introductory example, we could use
any other target (including @file{foo.o}) during @samp{make all} or
@samp{make check}.
-@code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
-must be created early in the build process can be listed in this
-variable. Moreover, all built sources do not necessarily have to be
-listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
-doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
-another source), because it's a known dependency of the associated
+@code{BUILT_SOURCES} is a bit of a misnomer, as any file which must be
+created early in the build process can be listed in this variable.
+Moreover, all built sources do not necessarily have to be listed in
+@code{BUILT_SOURCES}. For instance, a generated @file{.c} file
+doesn't need to appear in @code{BUILT_SOURCES} (unless it is included
+by another source), because it's a known dependency of the associated
object.
To emphasize, @code{BUILT_SOURCES} is honored only by @samp{make all},
@@ -7662,7 +7655,7 @@ will be passed to the Emacs invocation.
Byte-compiled Emacs Lisp files are not portable among all versions of
Emacs, so it makes sense to turn this off if you expect sites to have
more than one version of Emacs installed. Furthermore, many packages
-don't actually benefit from byte-compilation. Still, we recommend
+do not actually benefit from byte-compilation. Still, we recommend
that you byte-compile your Emacs Lisp sources. It is probably better
for sites with strange setups to cope for themselves than to make the
installation less nice for everybody else.
@@ -8049,10 +8042,11 @@ file for each Texinfo file. Automake will treat any
include in a
Texinfo file that matches @file{vers*.texi} just as an automatically
generated version file.
-Sometimes an info file actually depends on more than one @file{.texi}
-file. For instance, in GNU Hello, @file{hello.texi} includes the file
+Often an Info file depends on more than one @file{.texi} file. For
+instance, in GNU Hello, @file{hello.texi} includes the file
@file{fdl.texi}. You can tell Automake about these dependencies using
-the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
+the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does
+it:
@vindex TEXINFOS
@vindex _TEXINFOS
@@ -8272,10 +8266,10 @@ notrans_dist_man3_MANS = bar.3
@cindex Installation support
@cindex @samp{make install} support
-Naturally, Automake handles the details of actually installing your
-program once it has been built. All files named by the various
-primaries are automatically installed in the appropriate places when the
-user runs @samp{make install}.
+Naturally, Automake handles the details of installing your program
+once it has been built. All files named by the various primaries are
+automatically installed in the appropriate places when the user runs
+@samp{make install}.
@menu
* Basics of Installation:: What gets installed where
@@ -8546,18 +8540,19 @@ program used; it defaults to @code{tar}.
@acindex m4_include
@cmindex include
For the most part, the files to distribute are automatically found by
-Automake: all source files are automatically included in a distribution,
-as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
-has a built-in list of commonly used files that are automatically
-included if they are found in the current directory (either physically,
-or as the target of a @file{Makefile.am} rule); this list is printed by
-@samp{automake --help}. Note that some files in this list are actually
-distributed only if other certain conditions hold (for example,
+Automake: all source files are automatically included in a
+distribution, as are all @file{Makefile.am} and @file{Makefile.in}
+files. Automake also has a built-in list of commonly used files that
+are automatically included if they are found in the current directory
+(either physically, or as the target of a @file{Makefile.am} rule);
+this list is printed by @samp{automake --help}. However, some files
+in this list are distributed only if other certain conditions hold
+(for example,
@c Keep in sync with autodist-config-headers.sh
the @file{config.h.top} and @file{config.h.bot} files are automatically
distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
in @file{configure.ac}). Also, files that are read by @command{configure}
-(i.e.@: the source files corresponding to the files specified in various
+(i.e., the source files corresponding to the files specified in various
Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
automatically distributed. Files included in a @file{Makefile.am} (using
@code{include}) or in @file{configure.ac} (using @code{m4_include}), and
@@ -8989,13 +8984,13 @@ determine that such condition of behaviour does
@emph{not} hold.
@cindex test skip
Sometimes, tests can rely on non-portable tools or prerequisites, or
simply make no sense on a given system (for example, a test checking a
-Windows-specific feature makes no sense on a GNU/Linux system). In this
-case, accordingly to the definition above, the tests can neither be
-considered passed nor failed; instead, they are @emph{skipped}- --i.e.,
-they are not run, or their result is anyway ignored for what concerns
-the count of failures and successes. Skips are usually explicitly
-reported though, so that the user will be aware that not all of the
-testsuite has really run.
+Windows-specific feature makes no sense on a GNU/Linux system). In
+this case, accordingly to the definition above, the tests can neither
+be considered passed nor failed; instead, they are @emph{skipped},
+that is, they are not run, or their result is in any case ignored for
+what concerns the count of failures and successes. Skips are usually
+explicitly reported though, so that the user will be aware that not
+all of the testsuite has really run.
@cindex xfail
@cindex expected failure
@@ -9634,10 +9629,10 @@ invocations of @code{@var{ext}_LOG_DRIVER}.
@node API for Custom Test Drivers
@subsection API for Custom Test Drivers
-Note that @emph{the APIs described here are still highly experimental},
-and will very likely undergo tightenings and likely also extensive changes
-in the future, to accommodate for new features or to satisfy additional
-portability requirements.
+Note that @emph{the APIs described here are still highly
+experimental}, and will very likely undergo tightening and possibly
+extensive changes in the future, to accommodate for new features or to
+satisfy additional portability requirements.
The main characteristic of these APIs is that they are designed to share
as much infrastructure, semantics, and implementation detail as possible
@@ -11116,7 +11111,7 @@ func.c:4:3: warning: ‘i’ used uninitialized in this
function
mv -f .deps/func.Tpo .deps/func.Po
gcc -Wall -o foo main.o func.o
-@i{Clean up, so that we we can rebuild everything from scratch.}
+@i{Clean up, so that we can rebuild everything from scratch.}
% @kbd{make clean}
test -z "foo" || rm -f foo
rm -f *.o
@@ -11578,7 +11573,7 @@ they support VPATH builds (@pxref{VPATH Builds}).
Obviously if the
subpackage does not support VPATH builds the whole package will not
support VPATH builds. This in turns means that @samp{make distcheck}
will not work, because it relies on VPATH builds. Some people can
-live without this (actually, many Automake users have never heard of
+live without this (indeed, many Automake users have never heard of
@samp{make distcheck}). Other people may prefer to revamp the
existing @file{Makefile}s to support VPATH@. Doing so does not
necessarily require Automake; only Autoconf is needed (@pxref{Build
@@ -11602,11 +11597,11 @@ required targets and includes the third-party
@file{Makefile}. For
this to work in VPATH builds, @file{GNUmakefile} must lie in the build
directory; the easiest way to do this is to write a
@file{GNUmakefile.in} instead, and have it processed with
-@code{AC_CONFIG_FILES} from the outer package. For example if we
+@code{AC_CONFIG_FILES} from the outer package. For example, if we
assume @file{Makefile} defines all targets except the documentation
-targets, and that the @code{check} target is actually called
-@code{test}, we could write @file{GNUmakefile} (or
-@file{GNUmakefile.in}) like this:
+targets, and that the real @code{check} target is named @code{test},
+we could write @file{GNUmakefile} (or @file{GNUmakefile.in}) like
+this:
@example
# First, include the real Makefile
@@ -11985,11 +11980,11 @@ But, after all, CVS's job is versioning, not
distribution.
Allowing developers to use different versions of their tools can also
hide bugs during distributed development. Indeed, developers will be
using (hence testing) their own generated files, instead of the
-generated files that will be actually released. The developer who
-prepares the tarball might be using a version of the tool that
-produces bogus output (for instance a non-portable C file), something
-other developers could have noticed if they weren't using their own
-versions of this tool.
+generated files that will be released. The developer who prepares the
+tarball might be using a version of the tool that produces bogus
+output (for instance a non-portable C file), something other
+developers could have noticed if they weren't using their own versions
+of this tool.
@subheading Third-party Files
@cindex CVS and third-party files
@@ -12046,12 +12041,12 @@ the build continue is one of the arguments of the
@code{AM_MAINTAINER_MODE} allows you to choose whether the so called
"rebuild rules" should be enabled or disabled. With
@code{AM_MAINTAINER_MODE([enable])}, they are enabled by default;
-otherwise they are disabled by default. In the latter case, if
-you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
-@samp{./configure && make}, then @command{make} will *never* attempt to
-rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
-I.e., this disables build rules for files that are usually distributed
-and that users should normally not have to update.
+otherwise they are disabled by default. In the latter case, if you
+have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
+@samp{./configure && make}, then @command{make} will *never* attempt
+to rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs,
+etc. That is, this disables build rules for files that are usually
+distributed and that users should normally not have to update.
The user can override the default setting by passing either
@samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
@@ -12437,17 +12432,17 @@ flags, not appended.
@cindex @code{YFLAGS} and @code{AM_YFLAGS}
This section attempts to answer all the above questions. We will
-mostly discuss @code{CPPFLAGS} in our examples, but actually the
-answer holds for all the compile flags used in Automake:
-@code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
-@code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
-@code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS},
+mostly discuss @code{CPPFLAGS} in our examples, but the answer holds
+for all the compile flags used in Automake: @code{CCASFLAGS},
+@code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS}, @code{FCFLAGS},
+@code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS}, @code{LFLAGS},
+@code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS},
@code{RFLAGS}, @code{UPCFLAGS}, and @code{YFLAGS}.
@code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
-three variables that can be used to pass flags to the C preprocessor
-(actually these variables are also used for other languages like C++
-or preprocessed Fortran). @code{CPPFLAGS} is the user variable
+three variables that can be used to pass flags to the C preprocessor (
+these variables are also used for other languages like C++ or
+preprocessed Fortran). @code{CPPFLAGS} is the user variable
(@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
and @code{mumble_CPPFLAGS} is the variable specific to the
@code{mumble} target (we call this a per-target variable,
@@ -12584,7 +12579,7 @@ users.
Finally, we have avoided naming the variable of the example
@code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
-Automake to think that this is actually a per-target variable (like
+Automake to think that this is a per-target variable (like
@code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
@subheading Other Variables
@@ -12639,10 +12634,9 @@ cannot be built with both @samp{-DEXIT_CODE=0}
@emph{and}
build two different objects: @file{true-generic.o} and
@file{false-generic.o}.
-@command{automake} doesn't actually look whether source files are
-shared to decide if it must rename objects. It will just rename all
-objects of a target as soon as it sees per-target compilation flags
-used.
+Automake doesn't actually determine whether source files are shared to
+decide if it must rename objects. It just renames all objects of a
+target as soon as it sees that per-target compilation flags are used.
It's OK to share object files when per-target compilation flags are not
used. For instance, @file{true} and @file{false} will both use
@@ -12896,10 +12890,10 @@ that @file{data.h} is created before @file{data.c}.
Then we have a
weird situation. The next time @command{make} is run, @file{data.h}
will appear older than @file{data.c}, the second rule will be
triggered, a shell will be started to execute the @samp{if@dots{}fi}
-command, but actually it will just execute the @code{then} branch,
-that is: nothing. In other words, because the witness we selected is
-not the first file created by @command{foo}, @command{make} will start
-a shell to do nothing each time it is run.
+command, but it will just execute the @code{then} branch, that is:
+nothing. In other words, because the witness we selected is not the
+first file created by @command{foo}, @command{make} will start a shell
+to do nothing each time it is run.
A simple riposte is to fix the timestamps when this happens.
@@ -13140,8 +13134,8 @@ non-root users will not be able to install the package;
hence
distcheck fails.
Let's do better. The @samp{sysconfig.get_python_lib()} function
-actually accepts a third argument that will replace Python's
-installation prefix.
+accepts a third argument that will replace Python's installation
+prefix.
@example
% @kbd{python -c 'from distutils import sysconfig;
@@ -13188,7 +13182,7 @@ lispdir=`sed -n
conftest.out`
@end example
-I.e., it just picks the first directory that looks like
+That is, it just picks the first directory that looks like
@file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
the search path of emacs, and then substitutes @samp{$@{libdir@}} or
@samp{$@{datadir@}} appropriately.
@@ -13215,29 +13209,33 @@ generated by @command{automake} effectively:
If less verbose output has been enabled in the package with the use
of silent rules (@pxref{Automake Silent Rules}), you can use
@code{make V=1} to see the commands being executed.
+
@item
@code{make -n} can help show what would be done without actually doing
-it. Note however, that this will @emph{still execute} commands prefixed
-with @samp{+}, and, when using GNU @command{make}, commands that contain
+it. However, this will @emph{still execute} commands prefixed with
+@samp{+}, and, when using GNU @command{make}, commands that contain
the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
-Execution,,, make, The GNU Make Manual}).
-Typically, this is helpful to show what recursive rules would do, but it
-means that, in your own rules, you should not mix such recursion with
-actions that change any files.@footnote{Automake's @samp{dist} and
-@samp{distcheck} rules had a bug in this regard in that they created
-directories even with @option{-n}, but this has been fixed in Automake
-1.11.} Furthermore, note that GNU @command{make} will update
-prerequisites for the @file{Makefile} file itself even with @option{-n}
-(@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
+Execution,,, make, The GNU Make Manual}). Typically, this is helpful
+to show what recursive rules would do, but it means that, in your own
+rules, you should not mix such recursion with actions that change any
+files.@footnote{Automake's @samp{dist} and @samp{distcheck} rules had
+a bug in this regard in that they created directories even with
+@option{-n}, but this has been fixed in Automake 1.11.} Furthermore,
+note that GNU @command{make} will update prerequisites for the
+@file{Makefile} file itself even with @option{-n} (@pxref{Remaking
+Makefiles,,, make, The GNU Make Manual}).
+
@item
@code{make SHELL="/bin/bash -vx"} can help debug complex rules.
@xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
portability quirks associated with this construct.
+
@item
@code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
can be handy to examine the expanded value of variables. You may need
to use a target other than @samp{print} if that is already used or a
file with that name exists.
+
@item
@url{http://bashdb.sourceforge.net/@/remake/} provides a modified
GNU @command{make} command called @command{remake} that copes with
@@ -13250,38 +13248,37 @@ a debugger.
@node Reporting Bugs
@section Reporting Bugs
-Most nontrivial software has bugs. Automake is no exception. Although
-we cannot promise we can or will fix a bug, and we might not even agree
-that it is a bug, we want to hear about problems you encounter. Often we
-agree they are bugs and want to fix them.
+@cindex Bugs, reporting
+@cindex Reporting bugs
-To make it possible for us to fix a bug, please report it. In order to
-do so effectively, it helps to know when and how to do it.
+Most nontrivial software has bugs. Automake is no exception. We
+cannot promise we can or will fix a bug, and we might not even agree
+that it is a bug, but we want to hear about problems you
+encounter. Often we agree they are bugs and want to fix them.
-Before reporting a bug, it is a good idea to see if it is already known.
+So, to make it possible for us to fix a bug, please report it.
+If you can, though, it is helpful if you check if it is already known.
You can look at the @uref{https://debbugs.gnu.org/, GNU Bug Tracker}
and the @uref{https://lists.gnu.org/@/archive/@/html/@/bug-automake/,
-bug-automake mailing list archives} for previous bug reports. We
+bug-automake mailing list archives} for previous bug reports. (We
previously used a Gnats database for bug tracking, but it is no longer
-online.
+online.)
-If the bug is not already known, it should be reported. It is very
-important to report bugs in a way that is useful and efficient. For
-this, please familiarize yourself with
-@uref{https://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
-Report Bugs Effectively} and
+If the bug is not already known, it should be reported. To report
+bugs in a way that is useful and efficient, please read
+@uref{https://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How
+to Report Bugs Effectively} and
@uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
-Questions the Smart Way}. This helps you and developers to save time,
-which can then be spent on fixing more bugs and implementing more
-features.
+Questions the Smart Way}. Good bug reports save time for everyone.
For a bug report, a feature request or other suggestions, please send
email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
bug in the @uref{https://debbugs.gnu.org/@/automake, bug tracker}. Be
-sure to include the versions of Autoconf and Automake that you use.
-Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
-reproduces the problem you encounter. If you have encountered test
-suite failures, please attach the @file{test-suite.log} file.
+sure to include the versions of Autoconf and Automake that you use and
+the kind of system you're on. Ideally, post a minimal
+@file{Makefile.am} and @file{configure.ac} that reproduces the problem
+you encounter. If you have encountered test suite failures, please
+attach the @file{test-suite.log} file.
@c ========================================================== Appendices
diff --git a/t/python-virtualenv.sh b/t/python-virtualenv.sh
index 05df22b..46a5498 100644
--- a/t/python-virtualenv.sh
+++ b/t/python-virtualenv.sh
@@ -46,7 +46,7 @@ cwd=$(pwd) || fatal_ "getting current working directory"
py_version=$(python -c 'import sys; print("%u.%u" %
tuple(sys.version_info[:2]))')
py_site=$VIRTUAL_ENV/lib/python$py_version/site-packages
-# We need to do do this early, just to set some cache variables properly,
+# We need to do this early, just to set some cache variables properly,
# since because we're going to unset $PYTHON next.
if python_has_pep3147; then
: PEP 3147 will be used in installation of ".pyc" files
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [automake-commit] branch master updated: doc: wording.,
Karl Berry <=