Re: A Closer Look at GNU AutoTools

[Gavin Smith]

On Sat, Sep 13, 2014 at 4:32 PM, David A. Wheeler <address@hidden> wrote:
> There *are* good tutorials available for the autotools.
> John Calcote's book is awesome, I highly recommend it.
> The "Goat book"  ("GNU Autoconf, Automake, and Libtool" by Gary V. Vaughn and 
> Ben Elliston)
> was great for its time; if updated that'd be great too.
> For quick introductions, there are lots of OSS ones. I'll re-mention my video
> at http://www.dwheeler.com/autotools/ and there are many others.
>
> I agree that it'd be nice to have, as OSS, an "official" tutorial (not 
> reference) for the autotools.
> I believe that the autoconf, automake, and libtool manuals are reasonable 
> references, but
> are difficult for people who "just want to use it"
> for common simple cases and don't care about all the details.

The manuals do have examples that could be improved as tutorials. More
examples could be added for common use cases. It would be better for
the existing manuals to do better as tutorials rather than having a
separate document that many people would never get round to reading.

Here are some comments on the first few sections of the automake
manual. I'd be willing to prepare patches for the below if there is
any interest:

1. Introduction
Mention that scans configure.ac. Maybe include a flowchart with programs
and files involved.
2. An Introduction to the Autotools
2.1. Introducing the GNU Build System
2.2. Use Cases for the GNU Build System
It's possibly unclear whether these are use cases for a generated build
system (to be used by users of packages that use the autotools), or use cases
for the autotools themselves.
2.3. How Autotools Help
Merge with sections 1. or 2.
2.4 - A Small Hello World
Include as an example under section 4.  Confusing coming right after 2.2. which
is not for users of the autotools themselves.  Mention in 2.4.1 that the
contents of configure.ac and Makefile.am will be explained in 2.4.2 and 2.4.3.
3. General ideas.
3.1. General Operation
I'm not sure what the purpose of this section is.  Doesn't mention that
automake scans 'configure.ac'.  Include a mention of the naming scheme
discussed in section 3.3.?  Rename as "Format of 'Makefile.am'"?
3.2. Strictness
3.3. The Uniform Naming Scheme
Rename as something like "Naming for automake variables" - the terminology
"Uniform Naming Scheme" is not used anywhere else.
3.4. Staying below the command line length limit
3.5. How derived variables are named
Reorder 3.4. and 3.5. so sections about variable naming are together.
3.6. Variables reserved for the user
3.7. Programs automake might require
This section is not very important as neither users of autotools nor users of
generated build systems need to know about these programs.  I can't suggest
another place for it, though.
4. Some example packages
Move 2.4 here.  Add an example that doesn't use subdirectories.
5. Creating a 'Makefile.in'
Rename 'Invoking automake' or 'automake Invocation' (node name was this already)

> I think there's an unusual complication that does NOT happen in many other 
> projects:
> there is no one master project.  The autotools are at least autoconf + 
> automake + libtool,
> which are maintained as separate projects, yet they are typically used 
> together.
> A tutorial needs to clearly explain how to use them *together*, interleaving 
> their discussion
> as much as possible, and omitting a lot of details (at least at first).

Also, where can discussion of documentation take place when
documentation of the whole system is spread across several projects.
Arguably the autoconf manual does a better job at giving an overview
than the automake manual, despite automake being the higher-level
project (i.e. automake uses autoconf, not the other way around).