DOC: yet more updates to the CG build information

diff --git a/Documentation/contributor/build-notes.itexi b/Documentation/contributor/build-notes.itexi
index 6bea5628c83cc0885dfa72065a04adbb3c22fb4c..e5d7c67248100e599ec8c8ca313fd04a20db8851 100644 (file)
--- a/Documentation/contributor/build-notes.itexi
+++ b/Documentation/contributor/build-notes.itexi
@@ -282,7 +282,7 @@ 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:
+Next in @file{stepmake.make}:
 
 @example
 include $(addprefix $(stepdir)/,$(addsuffix -vars.make, $(STEPMAKE_TEMPLATES)))
@@ -297,11 +297,121 @@ which expands to:
 /home/phil/lilypond-git/stepmake/stepmake/install-vars.make.
 @end example
 
-Woo.  They all exist (they should - no - in front of the include).
+Woo.  They all exist (they should as there's no - in front of the
+include).  @file{generic-vars.make} sets loads of variables
+(funnily enough).  @file{toplevel-vars.make} is very short - one
+line commented as @code{# override Generic_vars.make:} and 2 as
+follows:
 
-Next step will be to work out what these do.
+@example
+# urg?
+include $(stepdir)/documentation-vars.make
+@end example
+
+I assume the urg comment refers to the fact that this should
+really just create more variables, but it actually sends us off to
+@file{/home/phil/lilypond-git/stepmake/stepmake/documentation-vars.make}.
+
+That file is a 3 line variable setting one.
+
+@file{po-vars.make} has the one-line comment @code{# empty}, as
+does @file{install-vars.make}.
+
+So now we're back to @file{stepmake.make}.
+
+The next lines are
+:
+@example
+# ugh. need to do this because of PATH :=$(top-src-dir)/..:$(PATH)
+include $(addprefix $(depth)/make/,$(addsuffix -vars.make, $(LOCALSTEPMAKE_TEMPLATES)))
+@end example
+
+and the include expands to:
+
+@example
+include ./make/generic-vars.make ./make/lilypond-vars.make.
+@end example
+
+These again set variables, and in some cases export them to allow
+child @code{make} processes to use them.
+
+The final 4 lines of @file{stepmake.make} are:
+
+@example
+include $(addprefix $(depth)/make/,$(addsuffix -rules.make, $(LOCALSTEPMAKE_TEMPLATES)))
+include $(addprefix $(stepdir)/,$(addsuffix -rules.make, $(STEPMAKE_TEMPLATES)))
+include $(addprefix $(depth)/make/,$(addsuffix -targets.make, $(LOCALSTEPMAKE_TEMPLATES)))
+include $(addprefix $(stepdir)/,$(addsuffix -targets.make, $(STEPMAKE_TEMPLATES)))
+@end example
+
+which expand as follows:
+
+@example
+include ./make/generic-rules.make ./make/lilypond-rules.make
+include
+  /home/phil/lilypond-git/stepmake/stepmake/generic-rules.make
+  /home/phil/lilypond-git/stepmake/stepmake/toplevel-rules.make
+  /home/phil/lilypond-git/stepmake/stepmake/po-rules.make
+  /home/phil/lilypond-git/stepmake/stepmake/install-rules.make
+include ./make/generic-targets.make ./make/lilypond-targets.make
+include
+  /home/phil/lilypond-git/stepmake/stepmake/generic-targets.make
+  /home/phil/lilypond-git/stepmake/stepmake/toplevel-targets.make
+  /home/phil/lilypond-git/stepmake/stepmake/po-targets.make
+  /home/phil/lilypond-git/stepmake/stepmake/install-targets.make
+@end example
+
+@file{lilypond-rules.make} is @code{#empty}
+@file{generic-rules.make} does seem to have 2 rules in it.  They
+are:
+
+@example
+$(outdir)/%.ly: %.lym4
+       $(M4) $< | sed "s/\`/,/g" > $@
+
+$(outdir)/%: %.in
+       rm -f $@
+       cat $< | sed $(sed-atfiles) | sed $(sed-atvariables) > $@
+@end example
+
+I believe the first rule is for *.ly files, and has a prerequisite
+that *.lym4 files must be built first.  The recipe is @code{m4  |
+sed "s/\`/,/g" >}.  Perhaps someone with more Unix/make knowledge
+can comment on exactly what the rules mean/do.
+
+@file{toplevel-rules.make} is @code{#empty}
+@file{po-rules.make} is @code{#empty}
+@file{install-rules.make} is @code{#empty}
+@file{generic-targets.make} contains 2 lines of comments.
+@file{lilypond-targets.make} contains only:
+
+@example
+## TODO: fail dist or web if no \version present.
+check-version:
+       grep -L version $(LY_FILES)
+@end example
+
+@file{stepmake/generic-targets.make} contains lots of rules - too
+many to list here - it seems to be the main file for rules. (FWIW
+I haven't actually found a rule for website: anywhere, although
+it clearly exists.  I have also found that you can display a rule
+in the terminal by typing, say @code{make -n website}.  This is
+probably common knowledge.
+
+@file{stepmake/toplevel-targets.make} adds a load of other (and
+occasionally the same) rules to the gernric-targets.
+
+@file{stepmake/po-targets.make} is rules for po* makes.
+
+@file{stepmake/install-targets.make} has rules for local-install*.
+
+And that's the end of stepmake.make.  Back to
+@file{GNUmakefile.in}.  More some other time.
 
-That's my 30 minutes for Monday.
+Another alterative approach to understanding the website build
+would be to redirect @code{make -n website} and @code{make website}
+to a text file and work through a) what it does and b) where the
+errors are occurring.
 
 Website build includes @ref{Building a bibliography}.