Re: RFC: Autotools Introduction chapter draft (16 pages long)
BP == Ben Pfaff [EMAIL PROTECTED] writes: BP I did a quick job of proofreading as I read your chapter. (And so did Ralf.) Thanks a lot to both of you ! I'll post the complete patch momently on automake-patches. -- Alexandre Duret-Lutz Shared books are happy books. http://www.bookcrossing.com/friend/gadl
Re: RFC: Autotools Introduction chapter draft (16 pages long)
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
Re: RFC: Autotools Introduction chapter draft (16 pages long)
Hello Alexandre, all, * Alexandre Duret-Lutz wrote on Sat, Aug 12, 2006 at 11:45:50PM CEST: I you feel that pointing out my missing ss and other blunders will pollute this list, feel free to divert your answer to [EMAIL PROTECTED] Well, I just replied there; apologies for not having post-edited my proof to weed the bits Ben already spotted. Cheers, Ralf
Re: RFC: Autotools Introduction chapter draft (16 pages long)
On Mon, Aug 14, 2006 at 12:06:15PM -0700, Ben Pfaff wrote: 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? Hi, Ben! It should... but that doesn't mean it will. Certainly ought to if they're using Automake, etc., but IMO make make install is a good habit to get into, for those relatively rare cases when someone doesn't have the right dependenceis set up... I'm too lazy to look up the context atm, though, so perhaps this was /only/ meant for autotools environs. Still, seems like a decent habit to get into, regardless. Also, I typically want to install as root, but not to build as root, which is why I'll more usually do a make, and then a sudo make install (I imagine you do the same, in practice). If I'm just testing the install, though, I'd probably set DESTDIR or --prefix to something interesting, and do it as make make install (possibly, just make install, as you suggest). -- Micah J. Cowan Programmer, musician, typesetting enthusiast, gamer... http://micah.cowan.name/
Re: RFC: Autotools Introduction chapter draft (16 pages long)
Hello Ben, Alexandre, * Ben Pfaff wrote on Mon, Aug 14, 2006 at 09:06:15PM CEST: Alexandre Duret-Lutz [EMAIL PROTECTED] writes: 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? Yes, and in theory, it should not make a difference which sequence you issue (which would make the one you prefer faster, as it spawns less instances of `make'). However, there are more packages that fail to have everything built with a `./configure make install', mostly due to unclean inter-Makefile dependencies, than packages for which it is a lot of work to have the `all' target rebuilt upon the `install' target. However, the latter hinders an important feature mentioned in the GCS: to be able to build as one user, and install as a different user.[1] ~ % tar zxf amhello-1.0.tar.gz ~ % cd amhello-1.0 ~/amhello-1.0 % ./configure [...] 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. FWIW, I certainly would prefer a $ prompt as well; I was a bit surprised by it at one time in the past. The user first unpacks the package, and then `cd' into the newly created directory to run the `configure' script. `cd' - `cd's `cd' into - enters, please. Cheers, Ralf [1] Yes, in some situations, Libtool is a source of failure here. DESTDIR installs as unprivileged user provide a workaround.
RFC: Autotools Introduction chapter draft (16 pages long)
Hi Folks, I need your help! 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. My objective is (at least) threefold: - I want to present to GNU Build System in a way which makes people eager to use the Autotools. - I would like to use this opportunity to present several uses of the build system that a maintainer should have in mind when hacking his package, but often do not even know about. (I'm often taken aback by Automake users who post to this list not knowing what a VPATH build. I really shouldn't be surprised: there is not a single place in the manual that takes to time to details what that is.) - I want to get rid of the outdated GNU Hello example later in the manual. GNU Hello is now too complex to be useful in a tutorial. 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. 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. The structure of this chapter is mostly based on the first slides of my (unredacted) Autotools tutorial at http://www-src.lip6.fr/~Alexandre.Duret-Lutz/autotools.html 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... Now it would be a bit different: it might be useful to now that there exist some teaching material that illustrates this chapter and then go far beyond it. The text still lacks a bit of cross referencing, and I also have to add many entries into the indexes. But that should not prevent useful comments. For those who want to print it, a postscript version is available at http://www-src.lip6.fr/~Alexandre.Duret-Lutz/dl/am-chap2.ps.gz You'll find a text version below, it is easier to quote. If you to help and comment upon this draft, please DO NOT reply privately. It can't seem to deal with private mail, please bear with me. I you feel that pointing out my missing ss and other blunders will pollute this list, feel free to divert your answer to [EMAIL PROTECTED] Thanks ! 2 An Introduction to the Autotools ** If you are new to Automake, maybe you know that it is part of a set of tools called _The Autotools_. Maybe you've already delved into a package full of files named `configure', `configure.ac', `Makefile.in', `Makefile.am', `aclocal.m4', ... some of them claiming to be _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, 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. 2.1 Introducing the GNU Build System It is a truth universally acknowledged, that a developer in possession of a new package, must be in want of a build system. In the Unix world, such a build system is traditionally achieved using the command `make' (*note Overview: (make)Top.). The developer expresses the recipe to build his package in a `Makefile'. This file is a set of rules to build the files in the package. For instance the program `prog' may be built by running the linker on the files `main.o', `foo.o', and `bar.o'; the file `main.o' may be built by running the compiler on `main.c'; etc. Each time `make' is run, it reads `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. When a package needs to be built on a different platform than the one it was developed on, its `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 `Makefile' for the 20 platforms he had to deal with. Instead, he handcrafted a little shell script called `configure' to automatically adjust the `Makefile' (*note Genesis: (autoconf)Genesis.). Compiling his package was now as simple as running `./configure make'. Today this process has been standardised in the GNU project. The GNU Coding Standards (*note The Release Process: (standards)Managin Releases.) explains how each package of the GNU project should have package of the GNU project should have such a `configure' script, and the minimal interface it should have.
