lilypond-0.1.57

diff --git a/Documentation/automake.urgh b/Documentation/automake.urgh
new file mode 100644 (file)
index 0000000..4d811d1
--- /dev/null
+++ b/Documentation/automake.urgh
@@ -0,0 +1,97 @@
+
+WHAT'S WRONG WITH AUTOMAKE?
+
+
+We have tried to use automake and found it to be inadequate for our
+needs for several reasons.  On the surface the shortcomings to
+automake may seem bugs or "not-yet-completed" features.  However, make
+itself is broken, and any tool built on top of make is broken as well.
+
+
+IRRITATIONS
+
+We'll start with the superficial irritations first:
+
+       - there is no intrinsic support for wildcarding; Adding
+support for wildcarding adds yet another layer to a top-heavy system.
+
+This may sound silly, but for a fast moving project, with 500
+sourcefiles, one does not want to administer a list of filenames by
+hand: files are created, deleted and moved very often, and wildcarding
+prevents that distributions miss files.
+
+
+       - Automake tries to cater for every taste of make.  But anyone
+who does more than the trivial (configure; make install) has to
+install automake and GNU make anyway.  Automake's universal make
+support is good for tools that have to be highly portable, but you
+have pay in ease of use and speed. 
+
+       - Automake is very much targeted at standard GNU packages that
+are written in C (or C++) and come with info-pages.  If you want to add
+dependencies from TeX or METAFONT files you are out of luck.  Ditto if
+you have weird file types (.pod), weird programming languages, etc.
+
+       - Dependency handling is unreliable in our experience. On
+several occasions we had unexplainable errors, that went away after
+doing a make distclean, and recompile.
+
+       - It is slower, much slower than a tailor made solution.  On
+JCNs machine this is a diffence of 800% (17 minutes in stead of 2) for
+every distribution made; this constitutes 45 minutes of irritation on
+a hacking-night.
+
+       - For a large project, a specialised Makefile system costs
+relatively little extra effort.  The extra effort pays itself back in speed
+and control.
+
+       - The Makefiles, Makefile.ins, and extensions constitute a
+huge amount of state.  We found it hard to reproduce bugs in automake
+(Strictly spoken they aren't bugs, as we haven't diagnosed because we
+couldn't reproduce them.)
+
+
+FUNDAMENTAL PROBLEMS
+
+Many of the fundamental problems can be traced back to flaws in make:
+
+       - make is not standardised.  The only decent implementation is
+GNU make, and GNU make is not widespread enough to require GNU make for
+compiling GNU tools.
+
+       - make does not have enough meta-ness: one cannot manipulate
+dependencies and rules in make: they cannot be put in variables,
+mapped at lists, etc.
+
+(In our tailor made system, we worked around this non-feature by using
+generic include files as a stopgap function call.)
+
+       - VPATH is a broken concept: programs should not think on
+their own; thinking is the programmer's job.  make should do exactly
+as it is told, and make should enable easy formulation of these
+commands commands.
+
+automake is tries to solve these problems by building on top of this
+broken tool: an extra layer of complexity is added, with
+self-modifying  Makefiles, and different Makefile versions for
+maintainer and user.
+
+
+CONCLUSIONS
+
+We could be called "cheap" for complaining about the above points,
+while not even filing decent bugreports.  The reality is that we
+ourselves are busy and that we don't find it amusing to hunt for and
+fix bugs in a fix (automake) for a broken tool (make).
+
+It should also be emphasised that we still think that automake is a
+good tool: it is excellent for small projects, and reasonable for big
+projects that are fully "standard."  However, for LilyPond, with its
+many sourcefiles and many different filetypes we found it unwieldy.
+
+We hope that some day a better replacement for make comes along, so
+that the gruesomeness of make and friends may die in oblivion.  (*)
+
+(*) I personally would like to enter a Makefile as functional program,
+whose execution caches function results on the disk as files.  But I
+shan't bother you further with my vaporware thoughts..