[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: RFC: "Autotools Introduction" chapter draft (16 pages long)
Re: RFC: "Autotools Introduction" chapter draft (16 pages long)
Mon, 14 Aug 2006 12:06:15 -0700
Gnus/5.110004 (No Gnus v0.4) Emacs/21.4 (gnu/linux)
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
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
> 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
> 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
> 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
> /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
> 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.
> 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.
> 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
> 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
> * `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_