Alexandre Duret-Lutz <[EMAIL PROTECTED]> 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_
