--- automake.texi 2018-02-25 06:13:58.000000000 -0800 +++ automake-new.texi 2018-07-13 18:50:06.000000000 -0700 @@ -967,7 +967,7 @@ In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0} directory from being read-only. In fact VPATH builds are also a means of building packages from a read-only medium such as a CD-ROM. (The -FSF used to sell CD-ROM with unpacked source code, before the GNU +FSF used to sell CD-ROMs with unpacked source code, before the GNU project grew so big.) @node Two-Part Install @@ -1337,7 +1337,7 @@ A typical setup is that package A will distribute one of the libraries it needs in a subdirectory. This library B is a complete package with its own GNU Build System. The @command{configure} script of A will -run the @command{configure} script of B as part of its execution, +run the @command{configure} script of B as part of its execution; building and installing A will also build and install B. Generating a distribution for A will also include B. @@ -1840,7 +1840,7 @@ and the following ``@code{:}'' character, and variable assignments shouldn't be indented with @key{TAB} characters. @c Keep this in sync with doc-parsing-buglets-colneq-subst.sh -Also, using more complex macro in target names can cause trouble: +Also, using more complex macros in target names can cause trouble: @example % @kbd{cat Makefile.am} @@ -1867,7 +1867,7 @@ Similarly, a variable defined in @file{Makefile.am} or @code{AC_SUBST}ed from @file{configure.ac} will override any definition of the variable that @command{automake} would ordinarily -create. This feature is more often useful than the ability to +create. This feature is often more useful than the ability to override a rule. Be warned that many of the variables generated by @command{automake} are considered to be for internal use only, and their names might change in future releases. @@ -1935,7 +1935,7 @@ @table @option @item foreign Automake will check for only those things that are absolutely -required for proper operations. For instance, whereas GNU standards +required for proper operation. For instance, whereas GNU standards dictate the existence of a @file{NEWS} file, it will not be required in this mode. This strictness will also turn off some warnings by default (among them, portability warnings). @@ -2174,7 +2174,7 @@ names, as can happen with above @code{$(data_DATA)} lists, it limits the amount of arguments passed to external commands. -Unfortunately, some system's @command{make} commands may prepend +Unfortunately, some systems' @command{make} commands may prepend @code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user @@ -2296,7 +2296,7 @@ @item missing This wraps a number of programs that are typically only required by -maintainers. If the program in question doesn't exist, or seems to old, +maintainers. If the program in question doesn't exist, or seems too old, @command{missing} will print an informative warning before failing out, to provide the user with more context and information. @@ -2535,10 +2535,10 @@ its dependencies (i.e., @file{aclocal.m4} and any included file), therefore @command{autoconf} must be in your @env{PATH}. If there is an @env{AUTOCONF} variable in your environment it will be used -instead of @command{autoconf}, this allows you to select a particular +instead of @command{autoconf}; this allows you to select a particular version of Autoconf. By the way, don't misunderstand this paragraph: @command{automake} runs @command{autoconf} to @strong{scan} your -@file{configure.ac}, this won't build @file{configure} and you still +@file{configure.ac}; this won't build @file{configure} and you still have to run @command{autoconf} yourself for this purpose. @cindex @command{automake} options @@ -2587,7 +2587,7 @@ @item --print-libdir @opindex --print-libdir Print the path of the installation directory containing Automake-provided -scripts and data files (like e.g., @file{texinfo.texi} and +scripts and data files (e.g., @file{texinfo.texi} and @file{install-sh}). @item -c @@ -3130,7 +3130,7 @@ @code{m4_include} is seldom used by @file{configure.ac} authors, but can appear in @file{aclocal.m4} when @command{aclocal} detects that some required macros come from files local to your package (as opposed to -macros installed in a system-wide directory, @pxref{aclocal Invocation}). +macros installed in a system-wide directory; @pxref{aclocal Invocation}). @end ftable @@ -3179,7 +3179,7 @@ @file{aclocal.m4}. This makes the package smaller, eases dependency tracking, and cause the file to be distributed automatically. (@xref{Local Macros}, for an example.) Any macro that is found in a -system-wide directory, or via an absolute search path will be copied. +system-wide directory or via an absolute search path will be copied. So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever some relative directory should be considered outside the package. @@ -3234,7 +3234,7 @@ @item --diff[=@var{command}] @opindex --diff -Run @var{command} on M4 file that would be installed or overwritten +Run @var{command} on the M4 file that would be installed or overwritten by @option{--install}. The default @var{command} is @samp{diff -u}. This option implies @option{--install} and @option{--dry-run}. @@ -3270,7 +3270,7 @@ @item --force @opindex --force Always overwrite the output file. The default is to overwrite the output -file only when really needed, i.e., when its contents changes or if one +file only when really needed, i.e., when its contents change or if one of its dependencies is younger. This option forces the update of @file{aclocal.m4} (or the file @@ -3290,7 +3290,7 @@ third-party packages to determine where to install @file{.m4} macro files, but @emph{this usage is today discouraged}, since it causes @samp{$(prefix)} not to be thoroughly honored (which violates the -GNU Coding Standards), and a similar semantics can be better obtained +GNU Coding Standards), and similar semantics can be better obtained with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}. @item --verbose @@ -3457,9 +3457,10 @@ @item @code{/usr/local/share/aclocal/} @end enumerate +@noindent 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 +using them to work around local system-dependent tool installation directories. Similarly, @file{dirlist} can be handy if you have installed a local @@ -3557,7 +3558,7 @@ aclocal}) will have to temporarily include all of these third party @file{.m4} files, maybe several times, including even files that are not actually needed. Doing so should alleviate many problems of the -current implementation, however it requires a stricter style from the +current implementation; however it requires a stricter style from the macro authors. Hopefully it is easy to revise the existing macros. For instance, @@ -3599,7 +3600,7 @@ flooded by mails. Another situation where @command{aclocal} is commonly used is to -manage macros that are used locally by the package, @ref{Local +manage macros that are used locally by the package; @ref{Local Macros}. @node Local Macros @@ -3729,7 +3730,7 @@ the older @samp{#serial} line (or the file that has none). Note that a serial number applies to a whole M4 file, not to any macro -it contains. A file can contains multiple macros, but only one +it contains. A file can contain multiple macros, but only one serial. Here is a use case that illustrates the use of @option{--install} and @@ -3763,7 +3764,7 @@ No local macros define @code{AX_THIRD_PARTY} @item @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY} -with serial 1. +with serial @w{number 1}. @end itemize @noindent @@ -3780,10 +3781,10 @@ @file{configure.ac} uses @code{AX_THIRD_PARTY} @item @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY} -with serial 1. +with serial @w{number 1}. @item @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY} -with serial 1. +with serial @w{number 1}. @end itemize @noindent @@ -3799,7 +3800,7 @@ Now suppose the system-wide third-party macro is changed. This can happen if the package installing this macro is updated. Let's suppose -the new macro has serial number 2. The next time @samp{aclocal --install} +the new macro has serial @w{number 2}. The next time @samp{aclocal --install} is run the situation is the following: @itemize @bullet @@ -3807,10 +3808,10 @@ @file{configure.ac} uses @code{AX_THIRD_PARTY} @item @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY} -with serial 1. +with serial @w{number 1}. @item @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY} -with serial 2. +with @w{serial 2}. @end itemize @noindent @@ -3862,7 +3863,7 @@ make that switch more seamless: never call @command{aclocal} yourself. Keep this guy under the exclusive control of @command{autoreconf} and Automake's rebuild rules. Hopefully you won't need to worry about -things breaking, when @command{aclocal} disappears, because everything +things breaking; when @command{aclocal} disappears, because everything will have been taken care of. If otherwise you used to call @command{aclocal} directly yourself or from some script, you will quickly notice the change. @@ -3929,7 +3930,7 @@ defaults, respectively, to the @code{PACKAGE_TARNAME} and @code{PACKAGE_VERSION} defined via the @code{AC_INIT} invocation; @pxref{AC_INIT, , The @code{AC_INIT} macro, autoconf, The Autoconf Manual}); -and this can be still be useful in some selected situations. +and this can still be useful in some selected situations. Our hope is that future Autoconf versions will improve their support for package versions defined dynamically at configure runtime; when (and if) this happens, support for the two-args @code{AM_INIT_AUTOMAKE} @@ -4167,7 +4168,7 @@ new @command{make} instance to build the directory's contents. Because this approach is very widespread, Automake offers built-in -support for it. However, it is worth nothing that the use of make +support for it. However, it is worth noting that the use of make recursion has its own serious issues and drawbacks, and that it's well possible to have packages with a multi directory layout that make little or no use of such recursion (examples of such packages @@ -4254,7 +4255,7 @@ @example % @kbd{cat configure.ac} -AC_INIT([pkg-name], [1.0] +AC_INIT([pkg-name], [1.0]) AM_INIT_AUTOMAKE AM_EXTRA_RECURSIVE_TARGETS([foo]) AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile]) @@ -4283,7 +4284,7 @@ like in the case of GNU Inetutils, you want to only build a subset of the entire package. -To illustrate how this works, let's assume we have two directories +To illustrate how this works, let's assume we have two directories, @file{src/} and @file{opt/}. @file{src/} should always be built, but we want to decide in @command{configure} whether @file{opt/} will be built or not. (For this example we will assume that @file{opt/} should be @@ -4293,11 +4294,11 @@ then maybe in @file{opt/}. However @samp{make dist} should always recurse into both @file{src/} -and @file{opt/}. Because @file{opt/} should be distributed even if it +and @file{opt/}, because @file{opt/} should be distributed even if it is not needed in the current configuration. This means @file{opt/Makefile} should be created @emph{unconditionally}. -There are two ways to setup a project like this. You can use Automake +There are two ways to set up a project like this. You can use Automake conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST} variables (@pxref{Setting Output Variables, , Setting Output Variables, autoconf, The Autoconf Manual}). Using Automake @@ -4452,11 +4453,11 @@ @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS} must be configured. -I.e., the @file{Makefile} must exists or the recursive @command{make} +I.e., 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}. -So that the cleaning rules remove the generated @file{Makefile}s. +This is so the cleaning rules remove the generated @file{Makefile}s. It would be correct to see @code{DIST_SUBDIRS} as a variable that lists all the directories that have been configured. @end itemize @@ -4478,7 +4479,7 @@ distribute these directories). @cindex Subdirectories, not distributed -In few packages, unconfigured directories are not even expected to +In a few packages, unconfigured directories are not even expected to be distributed. Although these packages do not require the aforementioned extra arrangements, there is another pitfall. If the name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS}, @@ -4658,7 +4659,7 @@ 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 looks like a gain in size +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). @@ -4788,7 +4789,7 @@ If you need to link against libraries that are not found by @command{configure}, you can use @code{LDADD} to do so. This variable is used to specify additional objects or libraries to link with; it is -inappropriate for specifying specific linker flags, you should use +inappropriate for specifying specific linker flags; you should use @code{AM_LDFLAGS} for this purpose. @vindex LDADD @vindex AM_LDFLAGS @@ -4908,7 +4909,7 @@ @end example @noindent -You can then setup the @samp{$(HELLO_SYSTEM)} substitution from +You can then set up the @samp{$(HELLO_SYSTEM)} substitution from @file{configure.ac}: @example @@ -4941,7 +4942,7 @@ endif @end example -In this case, @file{configure.ac} should setup the @code{LINUX} +In this case, @file{configure.ac} should set up the @code{LINUX} conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}). When using conditionals like this you don't need to use the @@ -5133,7 +5134,7 @@ determined until @file{./configure} is run: not all platforms support all kinds of libraries, and users can explicitly select which libraries should be built. (However the package's maintainers can -tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL} +tune the default; @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL} macro, libtool, The Libtool Manual}.) @cindex suffix @file{.lo}, defined @@ -5147,7 +5148,7 @@ @file{.lo} files and how libtool constructs them: this is libtool's concern, and the last thing one wants is to learn about libtool's guts. However the existence of these files matters, because they are -used as targets and dependencies in @file{Makefile}s rules when +used as targets and dependencies in @file{Makefile}s' rules when building libtool libraries. There are situations where you may have to refer to these, for instance when expressing dependencies for building source files conditionally (@pxref{Conditional Libtool @@ -5161,7 +5162,7 @@ This offers a portable dlopening facility to load libtool libraries dynamically, and can also achieve static linking where unavoidable. -Before we discuss how to use libtool with Automake in details, it +Before we discuss how to use libtool with Automake in detail, it should be noted that the libtool manual also has a section about how to use Automake with libtool (@pxref{Using Automake, , Using Automake with Libtool, libtool, The Libtool Manual}). @@ -5384,7 +5385,7 @@ @dots{} @end example -When using such setup, beware that @command{automake} will assume +When using such a setup, beware that @command{automake} will assume @file{libtop.la} is to be linked with the C linker. This is because @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as default language. If @code{libtop_la_SOURCES} was not empty, @@ -5412,7 +5413,7 @@ @samp{EXTRA_*_SOURCES} variables are used to keep track of source files that might be compiled (this is mostly useful when doing -conditional compilation using @code{AC_SUBST}, @pxref{Conditional +conditional compilation using @code{AC_SUBST}; @pxref{Conditional Libtool Sources}), and the @code{nodist_} prefix means the listed sources are not to be distributed (@pxref{Program and Library Variables}). In effect the file @file{dummy.cxx} does not need to @@ -5478,7 +5479,7 @@ @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic options include @option{--tag=@var{tag}} and @option{--silent} (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The -Libtool Manual} for more options) should appear before the mode +Libtool Manual} for more options). They should appear before the mode selection on the command line; in @file{Makefile.am}s they should be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable. @@ -5493,7 +5494,7 @@ The libtool rules also use a @code{LIBTOOLFLAGS} variable that should not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag -Variables Ordering}. It allows users to run @samp{make +Variables Ordering}). It allows users to run @samp{make LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of @command{libtool} can also be influenced by the Automake support for silent rules (@pxref{Automake Silent Rules}). @@ -5593,7 +5594,7 @@ A workaround for this issue is to ensure that these two objects get different basenames. As explained in @ref{Renamed Objects}, this -happens automatically when per-targets flags are used. +happens automatically when per-target flags are used. @example bin_PROGRAMS = prog @@ -5746,7 +5747,7 @@ target depends on the contents of such a variable, but no further interpretation is done. -Since these dependencies are associated to the link rule used to +Since these dependencies are associated with the link rule used to create the programs they should normally list files used by the link command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files for programs; @file{*.lo} and @file{*.la} files for Libtool libraries; @@ -5829,7 +5830,7 @@ like @file{sample.c} will be compiled to produce @file{sample.o}. However, if the program's @code{_CFLAGS} variable is set, then the object file will be named, for instance, @file{maude-sample.o}. (See -also @ref{Renamed Objects}). +also @ref{Renamed Objects}.) In compilations with per-target flags, the ordinary @samp{AM_} form of the flags variable is @emph{not} automatically included in the @@ -6132,7 +6133,7 @@ not under @code{$(srcdir)}. This matters especially for packages that use header files placed in sub-directories and want to allow builds outside the source tree (@pxref{VPATH Builds}). In that case we -recommend to use a pair of @option{-I} options, such as, e.g., +recommend using a pair of @option{-I} options, such as, e.g., @samp{-Isome/subdir -I$(srcdir)/some/subdir} or @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}. Note that the reference to the build tree should come before the @@ -6241,7 +6242,7 @@ If a @command{lex} source file is seen, then your @file{configure.ac} must define the variable @code{LEX}. You can use @code{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular Program Checks, -autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro +autoconf, The Autoconf Manual}), but using the @code{AM_PROG_LEX} macro (@pxref{Macros}) is recommended. @vindex LFLAGS @@ -6685,7 +6686,7 @@ @cindex Automatic linker selection @cindex Selecting the linker automatically -When a program or library mixes several languages, Automake choose the +When a program or library mixes several languages, Automake chooses the linker according to the following priorities. (The names in parentheses are the variables containing the link command.) @@ -6886,7 +6887,7 @@ @vtable @code @item VALAC Absolute path to the Vala compiler, or simply @samp{valac} if no -suitable compiler Vala could be found at configure runtime. +suitable Vala compiler could be found at configure runtime. @item VALAFLAGS Additional arguments for the Vala compiler. @@ -6992,6 +6993,7 @@ bin_PROGRAMS = liver @end example +@noindent to this: @example @@ -7169,7 +7171,7 @@ will install the two files as @file{$(includedir)/foo.h} and @file{$(includedir)/bar.h}. -The @code{nobase_} prefix is also supported, +The @code{nobase_} prefix is also supported: @example nobase_include_HEADERS = foo.h bar/bar.h @@ -7424,7 +7426,7 @@ recorded by the normal dependency tracking code. (Note that after this first compilation the dependency tracking code will also have recorded the dependency between @file{foo.o} and -@file{bindir.h}; so our explicit dependency is really useful to +@file{bindir.h}, so our explicit dependency is really useful to the first build only.) Adding explicit dependencies like this can be a bit dangerous if you are @@ -7623,7 +7625,7 @@ Any @file{.java} files listed in a @code{_JAVA} variable will be compiled with @code{JAVAC} at build time. By default, @file{.java} -files are not included in the distribution, you should use the +files are not included in the distribution; you should use the @code{dist_} prefix to distribute them. Here is a typical setup for distributing @file{.java} files and @@ -7696,7 +7698,7 @@ (@file{.pyo}) byte-compiled versions of the source files. Note that because byte-compilation occurs at install time, any files listed in @code{noinst_PYTHON} will not be compiled. Python source files are -included in the distribution by default, prepend @code{nodist_} (as in +included in the distribution by default; prepend @code{nodist_} (as in @code{nodist_python_PYTHON}) to omit them. Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} @@ -7750,7 +7752,7 @@ Assuming @var{action-if-not-found} is used (otherwise @file{./configure} will abort if Python is absent), the value of @code{PYTHON} can be used -to setup a conditional in order to disable the relevant part of a build +to set up a conditional in order to disable the relevant part of a build as follows. @example @@ -8505,7 +8507,7 @@ case if one is packaging from a read-only source tree, or when a @code{make distcheck} is being done. For similar reasons, the recipe shouldn't assume that the subdirectories put into the distribution -directory as effect of having them listed in @code{EXTRA_DIST} are +directory as an effect of having them listed in @code{EXTRA_DIST} are writable. So, if the @code{dist-hook} recipe wants to modify the content of an existing file (or @code{EXTRA_DIST} subdirectory) in the distribution directory, it should explicitly to make it writable first: @@ -8559,7 +8561,7 @@ runs the test suite (with @command{make check}) on this fresh build; @item installs the package in a temporary directory (with @command{make -install}), and tries runs the test suite on the resulting installation +install}), and runs the test suite on the resulting installation (with @command{make installcheck}); @item checks that the package can be correctly uninstalled (by @command{make @@ -8574,7 +8576,7 @@ (where the read-only sources are placed, how the temporary build and install directories are named and how deeply they are nested, etc.) is to be considered an implementation detail, which can change at any time; -so do not reply on it. +so do not rely on it. @vindex AM_DISTCHECK_CONFIGURE_FLAGS @vindex DISTCHECK_CONFIGURE_FLAGS @@ -8599,7 +8601,7 @@ is justified. GNU @command{m4} offers an example. GNU @command{m4} configures by default with its experimental and seldom used "changeword" feature -disabled; so in its case it is useful to have @command{make distcheck} +disabled; so in this case it is useful to have @command{make distcheck} run configure with the @option{--with-changeword} option, to ensure that the code for changeword support still compiles correctly. GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS} @@ -8662,10 +8664,10 @@ The above definition is not the default because it's usually an error if your Makefiles cause some distributed files to be rebuilt when the user -build the package. (Think about the user missing the tool required to +builds the package. (Think about the user missing the tool required to build the file; or if the required tool is built by your package, consider the cross-compilation case where it can't be run.) There is -an entry in the FAQ about this (@pxref{Errors with distclean}), make +an entry in the FAQ about this (@pxref{Errors with distclean}); make sure you read it before playing with @code{distcleancheck_listfiles}. @cindex @samp{make distuninstallcheck} @@ -8804,7 +8806,7 @@ @cindex testsuite harness A @emph{test harness} (also @emph{testsuite harness}) is a program or software component that executes all (or part of) the defined test cases, -analyzes their outcomes, and report or register these outcomes +analyzes their outcomes, and reports or registers these outcomes appropriately. Again, the details of how this is accomplished (and how the developer and user can influence it or interface with it) varies wildly, and we'll attempt no precise definition. @@ -8822,7 +8824,7 @@ 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 an successes. Skips are usually explicitly +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. @@ -8845,7 +8847,7 @@ @cindex Distinction between errors and failures in testsuites Many testing environments and frameworks distinguish between test failures and hard errors. As we've seen, a test failure happens when some invariant -or expected behaviour of the software under test is not met. An @emph{hard +or expected behaviour of the software under test is not met. A @emph{hard error} happens when e.g., the set-up of a test case scenario fails, or when some other unexpected or highly undesirable condition is encountered (for example, the program under test experiences a segmentation fault). @@ -8888,7 +8890,7 @@ @cindex Exit status 99, special interpretation When no test protocol is in use, an exit status of 0 from a test script will denote a success, an exit status of 77 a skipped test, an exit status of 99 -an hard error, and any other exit status will denote a failure. +a hard error, and any other exit status will denote a failure. @cindex Tests, expected failure @cindex Expected test failure @@ -8919,7 +8921,7 @@ possible results (whose meanings should be clear from the previous @ref{Generalities about Testing}) are @code{PASS}, @code{FAIL}, @code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an -example of output from an hypothetical testsuite that uses both plain +example of output from a hypothetical testsuite that uses both plain and TAP tests: @c Keep in sync with tap-doc.sh @example @@ -9011,7 +9013,7 @@ Automake ensures that each file listed in @code{TESTS} is built before it is run; you can list both source and derived programs (or scripts) in @code{TESTS}; the generated rule will look both in @code{srcdir} and -@file{.}. For instance, you might want to run a C program as a test. +'@file{..}'. 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. @@ -9031,7 +9033,7 @@ First, note that today the use of this harness is strongly discouraged in favour of the parallel test harness (@pxref{Parallel Test Harness}). -Still, there are @emph{few} situations when the advantages offered by +Still, there are a @emph{few} situations when the advantages offered by the parallel harness are irrelevant, and when test concurrency can even cause tricky problems. In those cases, it might make sense to still use the serial harness, for simplicity and reliability (we still @@ -9062,7 +9064,7 @@ benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user (@pxref{Parallel Test Harness}). -Another, less serious limit of the serial harness is that it doesn't +Another, less serious limitation of the serial harness is that it doesn't really distinguish between simple failures and hard errors; this is due to historical reasons only, and might be fixed in future Automake versions. @@ -9205,8 +9207,8 @@ Note however that the command above will unconditionally overwrite the @file{test-suite.log} file, thus clobbering the recorded results of any previous testsuite run. This might be undesirable for packages -whose testsuite takes long time to execute. Luckily, this problem can -easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime; +whose testsuite takes a long time to execute. Luckily, this problem can +easily be avoided by also overriding @code{TEST_SUITE_LOG} at runtime; for example, @c Keep in sync with parallel-tests-log-override-2.sh @@ -9286,7 +9288,7 @@ may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS} instead of with @code{check_PROGRAMS}, as the former allows intertwined compilation and test execution (but note that @code{EXTRA_PROGRAMS} are -not cleaned automatically, @pxref{Uniform}). +not cleaned automatically; @pxref{Uniform}). The variables @code{TESTS} and @code{XFAIL_TESTS} may contain conditional parts as well as configure substitutions. In the latter @@ -9341,7 +9343,7 @@ consider the test script exit status (this is done for example by the default test driver used by the parallel test harness, described in the previous section). Other drivers might implement more complex and -advanced test protocols, which might require them to parse and interpreter +advanced test protocols, which might require them to parse and interpret the output emitted by the test script they're running (examples of such protocols are TAP and SubUnit). @@ -9430,7 +9432,7 @@ portability requirements. The main characteristic of these APIs is that they are designed to share -as much infrastructure, semantics, and implementation details as possible +as much infrastructure, semantics, and implementation detail as possible with the parallel test harness and its default driver. @menu @@ -9565,9 +9567,9 @@ This is used to declare the "global result" of the script. Currently, the value of this field is needed only to be reported (more or less verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)}, -so it's quite free-form. For example, a test script which run 10 test +so it's quite free-form. For example, a test script which runs 10 test cases, 6 of which pass and 4 of which are skipped, could reasonably have -a @code{PASS/SKIP} value for this field, while a test script which run +a @code{PASS/SKIP} value for this field, while a test script which runs 19 successful tests and one failed test could have an @code{ALMOST PASSED} value. What happens when two or more @code{:test-global-result:} fields are present in the same @file{.trs} file is undefined behaviour. @@ -9592,7 +9594,7 @@ will contribute with @emph{five} test results to the testsuite summary (three of these tests being successful, one failed, and one skipped), and the content of the corresponding @file{.log} file will @emph{not} be -copied in the global log file @file{test-suite.log}. +copied into the global log file @file{test-suite.log}. @node Testsuite progress output @subsubsection Testsuite progress output @@ -9641,7 +9643,7 @@ fashion (@pxref{Testsuite progress on console}), and will use the @file{.trs} files (@pxref{Basics of test metadata}) to store the test results and related metadata. Apart from that, it will try to remain -as much compatible as possible with pre-existing and widespread utilities, +as compatible as possible with pre-existing and widespread utilities, such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove, @command{prove} utility}, at least for the simpler usages. @@ -9654,9 +9656,9 @@ @samp{Test::Harness::TAP}}. The most relevant real-world usages of TAP are obviously in the testsuites -of @command{perl} and of many perl modules. Still, also other important +of @command{perl} and of many perl modules. Still, other important third-party packages, such as @uref{http://git-scm.com/, @command{git}}, -use TAP in their testsuite. +also use TAP in their testsuite. @node Use TAP with the Automake test harness @subsection Use TAP with the Automake test harness @@ -9671,7 +9673,7 @@ below for clarification. Apart from the options common to all the Automake test drivers -(@pxref{Command-line arguments for test drivers}), the @file{tap-driver.sh} +(@pxref{Command-line arguments for test drivers}), @file{tap-driver.sh} supports the following options, whose names are chosen for enhanced compatibility with the @command{prove} utility. @@ -9683,9 +9685,9 @@ non-zero status. This option has effect also on non-zero exit statuses due to termination by a signal. @item --comments -Instruct the test driver to display TAP diagnostic (i.e., lines beginning +Instruct the test driver to display TAP diagnostics (i.e., lines beginning with the @samp{#} character) in the testsuite progress output too; by -default, TAP diagnostic is only copied to the @file{.log} file. +default, TAP diagnostics are only copied to the @file{.log} file. @item --no-comments Revert the effects of @option{--comments}. @item --merge @@ -9700,13 +9702,13 @@ @item --no-merge Revert the effects of @option{--merge}. @item --diagnostic-string=@var{STRING} -Change the string that introduces TAP diagnostic from the default value +Change the string that introduces TAP diagnostics from the default value of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your TAP-based test scripts produce verbose output on which they have limited control (because, say, the output comes from other tools invoked in the scripts), and it might contain text that gets spuriously interpreted as -TAP diagnostic: such an issue can be solved by redefining the string that -activates TAP diagnostic to a value you know won't appear by chance in +TAP diagnostics: such an issue can be solved by redefining the string that +activates TAP diagnostics to a value you know won't appear by chance in the tests' output. Note however that this feature is non-standard, as the ``official'' TAP protocol does not allow for such a customization; so don't use it if you can avoid it. @@ -9792,7 +9794,7 @@ @subsection Incompatibilities with other TAP parsers and drivers For implementation or historical reasons, the TAP driver and harness as -implemented by Automake have some minors incompatibilities with the +implemented by Automake have some minor incompatibilities with the mainstream versions, which you should be aware of. @itemize @bullet @@ -9804,9 +9806,9 @@ @item The @code{version} and @code{pragma} directives are not supported. @item -The @option{--diagnostic-string} option of our driver allows to modify -the string that introduces TAP diagnostic from the default value -of ``@code{#}''. The standard TAP protocol has currently no way to +The @option{--diagnostic-string} option of our driver allows modification of +the string that introduces TAP diagnostics from the default value +of ``@code{#}''. The standard TAP protocol currently has no way to allow this, so if you use it your diagnostic will be lost to more compliant tools like @command{prove} and @code{Test::Harness} @item @@ -9935,7 +9937,7 @@ @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra dependencies. These variables should be defined in all @file{Makefile}s of the tree (because these two rebuild rules are -output in all them), so it is safer and easier to @code{AC_SUBST} them +output in all of them), so it is safer and easier to @code{AC_SUBST} them from @file{configure.ac}. For instance, the following statement will cause @file{configure} to be rerun each time @file{version.sh} is changed. @@ -10041,7 +10043,7 @@ level and warning categories. As a general rule, strictness-implied warnings are overridden by those specified by explicit options. For example, even if @samp{portability} warnings are disabled by default -in @option{foreign} strictness, an usage like this will end up enabling +in @option{foreign} strictness, a usage like this will end up enabling them: @example @@ -10146,7 +10148,7 @@ be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar} options below. This option should be used in the top-level @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in -@file{configure.ac}, it will be ignored otherwise. It will also be +@file{configure.ac}; it will be ignored otherwise. It will also be ignored in sub-packages of nested packages (@pxref{Subpackages}). @item @option{info-in-builddir} @@ -10326,7 +10328,7 @@ default. This antiquated format is understood by all tar implementations and supports file names with up to 99 characters. When given longer file names some tar implementations will diagnose the -problem while other will generate broken tarballs or use non-portable +problem while others will generate broken tarballs or use non-portable extensions. Furthermore, the V7 format cannot store empty directories. When using this format, consider using the @option{filename-length-max=99} option to catch file names too long. @@ -10334,7 +10336,7 @@ @option{tar-ustar} selects the ustar format defined by POSIX 1003.1-1988. This format is old enough to be portable: As of 2018, it is supported by the native @code{tar} command on -GNU, FreeBSD, NetBSD, OpenBSD, AIX, HP-UX, Solaris, at least. +GNU, FreeBSD, NetBSD, OpenBSD, AIX, HP-UX, and Solaris, at least. It fully supports empty directories. It can store file names with up to 256 characters, provided that the file name can be split at directory separator in two parts, first of them being at most 155 @@ -10346,8 +10348,8 @@ this format is very young and should probably be restricted to packages that target only very modern platforms. As of 2018, this format is supported by the native @code{tar} command only -on GNU, FreeBSD, OpenBSD system; it is not supported by the native -@code{tar} command on NetBSD, AIX, HP-UX, Solaris. +on GNU, FreeBSD, and OpenBSD systems; it is not supported by the native +@code{tar} command on NetBSD, AIX, HP-UX, or Solaris. There are moves to change the pax format in an upward-compatible way, so this option may refer to a more recent version in the future. @@ -10362,6 +10364,7 @@ @item @var{version} @cindex Option, @var{version} A version number (e.g., @samp{0.30}) can be specified. If Automake is not +the same version or newer than the version specified, creation of the @file{Makefile.in} will be suppressed. @@ -10578,7 +10581,7 @@ @cindex Conditionals -Automake supports a simple type of conditionals. +Automake supports a simple type of conditional. These conditionals are not the same as conditionals in GNU Make. Automake conditionals are checked at configure time by the @@ -10606,8 +10609,8 @@ @defmac AM_CONDITIONAL (@var{conditional}, @var{condition}) The conditional name, @var{conditional}, should be a simple string starting with a letter and containing only letters, digits, and -underscores. It must be different from @samp{TRUE} and @samp{FALSE} -that are reserved by Automake. +underscores. It must be different from @samp{TRUE} and @samp{FALSE}, +which are reserved by Automake. The shell @var{condition} (suitable for use in a shell @code{if} statement) is evaluated when @command{configure} is run. Note that you @@ -10813,7 +10816,7 @@ an ``all or nothing'' strategy, i.e., either everything is silenced, or nothing is; this lack of granularity can sometimes be a fatal flaw. Moreover, when the @option{-s} flag is used, the @command{make} output -might turn out to be too much terse; in case of errors, the user won't +might turn out to be too terse; in case of errors, the user won't be able to easily see what rule or command have caused them, or even, in case of tools with poor error reporting, what the errors were! @@ -10825,8 +10828,8 @@ an easy determination of the error location and causes. However, calling @command{make} two times in a row might hide errors -(especially intermittent ones), or subtly change the expected semantic -of the @command{make} calls --- things these which can clearly make +(especially intermittent ones), or subtly change the expected semantics +of the @command{make} calls --- these things can clearly make debugging and error assessment very difficult. @item @command{make --no-print-directory} @@ -10987,7 +10990,7 @@ @vindex @code{AM_DEFAULT_VERBOSITY} @vindex @code{AM_V} @vindex @code{AM_DEFAULT_V} -To extend the silent mode to your own rules, you have few choices: +To extend the silent mode to your own rules, you have a few choices: @itemize @bullet @@ -11001,7 +11004,7 @@ @item You can silence a recipe unconditionally with @code{@@}, and then use the predefined variable @code{AM_V_P} to know whether make is being run -in silent or verbose mode, adjust the verbose information your recipe +in silent or verbose mode; adjust the verbose information your recipe displays accordingly: @example @@ -11302,7 +11305,7 @@ @c Keep in sync with primary-prefix-couples-documented-valid.sh So a @code{foo_SCRIPTS} will be installed by @code{install-data}, and a @code{barexec_SCRIPTS} will be installed by -@code{install-exec}. You should define your hooks consequently. +@code{install-exec}. You should define your hooks accordingly. @c FIXME should include discussion of variables you can use in these @c rules @@ -11387,7 +11390,7 @@ If you have ever used Gettext in a project, this is a good example of how third-party @file{Makefile}s can be used with Automake. The -@file{Makefile}s @command{gettextize} puts in the @file{po/} and +@file{Makefile}s that @command{gettextize} puts in the @file{po/} and @file{intl/} directories are handwritten @file{Makefile}s that implement all of these targets. That way they can be added to @code{SUBDIRS} in Automake packages. @@ -11417,12 +11420,12 @@ live without this (actually, 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 +necessarily require Automake; only Autoconf is needed (@pxref{Build Directories, , Build Directories, autoconf, The Autoconf Manual}). The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@}, and @samp{@@top_builddir@@} are defined by @file{configure} when it processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset -Output Variables, autoconf, The Autoconf Manual}), they are not +Output Variables, autoconf, The Autoconf Manual}); they are not computed by the Makefile like the aforementioned @samp{$(distdir)} and @samp{$(top_distdir)} variables. @@ -11523,7 +11526,7 @@ means you can install several versions of Automake in the same @samp{$prefix}, and can select an arbitrary Automake version by running @command{automake-1.6} or @command{automake-1.7} without juggling with -@samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6 +@samp{$PATH}. Furthermore, @file{Makefile}s generated by Automake 1.6 will use @command{automake-1.6} explicitly in their rebuild rules. The number @samp{1.6} in @command{automake-1.6} is Automake's API version, @@ -11563,7 +11566,7 @@ @heading What is not in the API -Every undocumented variable, target, or command line option, is not part +Every undocumented variable, target, or command line option is not part of the API@. You should avoid using them, as they could change from one version to the other (even in bug fix releases, if this helps to fix a bug). @@ -11575,7 +11578,7 @@ @node Upgrading @chapter Upgrading a Package to a Newer Automake Version -Automake maintains three kind of files in a package. +Automake maintains three kinds of files in a package. @itemize @item @file{aclocal.m4} @@ -11595,7 +11598,7 @@ The usual way to do that is @example -aclocal # with any option needed (such a -I m4) +aclocal # with any option needed (such as -I m4) autoconf automake --add-missing --force-missing @end example @@ -11611,7 +11614,7 @@ overridden by new versions (@pxref{automake Invocation}). It is important to regenerate all of these files each time Automake is -upgraded, even between bug fixes releases. For instance, it is not +upgraded, even between bug fix releases. For instance, it is not unusual for a bug fix to involve changes to both the rules generated in @file{Makefile.in} and the supporting M4 macros copied to @file{aclocal.m4}. @@ -11661,10 +11664,10 @@ generated on the developer's machine and are distributed so that end-users do not have to install the maintainer tools required to rebuild them. Other generated files like Lex scanners, Yacc parsers, -or Info documentation, are usually distributed on similar grounds. +or Info documentation are usually distributed on similar grounds. -Automake output rules in @file{Makefile}s to rebuild these files. For -instance, @command{make} will run @command{autoconf} to rebuild +Automake output generates rules in @file{Makefile}s to rebuild these files. +For instance, @command{make} will run @command{autoconf} to rebuild @file{configure} whenever @file{configure.ac} is changed. This makes development safer by ensuring a @file{configure} is never out-of-date with respect to @file{configure.ac}. @@ -11686,7 +11689,7 @@ However, during @command{cvs update}, files will have the date of the update, not the original timestamp of this revision. This is meant to -make sure that @command{make} notices sources files have been updated. +make sure that @command{make} notices that sources files have been updated. This timestamp shift is troublesome when both sources and generated files are kept under CVS@. Because CVS processes files in lexical @@ -11709,7 +11712,7 @@ @itemize @bullet @item The CVS repository contains all distributed files so you know exactly -what is distributed, and you can checkout any prior version entirely. +what is distributed, and you can check out any prior version entirely. @item Maintainers can see how generated files evolve (for instance, you can @@ -11717,7 +11720,7 @@ and make sure they look OK). @item -Users do not need the autotools to build a checkout of the project, it +Users do not need Autotools to build a check-out of the project; it works just like a released tarball. @item @@ -11735,11 +11738,11 @@ Maintainers interested in keeping their package buildable from a CVS checkout even for those users that lack maintainer-specific tools might -want to provide an helper script (or to enhance their existing bootstrap +want to provide a helper script (or to enhance their existing bootstrap script) to fix the timestamps after a @command{cvs update} or a @command{git checkout}, to prevent spurious rebuilds. In case of a project committing the Autotools-generated -files, as well as the generated @file{.info} files, such script might +files, as well as the generated @file{.info} files, such a script might look something like this: @smallexample @@ -11764,7 +11767,7 @@ @item In distributed development, developers are likely to have different -version of the maintainer tools installed. In this case rebuilds +versions of the maintainer tools installed. In this case rebuilds triggered by timestamp lossage will lead to spurious changes to generated files. There are several solutions to this: @@ -11809,7 +11812,7 @@ This way developers are not annoyed by changes to generated files. It does not matter if they all have different versions (assuming they are -compatible, of course). And finally, timestamps are not lost, changes +compatible, of course). And finally, timestamps are not lost; changes to sources files can't be missed as in the @file{Makefile.am}/@file{Makefile.in} example discussed earlier. @@ -11821,7 +11824,7 @@ 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 released actually. The developer who +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 @@ -11839,7 +11842,7 @@ These files, whether they are kept under CVS or not, raise similar concerns about version mismatch between developers' tools. The -Gettext manual has a section about this, see @ref{CVS Issues, CVS +Gettext manual has a section about this; see @ref{CVS Issues, CVS Issues, Integrating with CVS, gettext, GNU gettext tools}. @node maintainer-mode @@ -11851,7 +11854,7 @@ The @command{missing} script is a wrapper around several maintainer tools, designed to warn users if a maintainer tool is required but missing. Typical maintainer tools are @command{autoconf}, -@command{automake}, @command{bison}, etc. Because file generated by +@command{automake}, @command{bison}, etc. Because files generated by these tools are shipped with the other sources of a package, these tools shouldn't be required during a user build and they are not checked for in @file{configure}. @@ -11864,11 +11867,11 @@ error message like @samp{sh: @var{tool}: command not found}. Similarly, @command{missing} will warn the user if it detects that a maintainer tool it attempted to use seems too old (be warned that diagnosing this -correctly is typically more difficult that detecting missing tools, and +correctly is typically more difficult than detecting missing tools, and requires cooperation from the tool itself, so it won't always work). If the required tool is installed, @command{missing} will run it and -won't attempt to continue after failures. This is correct during +won't attempt to continue after failures. This is correct behavior during development: developers love fixing failures. However, users with missing or too old maintainer tools may get an error when the rebuild rule is spuriously triggered, halting the build. This failure to let @@ -11881,7 +11884,7 @@ @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, +@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 @@ -11894,7 +11897,7 @@ to @command{configure}. People use @code{AM_MAINTAINER_MODE} either because they do not want their -users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or +users (or themselves) annoyed by timestamp lossage (@pxref{CVS}), or because they simply can't stand the rebuild rules and prefer running maintainer tools explicitly. @@ -11905,7 +11908,7 @@ Several years ago Fran@,{c}ois Pinard pointed out several arguments against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to insecurity. By removing dependencies you get non-dependable builds: -changes to sources files can have no effect on generated files and this +changes to source files can have no effect on generated files and this can be very confusing when unnoticed. He adds that security shouldn't be reserved to maintainers (what @option{--enable-maintainer-mode} suggests), on the contrary. If one user has to modify a @@ -11915,8 +11918,8 @@ happens and the user doesn't notice it (this is what happens when rebuild rules are disabled by @code{AM_MAINTAINER_MODE}). -Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was -swayed by Fran@,{c}ois's arguments, and got rid of +Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro, was +swayed by Fran@,{c}ois' arguments, and got rid of @code{AM_MAINTAINER_MODE} in all of his packages. Still many people continue to use @code{AM_MAINTAINER_MODE}, because @@ -12095,8 +12098,8 @@ @end itemize The former left-over files are not distributed, so the fix is to mark -them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve -more explanations. +them for cleaning (@pxref{Clean}); this is obvious and doesn't deserve +more explanation. The latter bug is not always easy to understand and fix, so let's proceed with an example. Suppose our package contains a program for @@ -12142,7 +12145,7 @@ generated, distribute its sources. One way to fix the above example, while still distributing -@file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance, +@file{foo.1}, is to not depend on @file{foo$(EXEEXT)}. For instance, assuming @command{foo --version} and @command{foo --help} do not change unless @file{foo.c} or @file{configure.ac} change, we could write the following @file{Makefile.am}: @@ -12167,7 +12170,7 @@ We could also decide not to distribute @file{foo.1}. In this case it's fine to have @file{foo.1} dependent upon @file{foo$(EXEEXT)}, since both will have to be rebuilt. -However it would be impossible to build the package in a +However, it would be impossible to build the package in a cross-compilation, because building @file{foo.1} involves an @emph{execution} of @file{foo$(EXEEXT)}. @@ -12436,7 +12439,7 @@ @command{make} itself. @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and -has neither @code{AM_} nor per-target cousin. +has neither an @code{AM_} nor a per-target cousin. Finally you should not think that the existence of a per-target variable implies the existence of an @code{AM_} variable or of a user @@ -12496,7 +12499,7 @@ @display One of my source files needs to be compiled with different flags. How -do I do? +do I do that? @end display Automake supports per-program and per-library compilation flags (see @@ -12515,14 +12518,14 @@ compiled with @samp{-some -flags}. (If you wonder about the names of these object files, see @ref{Renamed Objects}.) Note that @code{foo_CFLAGS} gives the flags to use when compiling all the C -sources of the @emph{program} @code{foo}, it has nothing to do with +sources of the @emph{program} @code{foo}; it has nothing to do with @file{foo.c} or @file{foo-foo.o} specifically. What if @file{foo.c} needs to be compiled into @file{foo.o} using some specific flags, that none of the other files requires? Obviously per-program flags are not directly applicable here. Something like per-object flags are expected, i.e., flags that would be used only -when creating @file{foo-foo.o}. Automake does not support that, +when creating @file{foo-foo.o}. Automake does not support that; however this is easy to simulate using a library that contains only that object, and compiling this library with per-library flags. @@ -12905,7 +12908,7 @@ My package needs to populate the installation directory of another package at install-time. I can easily compute that installation directory in @file{configure}, but if I install files therein, -@samp{make distcheck} fails. How else should I do? +@samp{make distcheck} fails. How else should I do it? @end display These two setups share their symptoms: @samp{make distcheck} fails @@ -12937,7 +12940,7 @@ @end example @noindent -by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because +By default @code{sysconfdir} will be @samp{$(prefix)/etc}, because this is what the GNU Standards require. When such a package is installed on an FHS compliant system, the installer will have to set @samp{--sysconfdir=/etc}. As the maintainer of the package you @@ -12957,7 +12960,7 @@ @end example If you indeed use this absolute path to install your shared library, -non-root users will not be able to install the package, hence +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 @@ -12977,10 +12980,10 @@ as Python (you get the behavior of the previous attempt) @item -non-root users can install your package too, they will have the +non-root users can install your package too; they will have the extension module in a place that is not searched by Python but they can work around this using environment variables (and if you installed -scripts that use this shared library, it's easy to tell Python were to +scripts that use this shared library, it's easy to tell Python where to look in the beginning of your script, so the script works in both cases). @end itemize @@ -12989,7 +12992,7 @@ @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}). Of course not all tools are as advanced as Python regarding that -substitution of @var{prefix}. So another strategy is to figure the +substitution of @var{prefix}. So another strategy is to figure out the part of the installation directory that must be preserved. For instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp}) computes @samp{$(lispdir)}: @@ -13015,7 +13018,7 @@ @samp{$@{datadir@}} appropriately. The emacs case looks complicated because it processes a list and -expects two possible layouts, otherwise it's easy, and the benefits for +expects two possible layouts; otherwise it's easy, and the benefits for non-root users are really worth the extra @command{sed} invocation. @@ -13062,8 +13065,8 @@ @item @url{http://bashdb.sourceforge.net/@/remake/} provides a modified GNU @command{make} command called @command{remake} that copes with -complex GNU @command{make}-specific Makefiles and allows to trace -execution, examine variables, and call rules interactively, much like +complex GNU @command{make}-specific Makefiles and allows tracing +execution, examining variables, and calling rules interactively, much like a debugger. @end itemize @@ -13094,7 +13097,7 @@ @uref{http://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 +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.