DOC: Further work on build system from 7 March 11

diff --git a/Documentation/contributor/build-notes.itexi b/Documentation/contributor/build-notes.itexi
index e7e0ba09cc2394e74b7dcdb4e3f7fe5b0b99a1af..6bea5628c83cc0885dfa72065a04adbb3c22fb4c 100644 (file)
--- a/Documentation/contributor/build-notes.itexi
+++ b/Documentation/contributor/build-notes.itexi
@@ -192,6 +192,117 @@ The file @file{lily-bib.bst} also has fairly extensive commenting.
 
 Start here: @file{make/website.make}
 
+Typing make website runs the file @file{GNUmakefile} from the
+build directory.  This only contains 3 lines:
+
+@example
+depth = .
+include config$(if $(conf),-$(conf),).make
+include $(configure-srcdir)/GNUmakefile.in
+@end example
+
+The variable @code{depth} is used throughout the make system to
+track how far down the directory structure the make is.  The first
+include sets lots of variables but doesn't "do" anything.  The
+second runs the file @file{GNUmakefile.in} from the top level
+source directory.
+
+This sets another load of variables, and then includes (i.e.
+immediately runs) @file{stepmake.make} from the @file{make}
+subdirectory.  This sets a load of other variables, does some
+testing to see if SCONS (another build tool?) is being used, and
+then runs @file{make/config.make} - which doesn't seem to exist...
+
+Next, it runs @file{make/toplevel-version.make}, which sets the
+version variables for major, minor, patch, stable, development and
+mypatchlevel (which seems to be used for patch numbers for
+non-stable versions only?).
+
+Next - @file{make/local.make}, which doesn't exist.
+
+Then a few more variable and the interesting comment:
+
+@example
+# Don't try to outsmart us, you puny computer!
+# Well, UGH.  This only removes builtin rules from
+@end example
+
+and then tests to see whether BUILTINS_REMOVED is defined.  It
+appears to be when I run make, and so
+@file{stepmake/stepmake/no-builtin-rules.make} is run.  The
+comment at the head of this file says:
+
+@example
+# UGH.  GNU make comes with implicit rules.
+# We don't want any of them, and can't force users to run
+# --no-builtin-rules
+@end example
+
+I've not studied that file at length, but assume it removes all
+make's build-in rules (e.g. @file{*.c} files are run through the
+GNU C compiler) - there's a lot of them in here, and a lot of
+comments, and I'd guess most of it isn't needed.
+
+We return to @file{stepmake.make}, where we hit the make rule all:
+The first line of this is:
+
+@example
+-include $(addprefix $(depth)/make/,$(addsuffix -inclusions.make, $(LOCALSTEPMAKE_TEMPLATES)))
+@end example
+
+which, when the variables are substituted, gives:
+
+@example
+./make/generic-inclusions.make
+./make/lilypond-inclusions.make.
+@end example
+
+(Note - according to the make documentation, -include is only
+different from include in that it doesn't produce any kind of
+error message when the included file doesn't exist).
+
+And the first file doesn't exist.  Nor the second.  Next:
+
+@example
+-include $(addprefix $(stepdir)/,$(addsuffix -inclusions.make, $(STEPMAKE_TEMPLATES)))
+@end example
+
+which expands to the following files:
+
+@example
+/home/phil/lilypond-git/stepmake/stepmake/generic-inclusions.make
+/home/phil/lilypond-git/stepmake/stepmake/toplevel-inclusions.make
+/home/phil/lilypond-git/stepmake/stepmake/po-inclusions.make
+/home/phil/lilypond-git/stepmake/stepmake/install-inclusions.make.
+@end example
+
+One little feature to notice here - these are all absolute file
+locations - the line prior to this used relative locations.  And
+none of these files exist, either.  (Further note - I'm assuming
+all these lines of make I'm following are autogenerated, but
+that'll be something else to discover.)
+
+Next:
+
+@example
+include $(addprefix $(stepdir)/,$(addsuffix -vars.make, $(STEPMAKE_TEMPLATES)))
+@end example
+
+which expands to:
+
+@example
+/home/phil/lilypond-git/stepmake/stepmake/generic-vars.make
+/home/phil/lilypond-git/stepmake/stepmake/toplevel-vars.make
+/home/phil/lilypond-git/stepmake/stepmake/po-vars.make
+/home/phil/lilypond-git/stepmake/stepmake/install-vars.make.
+@end example
+
+Woo.  They all exist (they should - no - in front of the include).
+
+Next step will be to work out what these do.
+
+That's my 30 minutes for Monday.
+
 Website build includes @ref{Building a bibliography}.