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

[Ben Pfaff]

Alexandre Duret-Lutz <address@hidden> writes:

> 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.

I'm always amazed how well people write English.  My written
French, for example, is miserable (although I can read French
fairly well).

I did a quick job of proofreading as I read your chapter.  My
thoughts are interspersed below.

>    Today this process has been standardised in the GNU project.  The GNU
> Coding Standards (*note The Release Process: (standards)Managin

Managin -> Managing

> Releases.) explains how each package of the GNU project should have
> package of the GNU project should have such a `configure' script, and

Some words are repeated in the phrase above, messing up the
grammar.

> the minimal interface it should have.  The `Makefile' too should follow
> some established conventions.  The result?  A unified build system that
> makes all packages almost indistinguishable by the installer.  In its
> most simple scenario, all the installer has to do is to unpack the

most simple -> simplest

> package, run `./configure && make && make install', and repeat with the
> next package to install.

I'm never sure whether I should recommend running "make" before
"make install".  "make install" will first build everything that
"make" will, right?

>    We call this build system the "GNU Build System", since it was grown
> out of the GNU project.  However it is used by a vast number of other
> packages: following any existing convention has its advantages.

I would write ", because" instead of ":", but this is at most a
nitpick.

>    The Autotools are tools that will create a GNU Build System for your
> package.  Autoconf mostly focuses on `configure' and Automake on
> `Makefile's.  It is entirely possible to create a GNU Build System
> without the help of these tools.  However it is rather burdensome and
> error-prone.  We will discuss this again after some illustration of the
> GNU Build System in action.
>
> 2.2 Use Cases for the GNU Build System
> ======================================
>
> In this section we explore several use cases for the GNU Build System.
> You can replay all these examples on the `amhello-1.0.tar.gz' package
> distributed with Automake.  If Automake is installed on your system,
> you should find a copy of this file in
> `PREFIX/share/doc/automake/amhello-1.0.tar.gz', where PREFIX is the
> installation prefix specified during configuration (PREFIX defaults to
> `/usr/local', however if Automake was installed by some GNU/Linux
> distribution it most likely has been set to `/usr').  If you do not
> have a copy of Automake installed, you can find a copy of this file
> inside the `doc/' directory of the Automake package.
>
>    Some of the following use cases present features that are in fact
> extensions to the GNU Build System.  Read: they are not specified by
> the GNU Coding Standard, but they are nonetheless part of the build
> system created by the Autotools.  To keep things simple we do not make
> the difference.  Our objective is to show you many of the features that

"make the difference" -> "distinguish" or perhaps "point out the
differences"

> the build system created by the Autotools will offer to you.
>
> 2.2.1 Basic Installation
> ------------------------
>
> The most common installation procedure looks as follows.
>
>      ~ % tar zxf amhello-1.0.tar.gz
>      ~ % cd amhello-1.0
>      ~/amhello-1.0 % ./configure
>      ...
>      config.status: creating Makefile
>      config.status: creating src/Makefile
>      ...
>      ~/amhello-1.0 % make
>      ...
>      ~/amhello-1.0 % make check
>      ...
>      ~/amhello-1.0 % su
>      Password:
>      /home/adl/amhello-1.0 # make install
>      ...
>      /home/adl/amhello-1.0 # exit
>      ~/amhello-1.0 % make installcheck
>      ...

Most of the time, when I see a shell example, the shell used in
the example is the Bourne shell (hence a $ prompt).  I don't know
if it makes a difference to you or whether a reader could be
confused by it.

>    The user first unpacks the package, and then `cd' into the newly

`cd' -> `cd's

> created directory to run the `configure' script.  This script probes
> the system for various features, and finally create the `Makefile's.
> In this toy example there are only two `Makefile's, but in real-world
> project there may be many more, usually one `Makefile' per directory.
>
>    It is now possible to run `make'.  This will construct all the
> programs, libraries, and scripts that need to be constructed for the
> package.  In our example, this compiles the `hello' program.  All files
> are constructed in place, in the source tree; we will see later how
> this can be changed.
>
>    `make check' causes the package's tests to be run.  This step is not
> mandatory, but it is often good to make sure the programs that have
> been built behave as they should, before you decide to install them.
> Our example does not contain any test, so running `make check' is a

any test -> any tests

> no-op.
>
>    After every thing has been built, and maybe tested, it is time to

every thing -> everything

> install them on the system.  That means copying the programs,
> libraries, header files, scripts, and other data files, from the source

I would drop the final comma on that line.

> directory to their final destination on the system.  The command `make
> install' will do that.  However by default everything will be installed
> in subdirectories of `/usr/local': binaries will go into
> `/usr/local/bin', libraries will end into `/usr/local/lib', etc.  This
> destination is usually not writable by any user, so we assume that we
> have to become root before we can run `make install'.  In our example,
> running `make install' will copy the program `hello' into
> `/usr/local/bin' and `README' into `/usr/local/share/doc/amhello'.
>
>    A last and optional step is to run `make installcheck'.  This
> command may run tests on the installed files.  `make check' tests the
> files in the source tree while `make installcheck' tests their
> installed copies.  The tests run by the latter can be different from
> those run by former: there are tests that cannot be run in the source

I would write ", if" instead of ":".

> tree.  Conversely, some packages are set up so that `make installcheck'
> will run the very same tests as `make check', only on different files
> (non-installed vs. installed).  It can make a difference, for instance
> when the source tree's layout is different than that of the

different than -> different from

> installation, furthermore it may help to diagnose an incomplete

I would start a new sentence at the comma.

> installation.
>
>    Presently most packages do not have any `installcheck' tests because
> the existence of `installcheck' is little known, and its usefulness is
> neglected.  Our little toy package is no better: `make installcheck'
> does nothing.
>
> 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

argument -> arguments

> `make' are called "targets".  `make' is a shorthand for `make all',

Add comma after `make'.

> 2.2.6 Parallel Build Trees (a.k.a. VPATH Builds)
> ------------------------------------------------
>
> The GNU Build System distinguishes two trees : the source tree, and the

Delete space before :.

> build tree.
>
>    The source tree is rooted in the directory containing `configure',

Start new sentence at comma.

>    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
> `HOST2', maybe different platforms.

maybe => which may be

>      ~ % cd /nfs/src
>      /nfs/src % tar zxf ~/amhello-1.0.tar.gz
>
>    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
>      ...

I don't think the sudo command has been mentioned before.


> `--host=HOST'
>      The system where built programs & libraries will run.

& -> and

> 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

fits => fit

> 2.2.11 Preparing Distributions
> ------------------------------
>
> We have already mentioned `make dist'.  This target collects all your
> source files, and the necessary parts of the build system, to create a
> tarball named `PACKAGE-VERSION.tar.gz'

Sentence needs .

>    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.

I would use a colon at the end of this sentence.

>    * It attempts a full compilation of the package (*note Basic
>      Installation::), unpacking the newly constructed tarball, running
>      `make', `make check', `make install', as well as `make
>      installcheck', and even `make dist',

Might be worth noting that it does these things in a temporary
directory, so that you don't have to run distcheck with root
privileges.

> 2.2.12 Automatic Dependency Tracking
> ------------------------------------
>
> 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

appear -> appears

>    Because dependencies are only computed as a side-effect of the
> compilation, no dependency information exist the first time a package

exist -> exists

>    * 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 you -> implemented because you

>    * Implementing these feature portably is difficult, and exhausting.

feature -> features
Drop comma.

>    * `src/main.c' is the source file for the `hello' program.  We store
>      it in the `src/' subdirectory, because later if 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
>           #include <config.h>
>           #include <stdio.h>

I am not certain it is worthwhile to include shell commands just
to show file contents.

>    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

expansed -> expanded

> 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 Autoconf manual (*note Autoconf Macro Index: (autoconf)Autoconf
> Macro Index.).  The macros that starts 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
> 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.
>
>    The argument to `AM_INIT_AUTOMAKE' is a list of options for
> `automake' (*note Options::).  `-Wall' and `-Werror' ask `automake' to
> 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

Start new sentence at comma.

> 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

issue -> issues

> may be more that one source file: they will all be compiled and linked

that -> than
-- 
"There's only one thing that will make them stop hating you.
 And that's being so good at what you do that they can't ignore you.
 I told them you were the best.  Now you damn well better be."
--Orson Scott Card, _Ender's Game_