Re: RFC: "Autotools Introduction" chapter draft (16 pages long)

[Ralf Wildenhues]

[ moving from automake to &-patches list ]

Hello Alexandre,

* Alexandre Duret-Lutz wrote on Sat, Aug 12, 2006 at 11:45:50PM CEST:
> 
> Over the last weeks I've been writing an introductory chapter
> for the Automake manual.  Now I could use some proofreading
> eyes, especially since I'm a foreigner.  Other suggestions
> welcome too, of course.

Well, first a big thanks for your work.  It looks very nice in general.

> I'm not yet 100% sure how to plug this chapter into the existing
> documentation.  Presently, I've inserted it right after the
> first chapter that introduces Automake.

That seems like a good choice to me.

> Introducing Automake
> before Introducing the Autotools may sound weird, but I thing
> that it is nice to have a very short chapter giving the reader a
> sense of what Automake is about (even if that can be mostly
> Chinese to some newcomer) before talking about the GNU Build
> System and the Autotools in general.

Agreed.

> I'm undecided whether I should mention this tutorial in the
> manual.  Some people who commented on the tutorial suggested I
> did this, but I feared it might not be very diplomatic to decide
> that this tutorial was worth being mentioned and not
> others...

Well.  I'm in favor of a link to your manual, if only because I may have
to mention it less often in the long run.  I see your point about
diplomaticity; however, for one you do link lots of other tutorials from
its site, and for another I have yet to look at another tutorial that is
not using somewhat older notation.

BTW, speaking about the manual: could you please (allow me to) update or
remove the online manual at http://www.gnu.org/software/automake/manual/
and try to fix the set of broken links from therein?  I've asked this a
few months ago, prompted by a couple of bug reports.


Here's to the new chapter.  FWIW, I would have preferred texinfo (or
other "source representation" to be able to check formatting errors as
well; oh well.  I hope you don't mind some remarks to parts of the text,
and a simple unified diff for the more trivial parts.

A couple of notes: the proposed new chapter as well as the manual as a
whole consist of more-or-less en_US spelling, interspersed with some
en_UK words; I "fixed" them to be en_US (find in another mail a patch
for typos in the manual) for consistency.  Then, I am not a native speaker
(nitpick: you are not a "foreigner", or rather, that's not what you meant)
either, and I tend to add more commas than necessary (probably stemming
from German rules; I do believe most of those are ok to add, though).

The Autoconf manual has begun to use the convention to speak of
makefiles, when speaking about the general concept, and @file{Makefile}
when speaking about the specific file.  I don't know if Automake wants
to follow that?

Cheers,
Ralf

> 2.2.1 Basic Installation
> ------------------------
> 
> The most common installation procedure looks as follows.
> 
>      ~ % tar zxf amhello-1.0.tar.gz

Here (and elsewhere) you use `tar z...' freely instead of piping through
gzip, although that is not a feature of portable tar.  I wonder whether
the manual should use portable notation for tools used, or at least note
the GNUisms.  In any case, it would not seem fortunate to praise
portability on one hand and then use unportable constructs (without
marking so clearly) on the other hand.


> 2.2.2 Standard `Makefile' Targets
> ---------------------------------
> 
> So far we have come across four ways to run `make' in the GNU Build
> System: `make', `make check', `make install', and `make installcheck'.
> The words `check', `install', and `installcheck', passed as argument to
> `make' are called "targets".  `make' is a shorthand for `make all',
> `all' being the default target.

This looks just slightly confusing to me (because I once used to believe
"all" being the default target was a feature of `make', not of Automake.
Maybe better
  `make' are called "targets".  `make' is a shorthand for `make all',
  `all' being the default target in makefiles created by Automake.


> 2.2.6 Parallel Build Trees (a.k.a. VPATH Builds)
> ------------------------------------------------
[...]
>    These setups, where source and build trees are different, are often
> called "parallel builds" or "VPATH builds".  The word _parallel_ is a
> reference to the way the build tree shadows the source tree, it is not
> about some concurrency in the way build commands are run.  _VPATH_ is
> the name of the `make' feature used by the `Makefile's to allow these
> builds (*note `VPATH': Search Path for All Prerequisites: (make)General
> Search.).

I find the naming `parallel' very unfortunate, as it is used elsewhere
in the manual (and elsewhere in the computing world) with a different
meaning.  If only for the former, one could rename the other meaning as
concurrent; but that would require changes in the rest of the manual.


> 2.2.8 Cross Compilation
> -----------------------

I think the notation cross-compilation (with a hyphen) should be used
throughout; the patch below changes this.


> 2.2.10 Building Binary Packages Using DESTDIR
> ---------------------------------------------
> 
> The GNU build system's `make install' and `make uninstall' interface
> does not exactly fits the needs of a system administrator who has to
> deploy and upgrade packages on lots of hosts.  In other words, the GNU
> build system does not replace a package manager.

Hmm.  Maybe this introduction could be improved; does not help too much
to motivate DESTDIR.

> location (e.g., `--prefix /usr'), but when running `make install' the
> `DESTDIR' should be set to the name of an empty directory in which all

I don't see any reason for DESTDIR to point to an empty directory.  In
fact, I think it is very useful to be able to install several packages
with an identical DESTDIR setting.  (Not that this always works well,
especially with Libtool in the game, but that doesn't mean that it
should not work well.)  The patch below suggests a change to:

  [...] the `DESTDIR' should be set to the name of a path prefix below
  which all the installation will be diverted.


> 2.2.12 Automatic Dependency Tracking
> ------------------------------------
[...]
> `--enable-dependency-tracking'
>      Do not reject slow dependency extractors.
> 
>    *Note Dependency Tracking Evolution::, for some discussion about the
> different dependency tracking schemes used by Automake over the years.

This section should be cross-linked _from_ the current manual parts
about dependency tracking, as it explains some concepts better. 


Here's a diff for some more trivial issues:

--- intro.txt   2006-08-14 18:33:00.000000000 +0200
+++ intro.txt   2006-08-14 20:01:31.000000000 +0200
@@ -470,7 +470,7 @@
 from, and is populated with all object files, programs, libraries, and
 other derived files built from the sources (and hence not distributed).
 The build tree usually has the same subdirectory layout as the source
-tree; these subdirectories are created automatically by the build
+tree; there, subdirectories are created automatically by the build
 system.
 
    If `configure' is executed in its own directory, the source and
@@ -516,21 +516,21 @@
      ...
 
    With network file systems, a similar approach can be used to build
-the same sources on different machines.  For instance suppose that the
-sources are installed on a directory shared by two hosts: `HOST1' and
+the same sources on different machines.  For instance, suppose that the
+sources are installed on a directory shared by two hosts `HOST1' and
 `HOST2', maybe different platforms.
 
      ~ % cd /nfs/src
      /nfs/src % tar zxf ~/amhello-1.0.tar.gz
 
-   On the first host you could create a local build directory:
+   On the first host, you could create a local build directory:
      [HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh
      [HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure
      ...
      [HOST1] /tmp/amh % make && sudo make install
      ...
 
-   On the second host, you would do exactly the same, possibly at same
+   On the second host, you would do exactly the same, possibly at the same
 time:
      [HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh
      [HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure
@@ -539,7 +539,7 @@
      ...
 
    In this scenario, nothing forbids the `/nfs/src/amhello-1.0'
-directory from being read-only.  In fact VPATH builds are also a means
+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
 project grew so big.)
@@ -559,16 +559,16 @@
 
    These targets are `install-exec' for architecture-dependent files
 and `install-data' for architecture-independent files.  The command we
-used up to now, `make install', can be thought as a shorthand for `make
+used up to now, `make install', can be thought of as a shorthand for `make
 install-exec install-data'.
 
    From the GNU Build System point of view, the distinction between
 architecture-dependent files and architecture-independent files is
 based exclusively on the directory variable used to specify their
 installation destination.  In the list of directory variables we
-provided earlier (*note Standard Directory Variables::) all the
+provided earlier (*note Standard Directory Variables::), all the
 variables based on EXEC-PREFIX designate architecture-dependent
-directories whose files will be installed by `make install-exec'.  The
+directories, whose files will be installed by `make install-exec'.  The
 others designate architecture-independent directories and will serve
 files installed by `make install-data'.  *Note Install::, for more
 details.
@@ -596,12 +596,12 @@
 `make installcheck' (*note Basic Installation::) to verify that the
 package works correctly despite the apparent partial installation.
 
-2.2.8 Cross Compilation
+2.2.8 Cross-Compilation
 -----------------------
 
-To "cross compile" is to build on one platform a binary that will be
+To "cross-compile" is to build on one platform a binary that will be
 run on another platform.  When speaking of cross-compilation, it is
-important to distinguish between the "build platform" one which the
+important to distinguish between the "build platform" on which the
 compilation is performed, and the "host platform" on which the
 resulting executable is expected to run.  The following `configure'
 options are used to specify each of them:
@@ -612,14 +612,14 @@
 `--host=HOST'
      The system where built programs & libraries will run.
 
-   When the `--host' is used, `configure' will search for the cross
-compiling suite for this platform.  Cross compilation tools have their
-target architecture as prefix of their name.  For instance my cross
+   When the `--host' is used, `configure' will search for the cross-
+compiling suite for this platform.  Cross compilation tools commonly have their
+host architecture as prefix of their name.  For instance, my cross
 compiler for MinGW32 has its binaries called `i586-mingw32msvc-gcc',
 `i586-mingw32msvc-ld', `i586-mingw32msvc-as', etc.
 
    Here is how we could build `amhello-1.0' for `i586-mingw32msvc' on a
-GNU/Linux PC.
+GNU/Linux system.
 
      ~/amhello-1.0 % ./configure --build i686-pc-linux-gnu --host 
i586-mingw32msvc
      checking for a BSD-compatible install... /usr/bin/install -c
@@ -666,7 +666,7 @@
 The GNU build system provides means to automatically rename executables
 before they are installed.  This is especially convenient when
 installing a GNU package on a system that already has a proprietary
-implementation you do not want to overwrite.  For instance you may want
+implementation you do not want to overwrite.  For instance, you may want
 to install GNU `tar' as `gtar' so you can distinguish it from your
 vendor's `tar'.
 
@@ -695,15 +695,15 @@
 ---------------------------------------------
 
 The GNU build system's `make install' and `make uninstall' interface
-does not exactly fits the needs of a system administrator who has to
+does not exactly fit the needs of a system administrator who has to
 deploy and upgrade packages on lots of hosts.  In other words, the GNU
 build system does not replace a package manager.
 
    The `DESTDIR' variable can be used when creating binary packages
 containing a snapshot of all the files to be installed.  The package
 should be configured as if it was going to be installed in its final
-location (e.g., `--prefix /usr'), but when running `make install' the
-`DESTDIR' should be set to the name of an empty directory in which all
+location (e.g., `--prefix /usr'), but when running `make install', the
+`DESTDIR' should be set to the name of a path prefix below which all
 the installation will be diverted.
 
      ~/amhello-1.0 % ./configure --prefix /usr
@@ -737,7 +737,7 @@
 
    Another, more useful command is `make distcheck'.  The `distcheck'
 target constructs `PACKAGE-VERSION.tar.gz' just as well as `dist', but
-it additionally ensures most of the use-cases presented so far work.
+it additionally ensures most of the use-cases presented so far work:
 
    * It attempts a full compilation of the package (*note Basic
      Installation::), unpacking the newly constructed tarball, running
@@ -753,7 +753,7 @@
    * and it checks that `DESTDIR' installations work (*note DESTDIR::).
 
    Releasing a package that fails `make distcheck' means that one of
-the scenario we presented won't work and some users will be
+the scenarios we presented won't work and some users will be
 disappointed.  Therefore it is a good practice to release a package
 only after a successful `make distcheck'.  This of course does not
 imply that the package will be flawless, but at least it will prevent
@@ -770,7 +770,7 @@
 Dependency tracking is performed as a side-effect of compilation.  Each
 time the build system compiles a source file, it computes its list of
 dependencies (in C these are the header files included by the source
-being compiled).  Later, any time `make' is run and a dependency appear
+being compiled).  Later, any time `make' is run and a dependency appears
 to have changed, the dependent files will be rebuilt.
 
    When `configure' is executed, you can see it probing each compiler
@@ -783,11 +783,11 @@
      ...
 
    Because dependencies are only computed as a side-effect of the
-compilation, no dependency information exist the first time a package
+compilation, no dependency information exists the first time a package
 is built.  This is OK because all the files need to be built anyway:
 `make' does not have to decide which files need to be rebuilt.  In
 fact, dependency tracking is completely useless for one-time builds and
-there is a `configure' option to disable this.
+there is a `configure' option to disable this:
 
 `--disable-dependency-tracking'
      Speed up one-time builds.
@@ -795,9 +795,9 @@
    Some compilers do not offer any practical way to derive the list of
 dependencies as a side-effect of the compilation, requiring a separate
 run (maybe of another tool) to compute these dependencies.  The
-performance penalty implied my these methods is important enough to
+performance penalty implied by these methods is important enough to
 disable them by default.  The option `--enable-dependency-tracking'
-must be passed to `configure' to active them.
+must be passed to `configure' to activate them.
 
 `--enable-dependency-tracking'
      Do not reject slow dependency extractors.
@@ -822,14 +822,14 @@
 installing A will also build and install B.  Generating a distribution
 for A will also include B.
 
-   It is possible to gather several package like this.  GCC is an heavy
+   It is possible to gather several package like this.  GCC is a heavy
 user of this feature.  This gives installers a single package to
 configure, build and install, while it allows developers to work on
 subpackages independently.
 
    When configuring nested packages, the `configure' options given to
 the top-level `configure' are passed recursively to nested
-`configure's.  A package that do not understand an option will ignore
+`configure's.  A package that does not recognize an option will ignore
 it, assuming it is meaningful to some other package.
 
    The command `configure --help=recursive' can be used to display the
@@ -846,20 +846,20 @@
 
    * As we have seen, the GNU Build System has a lot of features (*note
      Use Cases::).  Some users may expect features you have not
-     implemented you did not need them.
+     implemented, because you did not need them.
 
-   * Implementing these feature portably is difficult, and exhausting.
-     Think portable shell scripts, portable `Makefile's, on systems you
+   * Implementing these features portably is difficult and exhausting.
+     Think of portable shell scripts or portable `Makefile's on systems you
      may not have handy.  *Note Portable Shell Programming:
-     (autoconf)Portable Shell, to convince yourself.
+     (autoconf)Portable Shell, to convince yourself of some pitfalls.
 
    * You will have to upgrade your setup to follow changes to the GNU
      Coding Standards.
 
    The GNU Autotools take all this burden off your back and provide:
 
-   * Tools to create a portable, complete, and self-contained, GNU Build
-     System, from simple instructions.  _Self-contained_ meaning the
+   * Tools to create a portable, complete, and self-contained GNU Build
+     System from simple instructions.  _Self-contained_ here means that the
      resulting build system does not require the GNU Autotools.
 
    * A central place where fixes and improvements are made: a bug-fix
@@ -891,7 +891,7 @@
    Create the following files in an empty directory.
 
    * `src/main.c' is the source file for the `hello' program.  We store
-     it in the `src/' subdirectory, because later if the package
+     it in the `src/' subdirectory, because later, when the package
      evolves, it will ease the addition of a `man/' directory for man
      pages, a `data/' directory for data files, etc.
           ~/amhello % cat src/main.c
@@ -950,7 +950,7 @@
    In addition to the three scripts mentioned in its output, you can see
 that `autoreconf' created four other files: `configure', `config.h.in',
 `Makefile.in', and `src/Makefile.in'.  The latter three files are
-templates that will be adapted to the system by `configure', under them
+templates that will be adapted to the system by `configure' under the
 names `config.h', `Makefile', and `src/Makefile'.  Let's do this:
 
      ~/amhello % ./configure
@@ -994,18 +994,18 @@
      =============================================
 
    Note that running `autoreconf' is only needed initially when the GNU
-Build System does not exist.  When you later changes some instructions
+Build System does not exist.  When you later change some instructions
 in a `Makefile.am' or `configure.ac', the relevant part of the build
 system will be regenerated automatically when you execute `make'.
 
    `autoreconf' is a script that calls `autoconf', `automake', and a
-bunch of other commands, in the right order.  If you are beginning with
+bunch of other commands in the right order.  If you are beginning with
 these tools, it is not important to figure out in which order all these
-tools should be invoked and why.  However because Autoconf and Automake
+tools should be invoked and why.  However, because Autoconf and Automake
 have separate manuals, the important point to understand is that
 `autoconf' is in charge of creating `configure' from `configure.ac',
-while `automake' is in charge of creating `Makefile's from
-`Makefile.am's and `configure.ac' too.  This should at least direct you
+while `automake' is in charge of creating `Makefile.in's from both
+`Makefile.am's and `configure.ac'.  This should at least direct you
 to the correct manual when seeking answers.
 
 2.4.2 `amhello-1.0' Explained
@@ -1025,20 +1025,20 @@
 
    This file is read by both `autoconf' (to create `configure.ac') and
 `automake' (to create the various `Makefile.in's).  It contains a
-series of M4 macros that will be expansed as shell code to finally form
+series of M4 macros that will be expanded as shell code to finally form
 the `configure' script.  We will not elaborate on the syntax of this
 file, because the Autoconf manual has a whole section about it (*note
 Writing `configure.ac': (autoconf)Writing configure.ac.).
 
-   The macros that starts with `AC_' are Autoconf macros, documented in
+   The macros prefixed with `AC_' are Autoconf macros, documented in
 the Autoconf manual (*note Autoconf Macro Index: (autoconf)Autoconf
-Macro Index.).  The macros that starts with `AM_' are Automake macros,
+Macro Index.).  The macros prefixed with `AM_' are Automake macros,
 documented later in this manual (*note Macro Index::).
 
    The first two lines of `configure.ac' initialize Autoconf and
 Automake.  `AC_INIT' takes in parameters the name of the package, its
 version number, and a contact address for bug-reports about the package
-(this address is output at the end of `./configure --help' for
+(this address is output at the end of `./configure --help', for
 instance).  When adapting this setup to your own package, by all means
 please do not blindly copy Automake's address: use the mailing list of
 your package, or your own mail address.
@@ -1048,7 +1048,7 @@
 turn on all warnings and report them as errors.  We are speaking of
 *Automake* warnings here, such as dubious instructions in
 `Makefile.am', this has absolutely nothing to do with how the compiler
-will be called even though it may support options with similar names.
+will be called, even though it may support options with similar names.
 Using `-Wall -Werror' is a safe setting when starting to work on a
 package: you do not want to miss any issue.  Later you may decide to
 relax things a bit.  The `foreign' option tells Automake that this
@@ -1061,7 +1061,7 @@
 C compiler and define the variable `CC' with its name.  The
 `src/Makefile.in' file generated by Automake uses the variable `CC' to
 build `hello', so when `configure' creates `src/Makefile' from
-`src/Makefile.in' it will define `CC' with the value it has found.  If
+`src/Makefile.in', it will define `CC' with the value it has found.  If
 Automake is asked to create a `Makefile.in' that uses `CC' but
 `configure.ac' does not define it, it will suggest you add a call to
 `AC_PROG_CC'.
@@ -1091,13 +1091,13 @@
 should add its `Makefile' to this list, otherwise Automake will never
 process the new `Makefile.am' you wrote in that directory.)
 
-   Finally the `AC_OUTPUT' line is a closing command that actually
+   Finally, the `AC_OUTPUT' line is a closing command that actually
 produces the part of the script in charge of creating the files
 registered with `AC_CONFIG_HEADERS' and `AC_CONFIG_FILES'.
 
    When starting a new project, we suggest you start with such a simple
 `configure.ac', and gradually add the other tests it requires.  The
-command `autoscan' can also suggest of few of the tests your package
+command `autoscan' can also suggest a few of the tests your package
 may need (*note Using `autoscan' to Create `configure.ac':
 (autoconf)autoscan Invocation.).
 
@@ -1112,20 +1112,20 @@
 output `Makefile.in' (that will be later turned into `Makefile' by
 `configure') but will react to certain variable definitions by
 generating some build rules and other variables.  Often `Makefile.am's
-contain only a list variable definitions as above, but it can also
-contains other variable and rule definitions that `automake' will pass
+contain only a list of variable definitions as above, but it can also
+contain other variable and rule definitions that `automake' will pass
 along without interpretation.
 
-   Variables that ends with `_PROGRAMS' are special variables that list
+   Variables that end with `_PROGRAMS' are special variables that list
 programs that the resulting `Makefile' should build.  In Automake
-speak, this `_PROGRAMS' suffix is called a "primary"; Automake
-recognises other primaries such as `_SCRIPTS', `_DATA', `_LIBRARIES',
-etc. corresponding to different type of files.
+terms, this `_PROGRAMS' suffix is called a "primary"; Automake
+recognizes other primaries such as `_SCRIPTS', `_DATA', `_LIBRARIES',
+etc. corresponding to different types of files.
 
    The `bin' part of the `bin_PROGRAMS' tells `automake' that the
 resulting programs should be installed in BINDIR.  Recall that the GNU
 Build System uses a set of variables to denote destination directories
-and allow users to customise these locations (*note Standard Directory
+and allow users to customize these locations (*note Standard Directory
 Variables::).  Any such directory variable can be put in front of a
 primary (omitting the `dir' suffix) to tell `automake' where to install
 the listed files.
@@ -1151,13 +1151,14 @@
 should recurse into before processing the current directory.  So this
 line is responsible for `make' building `src/hello' even though we run
 it from the top-level.  This line also causes `make install' to install
-`src/hello' before installing `README' (not that this order matters).
+`src/hello' before installing `README' (not that the order matters in
+this case).
 
    The line `dist_doc_DATA = README' causes `README' to be distributed
 and installed in DOCDIR.  Files listed with the `_DATA' primary are not
 automatically part of the tarball built with `make dist', so we add the
-`dist_' prefix so they get distributed.  However for `README' it
-wouldn't have been necessary: `automake' automatically distribute any
+`dist_' prefix so they get distributed.  However, for `README' it
+wouldn't have been necessary: `automake' automatically distributes any
 `README' file it encounters (the list of other files automatically
 distributed is presented by `automake --help').  The only important
 effect of this second line is therefore to install `README' during