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.)
 
 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)))
 
 @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
 
 /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}.
 
 
 Website build includes @ref{Building a bibliography}.