Automake a case study

[Calvin Arndt]

I have a small project 

Directory Structure looks like this:

/Project/ ---> Build system files go here 
   |
   |
   |______/project/ ---> C src and headers go here
             |
             |
             |_______/docs ---> *.txt *.doc *.html 


Project/Makefile.am

SUBDIRS = project
docsdir = $(datadir)/project/docs
docs_DATA = project/docs/*

EXTRA_DIST = project.spec INSTALL-WIN32

.PHONY: $(DATA)


Project/project/Makefile.am

bin_PROGRAMS = project
project_SOURCES = *.c *.h

EXTRA_DIST = docs

I have 2 problems, first is that this works perfect for

make
make clean
make dist
make install

but make distcheck and make uninstall don't...

However when running make distcheck the make install target fails for the DATA.
 
However thats the easy problem ( I'm pretty sure these are automake bugs )

The hard problem is that on this list and in alot of other places I keep seeing 
references to "A really good book" and some other good docs on the "autotools"

I'm gonna try not to be to windy here, yet informative and enlightening...

I've been working on this project for several months now learning C as I go ONE 
concept at a time....

I put those .am's together myself! BUT it took me two months. Redhat did a 
great job writing that book but it's absolutely worthless. The book spends more 
than half of its breath talking about libtool libraries and 2/3 of whats left 
on autoconf and only lightly touches on automake. The examples for automake are 
poor.

The writing style assumes too much knowledge. Alot more often now you'll be 
seeing guys like me (I'm 43 have a family and full time job and come to the 
unix world from the windows world and I've been computing since before IBMPC 
64k 4.77mhz came out) due to the fast paced growth linux. Not the typical 
project participant!

Consequently a book that assumes way too much knowledge and really a program
as complicated automake, being so poorly documented, is a real roadblock for 
guys like me getting involved in open-source projects.

Here are problems I found:

PRIMARIES are very briefly touched on but never fully explained
and no where is there a list of all valid PRIMARIES
For me noticing that made me wonder what else wasn't being said.

I saw references to other parts of automake commands yet no lists of valid 
parts (keywords?) one specific example  noinst ... If _DIST and _DATA are valid 
PRIMARIES what is noinst_ ?

And this whole thing about invalid variables!!!! Never once does that book 
bother to drop to the level of explaining those! But I need that level of 
explanation and so do alot of other people! Add to that confusion the libtool 
portion of the book replacing the dot in filenames with underscores. (I 
actually understand why that's done [being only slightly versed in perl]) My 
point is a well documented program wouldn't require the user to be an expert in 
5 other programming languages to be able to use it and more importantly it's 
documentation. And I stand back on what I infered before. I don't have the time 
to learn 5 langs just to be able to use automake. And I should'nt have to.

In closing, I'm currently I'm using automake 1.6. The improvements in your 
software since the version I started with, have been wonderful! Automake is 
HUGHLY important to free-software (free as in freedom). However at this point 
it is also one of three tools creating HUGH roadblocks for me and many others 
like me from getting involved in open source projects.

Because of poor documentation...

Respectfully,
Calvin Arndt

Linux is not just the reallm of college "CS" majors anymore!