From 1d2407c9f1bb068598cf7a17810e4b489ac6b385 Mon Sep 17 00:00:00 2001 From: Alexandre Duret-Lutz Date: Sat, 19 Aug 2006 13:35:39 +0000 Subject: [PATCH] * doc/automake.texi: Fix some typos in the introduction, adjust some spacing; spell `GNU Build System' consistently. (menu): Unify node naming. (Standard Directory Variables): Clarify that this list is not exhaustive. (DESTDIR): Fix example. --- ChangeLog | 9 ++++ doc/automake.texi | 118 +++++++++++++++++++++++----------------------- doc/stamp-vti | 2 +- doc/version.texi | 2 +- 4 files changed, 70 insertions(+), 61 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6545bd0f..7ceab3d3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2006-08-19 Ralf Wildenhues + + * doc/automake.texi: Fix some typos in the introduction, + adjust some spacing; spell `GNU Build System' consistently. + (menu): Unify node naming. + (Standard Directory Variables): Clarify that this list is not + exhaustive. + (DESTDIR): Fix example. + 2006-08-19 Alexandre Duret-Lutz * doc/automake.texi (Autotools Introduction) New chapter. diff --git a/doc/automake.texi b/doc/automake.texi index 7683811c..1e62d607 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -127,13 +127,13 @@ published by the Free Software Foundation raise funds for An Introduction to the Autotools * GNU Build System:: Introducing the GNU Build System -* Use Cases:: Use case for the GNU Build System +* Use Cases:: Use Cases for the GNU Build System * Why Autotools:: How Autotools Help * Hello World:: A Small Hello World Package Use Cases for the GNU Build System -* Basic Installation:: Common installtion procedure +* Basic Installation:: Common installation procedure * Standard Targets:: A list of standard Makefile targets * Standard Directory Variables:: A list of standard directory variables * Standard Configuration Variables:: Using configuration variables @@ -380,24 +380,24 @@ Mail suggestions and bug reports for Automake to If you are new to Automake, maybe you know that it is part of a set of tools called @emph{The Autotools}. Maybe you've already delved into a package full of files named @file{configure}, @file{configure.ac}, -@file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{} +@file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{}, some of them claiming to be @emph{generated by} Autoconf or Automake. But the exact purpose of these files and their relations is probably -fuzzy. The goal of this chapter is to introduce you this machinery, +fuzzy. The goal of this chapter is to introduce you to this machinery, to show you how it works and how powerful it is. If you've never installed or seen such a package, do not worry: this chapter will walk you through it. If you need some teaching material, more illustrations, or a less -@command{automake}-centred continuation, some slides for this +@command{automake}-centered continuation, some slides for this introduction are available in Alexandre Duret-Lutz's -@uref{Autotools Turorial, -http://www-src.lip6.fr/~Alexandre.Duret-Lutz/autotools.html}. +@uref{Autotools Tutorial, +http://www-src.lip6.fr/@/~Alexandre.Duret-Lutz/@/autotools.html}. This chapter is the written version of the first part of his tutorial. @menu * GNU Build System:: Introducing the GNU Build System -* Use Cases:: Use case for the GNU Build System +* Use Cases:: Use Cases for the GNU Build System * Why Autotools:: How Autotools Help * Hello World:: A Small Hello World Package @end menu @@ -419,12 +419,12 @@ running the linker on the files @file{main.o}, @file{foo.o}, and compiler on @file{main.c}; etc. Each time @command{make} is run, it reads @file{Makefile}, checks the existence and modification time of the files mentioned, decides what files need to be built (or rebuilt), -and run the associated commands. +and runs the associated commands. When a package needs to be built on a different platform than the one it was developed on, its @file{Makefile} usually needs to be adjusted. For instance the compiler may have another name or require more -options. In 1991, David J. MacKenzie got tired of customising +options. In 1991, David J. MacKenzie got tired of customizing @file{Makefile} for the 20 platforms he had to deal with. Instead, he handcrafted a little shell script called @file{configure} to automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis, @@ -433,7 +433,7 @@ as simple as running @code{./configure && make}. @cindex GNU Coding Standards -Today this process has been standardised in the GNU project. The GNU +Today this process has been standardized in the GNU project. The GNU Coding Standards (@pxref{Managing Releases, The Release Process, , standards, The GNU Coding Standards}) explains how each package of the GNU project should have a @file{configure} script, and the minimal @@ -462,7 +462,7 @@ illustration of the GNU Build System in action. @cindex GNU Build System, use cases @cindex GNU Build System, features @cindex Features of the GNU Build System -@cindex Use cases for the GNU Build System +@cindex Use Cases for the GNU Build System @cindex @file{amhello-1.0.tar.gz}, location @cindex @file{amhello-1.0.tar.gz}, use cases @@ -480,14 +480,14 @@ 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 +the GNU Coding Standards, but they are nonetheless part of the build +system created by the Autotools. To keep things simple, we do not point out the difference. Our objective is to show you many of the features that the build system created by the Autotools will offer to you. @menu -* Basic Installation:: Common installtion procedure +* Basic Installation:: Common installation procedure * Standard Targets:: A list of standard Makefile targets * Standard Directory Variables:: A list of standard directory variables * Standard Configuration Variables:: Using configuration variables @@ -540,7 +540,7 @@ command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}. The user then enters the newly created directory to run the @file{configure} script. This script probes the system for various -features, and finally create the @file{Makefile}s. In this toy +features, and finally creates the @file{Makefile}s. In this toy example there are only two @file{Makefile}s, but in real-world project there may be many more, usually one @file{Makefile} per directory. @@ -558,12 +558,12 @@ check} is a no-op. @cindex su, before @code{make install} After everything has been built, and maybe tested, it is time to -install them on the system. That means copying the programs, +install it on the system. That means copying the programs, libraries, header files, scripts, and other data files from the source directory to their final destination on the system. The -command @code{make install} will do that. However by default +command @code{make install} will do that. However, by default everything will be installed in subdirectories of @file{/usr/local}: -binaries will go into @file{/usr/local/bin}, libraries will end into +binaries will go into @file{/usr/local/bin}, libraries will end up in @file{/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 @code{make install}. In our example, running @code{make install} @@ -572,13 +572,13 @@ and @file{README} into @file{/usr/local/share/doc/amhello}. A last and optional step is to run @code{make installcheck}. This command may run tests on the installed files. @code{make check} tests -the files in the source tree while @code{make installcheck} tests +the files in the source tree, while @code{make installcheck} tests their installed copies. The tests run by the latter can be different -from those run by former. For instance, there are tests that cannot -be run in the source tree. Conversely, some packages are set up so -that @code{make installcheck} will run the very same tests as +from those run by the former. For instance, there are tests that +cannot be run in the source tree. Conversely, some packages are set +up so that @code{make installcheck} will run the very same tests as @code{make check}, only on different files (non-installed -vs. installed). It can make a difference, for instance when the +vs.@: installed). It can make a difference, for instance when the source tree's layout is different from that of the installation. Furthermore it may help to diagnose an incomplete installation. @@ -603,7 +603,7 @@ specify. @table @code @item make all @trindex all -Build programs, libraries, documentation, etc. (Same as @code{make}.) +Build programs, libraries, documentation, etc.@: (same as @code{make}). @item make install @trindex install Install what needs to be installed, copying the files from the @@ -611,7 +611,7 @@ package's tree to system-wide directories. @item make install-strip @trindex install-strip Same as @code{make install}, then strip debugging symbols. Some -users like to trade space for useful bug reports... +users like to trade space for useful bug reports@enddots{} @item make uninstall @trindex uninstall The opposite of @code{make install}: erase the installed files. @@ -639,7 +639,7 @@ files. @cindex directory variables The GNU Coding Standards also specify a hierarchy of variables to -denote installation directories. +denote installation directories. Some of these are: @multitable {Directory variable} {@file{@code{datarootdir}/doc/@code{PACKAGE}}} @headitem Directory variable @tab Default value @@ -675,7 +675,7 @@ installed into @var{docdir}, which defaults to @opindex --prefix -A user who wish to install a package on his own account could proceed +A user who wishes to install a package on his own account could proceed as follows: @example @@ -741,7 +741,7 @@ Again, a full list of these variables appears in the output of @cindex @file{config.site} example When installing several packages using the same setup, it can be -convenient to create a @file{config.site} to capture common settings. +convenient to create a file to capture common settings. If a file named @file{@var{prefix}/share/config.site} exists, @command{configure} will source it at the beginning of its execution. @@ -753,8 +753,8 @@ CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib} @end example Assuming we are installing many package in @file{~/usr}, and will -always want to use these definition of @code{CC}, @code{CPPFLAGS}, and -@code{LDFLAGS}, we can automatize this by creating the following +always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and +@code{LDFLAGS}, we can automate this by creating the following @file{~/usr/share/config.site} file: @example @@ -763,7 +763,7 @@ test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib @end example -Now any time a @file{configure} script is using the @file{~/usr} +Now, any time a @file{configure} script is using the @file{~/usr} prefix, it will execute the above @file{config.site} and define these three variables. @@ -778,22 +778,22 @@ Manual}, for more information about this feature. @node VPATH Builds -@subsection Parallel Build Trees (a.k.a. VPATH Builds) +@subsection Parallel Build Trees (a.k.a.@: VPATH Builds) @cindex Parallel build trees @cindex VPATH builds @cindex source tree and build tree @cindex build tree and source tree -@cindex trees, source vs. build +@cindex trees, source vs.@: build The GNU Build System distinguishes two trees: the source tree, and the build tree. The source tree is rooted in the directory containing -@file{configure}. it contains all the sources files (those that are +@file{configure}. It contains all the sources files (those that are distributed), and may be arranged using several subdirectories. -The build tree is rooted in the directory where the @file{configure} -were run, and is populated with all object files, programs, libraries, +The build tree is rooted in the directory in which @file{configure} +was run, 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; its subdirectories are created automatically by @@ -801,7 +801,7 @@ the build system. If @file{configure} is executed in its own directory, the source and build trees are combined: derived files are constructed in the same -directory as their sources. This was the case in our first +directories as their sources. This was the case in our first installation example (@pxref{Basic Installation}). A common request from users is that they want to confine all derived @@ -941,7 +941,7 @@ On the first host we would run ... @end example -On the second host, however, we need only to install the +On the second host, however, we need only install the architecture-specific files. @example [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh} @@ -957,10 +957,10 @@ the package works correctly despite the apparent partial installation. @node Cross-Compilation @subsection Cross-Compilation -@cindex Cross-compilation +@cindex cross-compilation To @dfn{cross-compile} is to build on one platform a binary that will -be run on another platform. When speaking of cross-compilation, it is +run on another platform. When speaking of cross-compilation, it is important to distinguish between the @dfn{build platform} on which the compilation is performed, and the @dfn{host platform} on which the resulting executable is expected to run. The following @@ -976,7 +976,7 @@ The system where built programs and libraries will run. @end table When the @option{--host} is used, @command{configure} will search for -the cross-compiling suite for this platform. cross-compilation tools +the cross-compiling suite for this platform. Cross-compilation tools commonly have their target architecture as prefix of their name. For instance my cross-compiler for MinGW32 has its binaries called @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld}, @@ -1039,7 +1039,7 @@ options. @cindex Transforming program names @cindex Programs, renaming during installation -The GNU build system provides means to automatically rename +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, @@ -1076,10 +1076,10 @@ as @file{/usr/local/bin/test-hello}, for instance. @subsection Building Binary Packages Using DESTDIR @vindex DESTDIR -The GNU build system's @code{make install} and @code{make uninstall} +The GNU Build System's @code{make install} and @code{make uninstall} interface 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. +words, the GNU Build System does not replace a package manager. Such package managers usually need to know which files have been installed by a package, so a mere @code{make install} is @@ -1109,15 +1109,15 @@ snapshot of all the files to be installed. ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install} @dots{} ~/amhello-1.0 % @kbd{cd ~/inst} -~/inst % @kbd{find . -type f -print > files.lst} -~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat file.lst`} +~/inst % @kbd{find . -type f -print > ../files.lst} +~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../file.lst`} ./usr/bin/hello ./usr/share/doc/amhello/README @end example After this example, @code{amhello-1.0-i686.tar.gz} is ready to be -uncompressed in @file{/} on many hosts. (Using @code{`cat file.lst`} -instead of @samp{.} as argument for @command{tar} avoid entries for +uncompressed in @file{/} on many hosts. (Using @code{`cat ../file.lst`} +instead of @samp{.} as argument for @command{tar} avoids entries for each subdirectory in the archive: we would not like @command{tar} to restore the modification time of @file{/}, @file{/usr/}, etc.) @@ -1138,7 +1138,7 @@ architecture-independent files in a single package. @cindex Distributions, preparation We have already mentioned @code{make dist}. This target collects all -your source files, and the necessary parts of the build system, to +your source files and the necessary parts of the build system to create a tarball named @file{@var{package}-@var{version}.tar.gz}. @cindex @code{distcheck} better than @code{dist} @@ -1146,7 +1146,7 @@ create a tarball named @file{@var{package}-@var{version}.tar.gz}. Another, more useful command is @code{make distcheck}. The @code{distcheck} target constructs @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist}, -but it additionally ensures most of the use-cases presented so far +but it additionally ensures most of the use cases presented so far work: @itemize @bullet @@ -1247,7 +1247,7 @@ Autoconfiscated packages (that means packages whose build system have been created by Autoconf and friends) can be nested to arbitrary depth. -A typical setup is that a package A will distribute one of the library +A typical setup is that a 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, @@ -1313,7 +1313,7 @@ a bug-fix for a portability issue will benefit every package. Yet there also exist reasons why you may want NOT to use the Autotools@enddots{} For instance you may be already using (or used to) another incompatible build system. Autotools will only be useful if -you do accept the concepts of GNU Build System. People who have their +you do accept the concepts of the GNU Build System. People who have their own idea of how a build system should work will feel frustrated by the Autotools. @@ -1489,7 +1489,7 @@ point to understand is that @command{autoconf} is in charge of creating @file{configure} from @file{configure.ac}, while @command{automake} is in charge of creating @file{Makefile.in}s from @file{Makefile.am}s and @file{configure.ac}. This should at least -direct you to the correct manual when seeking answers. +direct you to the right manual when seeking answers. @node amhello Explained @@ -1576,13 +1576,13 @@ is an excerpt of @file{config.h} after @command{configure} has run: @end smallexample As you probably noticed, @file{src/main.c} includes @file{config.h} so -it can use @code{PACKAGE_STRING}. In a real work project, +it can use @code{PACKAGE_STRING}. In a real-world project, @file{config.h} can grow really big, with one @samp{#define} per feature probed on the system. The @code{AC_CONFIG_FILES} macro declares the list of files that -@command{configure} should create from their @file{*.in} template. -Automake also scans this list to find the @file{Makefile.am} it must +@command{configure} should create from their @file{*.in} templates. +Automake also scans this list to find the @file{Makefile.am} files it must process. (This is important to remember: when adding a new directory to your project, you should add its @file{Makefile} to this list, otherwise Automake will never process the new @file{Makefile.am} you @@ -1618,14 +1618,14 @@ A @file{Makefile.am} has the same syntax as an ordinary @command{configure}) but will react to certain variable definitions by generating some build rules and other variables. Often @file{Makefile.am}s contain only a list of variable definitions as -above, but it can also contain other variable and rule definitions that +above, but they can also contain other variable and rule definitions that @command{automake} will pass along without interpretation. Variables that end with @code{_PROGRAMS} are special variables that list programs that the resulting @file{Makefile} should build. In Automake speak, this @code{_PROGRAMS} suffix is called a @dfn{primary}; Automake recognizes other primaries such as -@code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc. corresponding +@code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding to different types of files. The @samp{bin} part of the @code{bin_PROGRAMS} tells diff --git a/doc/stamp-vti b/doc/stamp-vti index 14116414..4c71d942 100644 --- a/doc/stamp-vti +++ b/doc/stamp-vti @@ -1,4 +1,4 @@ -@set UPDATED 16 August 2006 +@set UPDATED 19 August 2006 @set UPDATED-MONTH August 2006 @set EDITION 1.9a @set VERSION 1.9a diff --git a/doc/version.texi b/doc/version.texi index 14116414..4c71d942 100644 --- a/doc/version.texi +++ b/doc/version.texi @@ -1,4 +1,4 @@ -@set UPDATED 16 August 2006 +@set UPDATED 19 August 2006 @set UPDATED-MONTH August 2006 @set EDITION 1.9a @set VERSION 1.9a -- 2.43.5