Documentation/contributor/build-notes.itexi

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2
   3
   4 @node Build system notes
   5 @chapter Build system notes
   6
   7 @warning{This chapter is in high flux, and is being run in a
   8 @qq{wiki-like} fashion.  Do not trust anything you read in this
   9 chapter.}
  10
  11 @menu
  12 * Build system overview::
  13 * Tips for working on the build system::
  14 * General build system notes::
  15 * Doc build::
  16 * Website build::
  17 * Building an Ubuntu distro::
  18 @end menu
  19
  20
  21 @node Build system overview
  22 @section Build system overview
  23
  24 Build system is currently GNU make, with an extra "stepmake" layer
  25 on top.  Look at files in @file{make/} and @file{stepmake/} and
  26 all @file{GNUmakefile}s.
  27
  28 There is wide-spread dissatisfaction with this system, and we are
  29 considering changing.  This would be a huge undertaking (estimated
  30 200+ hours).  This change will probably involve not using GNU make
  31 any more -- but a discussion about the precise build system will
  32 have to wait.  Before we reach that point, we need to figure out
  33 (at least approximately) what the current build system does.
  34
  35 Fundamentally, a build system does two things:
  36
  37 @enumerate
  38 @item
  39 Constructs command-line commands, for example:
  40
  41 @example
  42 lilypond-book \
  43   --tons --of --options \
  44   pitches.itely
  45 texi2pdf \
  46   --more --imperial --and --metric --tons --of --options \
  47   pitches.texi
  48 @end example
  49
  50 @item
  51 If there was a previous build, it decides which parts of the
  52 system need to be rebuilt.
  53
  54 @end enumerate
  55
  56 When I try to do anything in the build system, it helps to remind
  57 myself of this.  The "end result" is just a series of command-line
  58 commands.  All the black magick is just an attempt to construct
  59 those commands.
  60
  61 @node Tips for working on the build system
  62 @section Tips for working on the build system
  63
  64 @itemize
  65 @item
  66 Add:
  67
  68 @example
  69 echo "aaa"
  70
  71 echo "bbb"
  72 @end example
  73
  74 to the build system files in various places.  This will let you
  75 track where the program is, in various points of the build.
  76
  77 PH note.  There are lots of places where Make doesn't let you put
  78 echo commands.  My top tip for tracing how make runs is to put
  79
  80 @example
  81 $(error Some Text to display)
  82 @end example
  83
  84 This will stop make running and print the text @code{Some Text to
  85 display}.
  86
  87 End PH note.
  88
  89 @item
  90 First task: understand how @code{make website} works,
  91 @emph{without} the translations.  Looking at the english-only
  92 website is the best introduction to the build system... it only
  93 covers about 5% of the whole thing, but even that will likely take
  94 10 hours or more.
  95
  96 @end itemize
  97
  98
  99 @node General build system notes
 100 @section General build system notes
 101
 102 @menu
 103 * How stepmake works::
 104 @end menu
 105
 106 @node How stepmake works
 107 @subsection How stepmake works
 108
 109 Typing make website runs the file @file{GNUmakefile} from the
 110 build directory.  This only contains 3 lines:
 111
 112 @example
 113 depth = .
 114 include config$(if $(conf),-$(conf),).make
 115 include $(configure-srcdir)/GNUmakefile.in
 116 @end example
 117
 118 The variable @code{depth} is used throughout the make system to
 119 track how far down the directory structure the make is.  The first
 120 include sets lots of variables but doesn't "do" anything.  The
 121 second runs the file @file{GNUmakefile.in} from the top level
 122 source directory.
 123
 124 This sets another load of variables, and then includes (i.e.
 125 immediately runs) @file{stepmake.make} from the @file{make}
 126 subdirectory.  This sets a load of other variables, does some
 127 testing to see if SCONS (another build tool?) is being used, and
 128 then runs @file{make/config.make} - which doesn't seem to exist...
 129
 130 GP: scons is indeed a different build tool; I think that Jan
 131 experimented with it 5 years ago or something.  It seems like we
 132 still have bits and pieces of it floating around.
 133
 134 Next, it runs @file{make/toplevel-version.make}, which sets the
 135 version variables for major, minor, patch, stable, development and
 136 mypatchlevel (which seems to be used for patch numbers for
 137 non-stable versions only?).
 138
 139 Next - @file{make/local.make}, which doesn't exist.
 140
 141 Then a few more variable and the interesting comment:
 142
 143 @example
 144 # Don't try to outsmart us, you puny computer!
 145 # Well, UGH.  This only removes builtin rules from
 146 @end example
 147
 148 and then tests to see whether BUILTINS_REMOVED is defined.  It
 149 appears to be when I run make, and so
 150 @file{stepmake/stepmake/no-builtin-rules.make} is run.  The
 151 comment at the head of this file says:
 152
 153 @example
 154 # UGH.  GNU make comes with implicit rules.
 155 # We don't want any of them, and can't force users to run
 156 # --no-builtin-rules
 157 @end example
 158
 159 I've not studied that file at length, but assume it removes all
 160 make's build-in rules (e.g. @file{*.c} files are run through the
 161 GNU C compiler) - there's a lot of them in here, and a lot of
 162 comments, and I'd guess most of it isn't needed.
 163
 164 We return to @file{stepmake.make}, where we hit the make rule all:
 165 The first line of this is:
 166
 167 @smallexample
 168 -include $(addprefix $(depth)/make/,$(addsuffix -inclusions.make, $(LOCALSTEPMAKE_TEMPLATES)))
 169 @end smallexample
 170
 171 which, when the variables are substituted, gives:
 172
 173 @example
 174 ./make/generic-inclusions.make
 175 ./make/lilypond-inclusions.make.
 176 @end example
 177
 178 (Note - according to the make documentation, -include is only
 179 different from include in that it doesn't produce any kind of
 180 error message when the included file doesn't exist).
 181
 182 And the first file doesn't exist.  Nor the second.  Next:
 183
 184 @smallexample
 185 -include $(addprefix $(stepdir)/,$(addsuffix -inclusions.make, $(STEPMAKE_TEMPLATES)))
 186 @end smallexample
 187
 188 which expands to the following files:
 189
 190 @example
 191 /home/phil/lilypond-git/stepmake/stepmake/generic-inclusions.make
 192 /home/phil/lilypond-git/stepmake/stepmake/toplevel-inclusions.make
 193 /home/phil/lilypond-git/stepmake/stepmake/po-inclusions.make
 194 /home/phil/lilypond-git/stepmake/stepmake/install-inclusions.make.
 195 @end example
 196
 197 One little feature to notice here - these are all absolute file
 198 locations - the line prior to this used relative locations.  And
 199 none of these files exist, either.  (Further note - I'm assuming
 200 all these lines of make I'm following are autogenerated, but
 201 that'll be something else to discover.)
 202
 203 Next in @file{stepmake.make}:
 204
 205 @smallexample
 206 include $(addprefix $(stepdir)/,$(addsuffix -vars.make, $(STEPMAKE_TEMPLATES)))
 207 @end smallexample
 208
 209 which expands to:
 210
 211 @example
 212 /home/phil/lilypond-git/stepmake/stepmake/generic-vars.make
 213 /home/phil/lilypond-git/stepmake/stepmake/toplevel-vars.make
 214 /home/phil/lilypond-git/stepmake/stepmake/po-vars.make
 215 /home/phil/lilypond-git/stepmake/stepmake/install-vars.make.
 216 @end example
 217
 218 Woo.  They all exist (they should as there's no - in front of the
 219 include).  @file{generic-vars.make} sets loads of variables
 220 (funnily enough).  @file{toplevel-vars.make} is very short - one
 221 line commented as @code{# override Generic_vars.make:} and 2 as
 222 follows:
 223
 224 @example
 225 # urg?
 226 include $(stepdir)/documentation-vars.make
 227 @end example
 228
 229 I assume the urg comment refers to the fact that this should
 230 really just create more variables, but it actually sends us off to
 231 @file{/home/phil/lilypond-git/stepmake/stepmake/documentation-vars.make}.
 232
 233 That file is a 3 line variable setting one.
 234
 235 @file{po-vars.make} has the one-line comment @code{# empty}, as
 236 does @file{install-vars.make}.
 237
 238 So now we're back to @file{stepmake.make}.
 239
 240 The next lines are
 241 :
 242 @smallexample
 243 # ugh. need to do this because of PATH :=$(top-src-dir)/..:$(PATH)
 244 include $(addprefix $(depth)/make/,$(addsuffix -vars.make, $(LOCALSTEPMAKE_TEMPLATES)))
 245 @end smallexample
 246
 247 and the include expands to:
 248
 249 @example
 250 include ./make/generic-vars.make ./make/lilypond-vars.make.
 251 @end example
 252
 253 These again set variables, and in some cases export them to allow
 254 child @code{make} processes to use them.
 255
 256 The final 4 lines of @file{stepmake.make} are:
 257
 258 @smallexample
 259 include $(addprefix $(depth)/make/,$(addsuffix -rules.make, $(LOCALSTEPMAKE_TEMPLATES)))
 260 include $(addprefix $(stepdir)/,$(addsuffix -rules.make, $(STEPMAKE_TEMPLATES)))
 261 include $(addprefix $(depth)/make/,$(addsuffix -targets.make, $(LOCALSTEPMAKE_TEMPLATES)))
 262 include $(addprefix $(stepdir)/,$(addsuffix -targets.make, $(STEPMAKE_TEMPLATES)))
 263 @end smallexample
 264
 265 which expand as follows:
 266
 267 @example
 268 include ./make/generic-rules.make ./make/lilypond-rules.make
 269 include
 270   /home/phil/lilypond-git/stepmake/stepmake/generic-rules.make
 271   /home/phil/lilypond-git/stepmake/stepmake/toplevel-rules.make
 272   /home/phil/lilypond-git/stepmake/stepmake/po-rules.make
 273   /home/phil/lilypond-git/stepmake/stepmake/install-rules.make
 274 include ./make/generic-targets.make ./make/lilypond-targets.make
 275 include
 276   /home/phil/lilypond-git/stepmake/stepmake/generic-targets.make
 277   /home/phil/lilypond-git/stepmake/stepmake/toplevel-targets.make
 278   /home/phil/lilypond-git/stepmake/stepmake/po-targets.make
 279   /home/phil/lilypond-git/stepmake/stepmake/install-targets.make
 280 @end example
 281
 282 @file{lilypond-rules.make} is @code{#empty}
 283
 284 @file{generic-rules.make} does seem to have 2 rules in it.  They
 285 are:
 286
 287 @example
 288 $(outdir)/%.ly: %.lym4
 289         $(M4) $< | sed "s/\`/,/g" > $@
 290
 291 $(outdir)/%: %.in
 292         rm -f $@
 293         cat $< | sed $(sed-atfiles) | sed $(sed-atvariables) > $@
 294 @end example
 295
 296 I believe the first rule is for *.ly files, and has a prerequisite
 297 that *.lym4 files must be built first.  The recipe is @code{m4  |
 298 sed "s/\`/,/g" >}.  Perhaps someone with more Unix/make knowledge
 299 can comment on exactly what the rules mean/do.
 300
 301 @file{toplevel-rules.make} is @code{#empty}
 302
 303 @file{po-rules.make} is @code{#empty}
 304
 305 @file{install-rules.make} is @code{#empty}
 306
 307 @file{generic-targets.make} contains 2 lines of comments.
 308
 309 @file{lilypond-targets.make} contains only:
 310
 311 @example
 312 ## TODO: fail dist or web if no \version present.
 313 check-version:
 314         grep -L version $(LY_FILES)
 315 @end example
 316
 317 @file{stepmake/generic-targets.make} contains lots of rules - too
 318 many to list here - it seems to be the main file for rules. (FWIW
 319 I haven't actually found a rule for website: anywhere, although
 320 it clearly exists.  I have also found that you can display a rule
 321 in the terminal by typing, say @code{make -n website}.  This is
 322 probably common knowledge.
 323
 324 @file{stepmake/toplevel-targets.make} adds a load of other (and
 325 occasionally the same) rules to the gernric-targets.
 326
 327 @file{stepmake/po-targets.make} is rules for po* makes.
 328
 329 @file{stepmake/install-targets.make} has rules for local-install*.
 330
 331 And that's the end of stepmake.make.  Back to
 332 @file{GNUmakefile.in}.
 333
 334 A bit more info from 27 March.  I've put some error traces into
 335 @code{GNUmakefile} in the build directory, and it looks like the
 336 following lines actually cause the make to run (putting an error
 337 call above them - no make; below them - make):
 338
 339 @smallexample
 340 ifeq ($(out),www)
 341 # All web targets, except info image symlinks and info docs are
 342 # installed in non-recursing target from TOP-SRC-DIR
 343 install-WWW:
 344         -$(INSTALL) -m 755 -d $(DESTDIR)$(webdir)
 345         rsync -rl --exclude='*.signature' $(outdir)/offline-root $(DESTDIR)$(webdir)
 346         $(MAKE) -C Documentation omf-local-install
 347 @end smallexample
 348
 349 I don't currently understand the @code{ifeq}, since @code{$(out)}
 350 is empty at this point, but the line starting @w{@code{-$(INSTALL)}}
 351 translates to:
 352
 353 @example
 354 -/usr/bin/python /home/phil/lilypond-git/stepmake/bin/install.py \
 355   -c -m 755 -d /usr/local/share/doc/lilypond/html
 356 @end example
 357
 358 End of work for Sunday 27th.
 359
 360 Another alterative approach to understanding the website build
 361 would be to redirect @code{make -n website} and @code{make website}
 362 to a text file and work through a) what it does and b) where the
 363 errors are occurring.
 364
 365 GP: wow, all the above is much more complicated than I've ever
 366 looked at stuff -- I tend to do a "back first" approach (where I
 367 begin from the command-line that I want to modify, figure out
 368 where it's generated, and then figure out how to change the
 369 generated command-line), rather than a "front first" (where you
 370 begin from the "make" command).
 371
 372
 373 @node Doc build
 374 @section Doc build
 375
 376 @menu
 377 * The function of make doc::
 378 * Building a bibliography::
 379 @end menu
 380
 381 @node The function of make doc
 382 @subsection The function of make doc
 383
 384 The following is a set of notes on how make doc functions.
 385
 386 Preliminary question to be answered some time: where do all the
 387 GNUmakefiles come from.  They're in the build directory, but this
 388 is not part of source.  Must be the configure script.  And it
 389 looks like this comes from autogen.sh.  Must at some point kill
 390 the whole git directory, repull and see what is created when.
 391
 392 Anyway, here's how make doc progresses:
 393
 394 This is the build dependency tree from
 395 @file{stepmake/stepmake/generic-targets.make}:
 396
 397 @example
 398 doc: doc-stage-1
 399   doc-stage-1:
 400         $(MAKE) -C $(depth)/scripts/build out=
 401         $(MAKE) out=www WWW-1
 402           WWW-1: local-WWW-1
 403         $(LOOP)
 404           $(MAKE) out=www WWW-2
 405           WWW-2: local-WWW-2
 406             $(LOOP)
 407           $(MAKE) out=www WWW-post
 408 @end example
 409
 410 @example
 411 MAKE = make --no-builtin-rules
 412 -C = Change to directory before make
 413 @end example
 414
 415 doc-stage-1 does lots of opening and looking in files, but no
 416 processing.
 417
 418 @example
 419 Variable LOOP =
 420
 421 + make PACKAGE=LILYPOND package=lilypond -C python
 422 && make PACKAGE=LILYPOND package=lilypond -C scripts
 423 &&  make PACKAGE=LILYPOND package=lilypond -C flower
 424 &&  make PACKAGE=LILYPOND package=lilypond -C lily
 425 &&  make PACKAGE=LILYPOND package=lilypond -C mf
 426 &&  make PACKAGE=LILYPOND package=lilypond -C ly
 427 &&  make PACKAGE=LILYPOND package=lilypond -C tex
 428 &&  make PACKAGE=LILYPOND package=lilypond -C ps
 429 &&  make PACKAGE=LILYPOND package=lilypond -C scm
 430 &&  make PACKAGE=LILYPOND package=lilypond -C po
 431 &&  make PACKAGE=LILYPOND package=lilypond -C make
 432 &&  make PACKAGE=LILYPOND package=lilypond -C elisp
 433 &&  make PACKAGE=LILYPOND package=lilypond -C vim
 434 &&  make PACKAGE=LILYPOND package=lilypond -C input
 435 &&  make PACKAGE=LILYPOND package=lilypond -C stepmake
 436 &&  make PACKAGE=LILYPOND package=lilypond -C Documentation
 437 && true
 438 @end example
 439
 440 From git grep:
 441
 442 stepmake/stepmake/generic-vars.make has this:
 443
 444 @smallexample
 445 LOOP=+$(foreach i, $(SUBDIRS), $(MAKE) PACKAGE=$(PACKAGE) package=$(package) -C $(i) $@ &&) true
 446 @end smallexample
 447
 448 $@ is the name of the target - WWW-1 in this case.
 449
 450 In GNUmakefile.in we find:
 451
 452 @example
 453 SUBDIRS = python scripts \
 454         flower lily \
 455         mf ly \
 456         tex ps scm \
 457         po make \
 458         elisp vim \
 459         input \
 460         stepmake $(documentation-dir)
 461 @end example
 462
 463 So that's how we get the main make loop...
 464
 465 That loop expands like this:
 466
 467 @example
 468 make PACKAGE=LILYPOND package=lilypond -C python WWW-1 &&
 469 make PACKAGE=LILYPOND package=lilypond -C scripts WWW-1 &&
 470 make PACKAGE=LILYPOND package=lilypond -C flower WWW-1 &&
 471 make PACKAGE=LILYPOND package=lilypond -C lily WWW-1 &&
 472 make PACKAGE=LILYPOND package=lilypond -C mf WWW-1 &&
 473 make PACKAGE=LILYPOND package=lilypond -C ly WWW-1 &&
 474 make PACKAGE=LILYPOND package=lilypond -C tex WWW-1 &&
 475 make PACKAGE=LILYPOND package=lilypond -C ps WWW-1 &&
 476 make PACKAGE=LILYPOND package=lilypond -C scm WWW-1 &&
 477 make PACKAGE=LILYPOND package=lilypond -C po WWW-1 &&
 478 make PACKAGE=LILYPOND package=lilypond -C make WWW-1 &&
 479 make PACKAGE=LILYPOND package=lilypond -C elisp WWW-1 &&
 480 make PACKAGE=LILYPOND package=lilypond -C vim WWW-1 &&
 481 make PACKAGE=LILYPOND package=lilypond -C input WWW-1 &&
 482 make PACKAGE=LILYPOND package=lilypond -C stepmake WWW-1 &&
 483 make PACKAGE=LILYPOND package=lilypond -C Documentation WWW-1 &&
 484 true
 485 @end example
 486
 487 The directories up to and including vim produce no effect with
 488 make in non-debug mode, although debug does show lots of action.
 489
 490 @file{git/build/input/GNUmakefile} is:
 491
 492 @example
 493 depth=../
 494 include $(depth)/config$(if $(conf),-$(conf),).make
 495 include $(configure-srcdir)/./input/GNUmakefile
 496 MODULE_INCLUDES += $(src-dir)/$(outbase)
 497 @end example
 498
 499 The first include is:
 500
 501 @example
 502 ..//config.make
 503 @end example
 504
 505 (note the // which is strictly wrong)
 506
 507 which has lots of variables to set, but no action occurs.
 508
 509 The second is:
 510
 511 @example
 512 lilypond-git/./input/GNUmakefile
 513 @end example
 514
 515 which similarly doesn't create any actual action.
 516
 517 An error message at the end of build/input/GNUmakefile stops
 518 make processing before it moves on to regression - so where does
 519 that come from?
 520
 521 And the answer is - make processes all directories in the
 522 directory it's entered (with some exceptions like out and out-www)
 523 and so it changes to /regression.
 524
 525 It then seems to consider whether it needs to make/remake loads of
 526 makefiles.  Don't understand this yet.  Possibly these are all the
 527 makefiles it's processing, and it always checks they're up to date
 528 before processing other files?
 529
 530 Could be correct - some of this output is:
 531
 532 @example
 533 Must remake target `../../make/ly-inclusions.make'.
 534 Failed to remake target file `../../make/ly-inclusions.make'.
 535 @end example
 536
 537 Having decided that, it then leaves the directory and re-executes:
 538
 539 @example
 540 make PACKAGE=LILYPOND package=lilypond -C regression WWW-1
 541 @end example
 542
 543 The top of this make is:
 544
 545 @example
 546 This program built for i486-pc-linux-gnu
 547 Reading makefiles...
 548 Reading makefile `GNUmakefile'...
 549 Reading makefile `../..//config.make' (search path) (no ~ expansion)...
 550 @end example
 551
 552 which looks like it's re-reading all its known makefiles to check
 553 they're up to date.
 554
 555 (From the make manual:
 556
 557 To this end, after reading in all makefiles, make will consider each as a goal target and
 558 attempt to update it. If a makefile has a rule which says how to update it (found either
 559 in that very makefile or in another one) or if an implicit rule applies to it (see Chapter 10
 560 [Using Implicit Rules], page 103), it will be updated if necessary. After all makefiles have
 561 been checked, if any have actually been changed, make starts with a clean slate and reads
 562 all the makefiles over again. (It will also attempt to update each of them over again, but
 563 normally this will not change them again, since they are already up to date.)
 564
 565 So my assumption seems correct)
 566
 567 There appear to be about 74 of them.  After all the makefile
 568 checking, we get this:
 569
 570 @smallexample
 571 Updating goal targets....
 572 Considering target file `WWW-1'.
 573 File `WWW-1' does not exist.
 574 Considering target file `local-WWW-1'.
 575 File `local-WWW-1' does not exist.
 576 Considering target file `out-www/collated-files.texi'.
 577 File `out-www/collated-files.texi' does not exist.
 578 Looking for an implicit rule for `out-www/collated-files.texi'.
 579 Trying pattern rule with stem `collated-files.texi'.
 580 Trying implicit prerequisite `collated-files.texi.in'.
 581 Trying pattern rule with stem `collated-files.texi'.
 582 Trying implicit prerequisite `collated-files.texi.in'.
 583 Trying pattern rule with stem `collated-files'.
 584 Trying implicit prerequisite `collated-files.tely'.
 585 Trying pattern rule with stem `collated-files'.
 586 Trying implicit prerequisite `out-www/collated-files.tely'.
 587 Trying rule prerequisite `out-www/version.itexi'.
 588 Found prerequisite `out-www/version.itexi' as VPATH `/home/phil/lilypond-git/input/regression/out-www/version.itexi'
 589 @end smallexample
 590
 591 grep finds this if searching for local-WWW-1:
 592
 593 @example
 594 make/lysdoc-targets.make:
 595   local-WWW-1: $(outdir)/collated-files.texi $(outdir)/collated-files.pdf
 596 @end example
 597
 598 which means that local-WWW-1 depends on coll*.texi and coll*.pdf
 599 and so these will need to be checked to see if they're up to date.
 600 So make needs to find rules for both of those and (as it says) it
 601 certainly needs to make coll*.texi, since it doesn't exist.
 602
 603 In ly-rules.make we have:
 604
 605 @example
 606 .SUFFIXES: .doc .tely .texi .ly
 607 @end example
 608
 609 which I'll work out at some point, and also this rule:
 610
 611 @smallexample
 612 $(outdir)/%.texi: $(outdir)/%.tely $(outdir)/version.itexi $(DOCUMENTATION_LOCALE_TARGET) $(INIT_LY_SOURCES) $(SCHEME_SOURCES)
 613   LILYPOND_VERSION=$(TOPLEVEL_VERSION) $(PYTHON) $(LILYPOND_BOOK) $(LILYPOND_BOOK_INCLUDES) --process='$(LILYPOND_BOOK_PROCESS) $(LILYPOND_BOOK_INCLUDES) $(LILYPOND_BOOK_LILYPOND_FLAGS)' --output=$(outdir) --format=$(LILYPOND_BOOK_FORMAT) $(LILYPOND_BOOK_FLAGS) $<
 614 @end smallexample
 615
 616 Note that the recipe is a very long line - it could probably
 617 benefit from splitting.  The same makefile also has:
 618
 619 @smallexample
 620 $(outdir)/%.texi: $(outdir)/%.tely $(outdir)/version.itexi $(DOCUMENTATION_LOCALE_TARGET) $(INIT_LY_SOURCES) $(SCHEME_SOURCES)
 621   LILYPOND_VERSION=$(TOPLEVEL_VERSION) $(PYTHON) $(LILYPOND_BOOK) $(LILYPOND_BOOK_INCLUDES) --process='$(LILYPOND_BOOK_PROCESS) $(LILYPOND_BOOK_INCLUDES) $(LILYPOND_BOOK_LILYPOND_FLAGS)' --output=$(outdir) --format=$(LILYPOND_BOOK_FORMAT) $(LILYPOND_BOOK_FLAGS) $<
 622 @end smallexample
 623
 624 @noindent
 625 which seems to be an almost exact duplicate.  Whatever, the first
 626 one is executed first.  Have not checked if the second executes.
 627
 628 The first recipe translates as this:
 629
 630 @example
 631 LILYPOND_VERSION=2.15.0 /usr/bin/python   --process=' ' \
 632   --output=./out-www --format= --lily-output-dir \
 633     /home/phil/lilypond-git/build/out/lybook-db
 634 @end example
 635
 636 @noindent
 637 if we stop the build with an $(error), but I think this is because
 638 we need to allow it to process the dependencies first.  It looks
 639 like foo.texi is shown as being dependent on foo.tely, plus a load
 640 of other files.
 641
 642 @example
 643 DOCUMENTATION_LOCALE_TARGET is blank
 644 INIT_LY_SOURCES = /home/phil/lilypond-git/scm/auto-beam.scm \
 645   /home/phil/lilypond-git/scm/autochange.scm
 646 @end example
 647
 648 plus 10s (100s?) of other .scm files.
 649
 650 @example
 651 SCHEME_SOURCES = /home/phil/lilypond-git/ly/Welcome-to-LilyPond-MacOS.ly \
 652   /home/phil/lilypond-git/ly/Welcome_to_LilyPond.ly
 653 @end example
 654
 655 ditto .ly files.  This does seem a teency bit wrong - it looks like
 656 the .ly and .scm files have been interchanged.  ly-vars.make has
 657 these 2 lines:
 658
 659 @example
 660 INIT_LY_SOURCES = $(wildcard $(top-src-dir)/scm/*.scm)
 661 SCHEME_SOURCES = $(wildcard $(top-src-dir)/ly/*.ly)
 662 @end example
 663
 664 Looks like a bug.....
 665
 666 So it now works its way through all these files, checking if they
 667 need to be remade.  This is 100s of lines of the debug listing,
 668 although none in the normal list.  Clearly none has to be made
 669 since they're source files.  It concludes:
 670
 671 @example
 672 Must remake target `out-www/collated-files.tely'
 673 @end example
 674
 675 @file{lysdoc-rules.make} has this:
 676
 677 @smallexample
 678 $(outdir)/collated-files.tely: $(COLLATED_FILES)
 679         $(LYS_TO_TELY) --name=$(outdir)/collated-files.tely --title="$(TITLE)" --author="$(AUTHOR)" $^
 680 @end smallexample
 681
 682 @file{lysdoc-vars.make} has:
 683
 684 @example
 685 COLLATED_FILES = $(sort $(TEXINFO_SOURCES) $(LY_FILES) $(OUT_LY_FILES) )
 686 @end example
 687
 688 We find that:
 689
 690 @example
 691 TEXINFO_SOURCES = AAA-intro-regression.tely
 692 OUT_LY_FILES is empty
 693 @end example
 694
 695 so LY_FILES has the big long list of all the .ly files in the
 696 regression directory.
 697
 698 This kicks off
 699
 700 @example
 701 /home/phil/lilypond-git/build/scripts/build/out/lys-to-tely
 702 @end example
 703
 704 with a list of all the files in the regression test directory. This
 705 should (I believe) create the file collated-files.tely.
 706
 707 So the next rule in make is for @file{version.itexi}, and make duly
 708 checks this.  There's a rule in @file{doc-i18n-root-rules.make} that this
 709 depends on @file{git/VERSION}:
 710
 711 @smallexample
 712 $(outdir)/version.%: $(top-src-dir)/VERSION
 713         $(PYTHON) $(top-src-dir)/scripts/build/create-version-itexi.py > $@
 714 @end smallexample
 715
 716 This causes create-version-itexi.py to run and create
 717 version.itexi.
 718
 719 Once that's done, all the other *.scm and *.ly files are checked
 720 and since they have no rules associated, they aren't remade (just
 721 as well for source files, really).  Since version.itexi was remade
 722 make concludes that collated-files.texi must be remade.  To do
 723 this, it runs lilypond-book.py on collated-files.tely, as below:
 724
 725 @example
 726 LILYPOND_VERSION=2.15.0
 727   /usr/bin/python
 728   /home/phil/lilypond-git/scripts/lilypond-book.py
 729     -I /home/phil/lilypond-git/input/regression/
 730     -I ./out-www -I /home/phil/lilypond-git/input
 731     -I /home/phil/lilypond-git/Documentation
 732     -I /home/phil/lilypond-git/Documentation/snippets
 733     -I /home/phil/lilypond-git/input/regression/
 734     -I /home/phil/lilypond-git/Documentation/included/
 735     -I /home/phil/lilypond-git/build/mf/out/
 736     -I /home/phil/lilypond-git/build/mf/out/
 737     -I /home/phil/lilypond-git/Documentation/pictures
 738     -I /home/phil/lilypond-git/build/Documentation/pictures/./out-www
 739     --process='/home/phil/lilypond-git/build/out/bin/lilypond
 740     -I /home/phil/lilypond-git/input/regression/
 741     -I ./out-www
 742     -I /home/phil/lilypond-git/input
 743     -I /home/phil/lilypond-git/Documentation
 744     -I /home/phil/lilypond-git/Documentation/snippets
 745     -I /home/phil/lilypond-git/input/regression/
 746     -I /home/phil/lilypond-git/Documentation/included/
 747     -I /home/phil/lilypond-git/build/mf/out/
 748     -I /home/phil/lilypond-git/build/mf/out/
 749     -I /home/phil/lilypond-git/Documentation/pictures
 750     -I /home/phil/lilypond-git/build/Documentation/pictures/./out-www
 751     -dbackend=eps
 752     --formats=ps,png,pdf
 753     -dinclude-eps-fonts
 754     -dgs-load-fonts
 755     --header=doctitle
 756     --header=doctitlecs
 757     --header=doctitlede
 758     --header=doctitlees
 759     --header=doctitlefr
 760     --header=doctitlehu
 761     --header=doctitleit
 762     --header=doctitleja
 763     --header=doctitlenl
 764     --header=doctitlezh
 765     --header=texidoc
 766     --header=texidoccs
 767     --header=texidocde
 768     --header=texidoces
 769     --header=texidocfr
 770     --header=texidochu
 771     --header=texidocit
 772     --header=texidocja
 773     --header=texidocnl
 774     --header=texidoczh
 775     -dcheck-internal-types
 776     -ddump-signatures
 777     -danti-alias-factor=2'
 778     --output=./out-www
 779     --format=texi-html
 780     --verbose
 781     --lily-output-dir /home/phil/lilypond-git/build/out/lybook-db
 782     out-www/collated-files.tely
 783 @end example
 784
 785 So - lilypond-book runs on:
 786
 787 @example
 788 input/regression/out-www/collated-files.tely
 789 @end example
 790
 791
 792 Note the --verbose flag - this is from the make variable
 793 LILYPOND_BOOK_VERBOSE which is added to the make variable
 794 LILYPOND_BOOK_FLAGS.
 795
 796 Now found the invocation to write some of the image files.  It's
 797 like this:
 798
 799 @example
 800 /home/phil/lilypond-git/build/out/bin/lilypond
 801   -I /home/phil/lilypond-git/input/regression/
 802   -I ./out-www -I /home/phil/lilypond-git/input
 803   -I /home/phil/lilypond-git/Documentation
 804   -I /home/phil/lilypond-git/Documentation/snippets
 805   -I /home/phil/lilypond-git/input/regression/
 806   -I /home/phil/lilypond-git/Documentation/included/
 807   -I /home/phil/lilypond-git/build/mf/out/
 808   -I /home/phil/lilypond-git/build/mf/out/
 809   -I /home/phil/lilypond-git/Documentation/pictures
 810   -I /home/phil/lilypond-git/build/Documentation/pictures/./out-www
 811   -dbackend=eps
 812   --formats=ps,png,pdf
 813   -dinclude-eps-fonts
 814   -dgs-load-fonts
 815   --header=doctitle
 816   --header=doctitlecs
 817   --header=doctitlede
 818   --header=doctitlees
 819   --header=doctitlefr
 820   --header=doctitlehu
 821   --header=doctitleit
 822   --header=doctitleja
 823   --header=doctitlenl
 824   --header=doctitlezh
 825   --header=texidoc
 826   --header=texidoccs
 827   --header=texidocde
 828   --header=texidoces
 829   --header=texidocfr
 830   --header=texidochu
 831   --header=texidocit
 832   --header=texidocja
 833   --header=texidocnl
 834   --header=texidoczh
 835   -dcheck-internal-types
 836   -ddump-signatures
 837   -danti-alias-factor=2
 838   -I  "/home/phil/lilypond-git/build/out/lybook-db"
 839   -I  "/home/phil/lilypond-git/build/input/regression"
 840   -I  "/home/phil/lilypond-git/input/regression"
 841   -I  "/home/phil/lilypond-git/build/input/regression/out-www"
 842   -I  "/home/phil/lilypond-git/input"
 843   -I  "/home/phil/lilypond-git/Documentation"
 844   -I  "/home/phil/lilypond-git/Documentation/snippets"
 845   -I  "/home/phil/lilypond-git/input/regression"
 846   -I  "/home/phil/lilypond-git/Documentation/included"
 847   -I  "/home/phil/lilypond-git/build/mf/out"
 848   -I  "/home/phil/lilypond-git/build/mf/out"
 849   -I  "/home/phil/lilypond-git/Documentation/pictures"
 850   -I  "/home/phil/lilypond-git/build/Documentation/pictures/out-www"
 851   --formats=eps
 852   --verbose
 853   -deps-box-padding=3.000000
 854   -dread-file-list
 855   -dno-strip-output-dir
 856   "/home/phil/lilypond-git/build/out/lybook-db/snippet-names--415419468.ly"'
 857 @end example
 858
 859 Note the --verbose.  This causes 100s of lines of Lily debug output.
 860 But at present I can't work out where the flag comes from. Later.
 861
 862
 863 @node Building a bibliography
 864 @subsection Building a bibliography
 865
 866 Bibliography files contain a list of citations, like this:
 867
 868 @example
 869 @@Book@{vinci,
 870   author = @{Vinci, Albert C.@},
 871   title = @{Fundamentals of Traditional Music Notation@},
 872   publisher = @{Kent State University Press@},
 873   year = @{1989@}
 874 @}
 875 @end example
 876
 877 There are a variety of types of citation (e.g. Book (as above),
 878 article, publication).  Each cited publication has a list of
 879 entries that can be used to identify the publication.
 880 Bibliograpies are normally stored as files with a .bib
 881 extension.  One part of the doc-build process is transforming the
 882 bibliography information into @code{texinfo} files.  The commands
 883 to do this are in the @file{GNUmakefile} in the
 884 @file{Documentation} directory.
 885
 886 A typical line of the makefile to translate a single bibliography
 887 is:
 888
 889 @example
 890 $(outdir)/colorado.itexi:
 891         BSTINPUTS=$(src-dir)/essay $(buildscript-dir)/bib2texi \
 892                 -s $(top-src-dir)/Documentation/lily-bib \
 893                 -o $(outdir)/colorado.itexi \
 894                 $(src-dir)/essay/colorado.bib
 895 @end example
 896
 897 Line by line:
 898
 899 @example
 900 $(outdir)/colorado.itexi:
 901 @end example
 902
 903 We're making the file @file{colorado.itexi} and so this is the
 904 make instruction.
 905
 906 @example
 907         BSTINPUTS=$(src-dir)/essay $(buildscript-dir)/bib2texi \
 908 @end example
 909
 910 It's in the @file{essay} directory and we want to run the
 911 bib2texi.py script against it.
 912
 913 @example
 914                 -s $(top-src-dir)/Documentation/lily-bib \
 915 @end example
 916
 917 The style template is @file{lily-bib.bst} and is found in the
 918 @file{Documentation} directory.
 919
 920 @example
 921                 -o $(outdir)/colorado.itexi \
 922 @end example
 923
 924 The output file in @file{colorado.itexi}.
 925
 926 @example
 927                 $(src-dir)/essay/colorado.bib
 928 @end example
 929
 930 The input file is @file{colorado.bib} in the @file{essay}
 931 directory.
 932
 933 The @code{bib2texi} Python script used to be used with a variety
 934 of options, but now is always called using the same options, as
 935 above.  Its job is to create the file containing the options for
 936 @code{bibtex} (the program that actually does the translation),
 937 run bibtex, and then clean up some temporary files.  Its main
 938 "value add" is the creation of the options file, using this code:
 939
 940 @example
 941 open (tmpfile + '.aux', 'w').write (r'''
 942 \relax
 943 \citation@{*@}
 944 \bibstyle@{%(style)s@}
 945 \bibdata@{%(files)s@}''' % vars ())
 946 @end example
 947
 948 The key items are the style file (now always lily-bib for us) and
 949 the input file.
 950
 951 The style file is written in its own specialised language,
 952 described to some extent at
 953
 954 @example
 955 @uref{http://amath.colorado.edu/documentation/LaTeX/reference/faq/bibtex.pdf}
 956 @end example
 957
 958 The file @file{lily-bib.bst} also has fairly extensive commenting.
 959
 960 @node Website build
 961 @section Website build
 962
 963 Start here: @file{make/website.make}
 964
 965 The overall build system begins with @ref{How stepmake works}.
 966 Summary: when you type @code{make website} this ends up running
 967 @file{GNUmakefile.in} in the @file{git} directory.  Right at the
 968 bottom, this has the lines:
 969
 970 @example
 971 # we want this separate for security; see CG 4.2.  -gp
 972 website:
 973         $(MAKE) config_make=$(config_make) \
 974                 top-src-dir=$(top-src-dir) \
 975                 -f $(top-src-dir)/make/website.make \
 976                 website
 977 @end example
 978
 979 On my system this expands to:
 980
 981 @example
 982 make --no-builtin-rules config_make=./config.make \
 983                 top-src-dir=/home/phil/lilypond-git \
 984                 -f /home/phil/lilypond-git/make/website.make \
 985                 website
 986 @end example
 987
 988 We see that the @code{$(MAKE)} expands to
 989 @code{make --no-builtin-rules} which is how @code{MAKE} is
 990 defined higher up the makefile.  The -f switch defines the
 991 makefile to be used - in this case
 992 @file{git/make/website.make}.  That's where all the action
 993 happens.
 994
 995 We believe that note that *none* of the variables that
 996 are loaded (from depth to version numbers to whatever) are used in
 997 @file{website.make}.  Instead, @file{website.make} sets up its own
 998 variables at the top of the file.  If you're wondering if there's
 999 some smart reason for this, then the answer is "no".  It's because
1000 I (GP) didn't know/trust the original variables when I was writing
1001 that file.
1002
1003 Website build includes @ref{Building a bibliography}.
1004
1005 @subsubheading Output from @code{make -n website}
1006
1007 Sorry, including this output directly produces problems in the
1008 build system.  Please run:
1009
1010 @example
1011 make -n website &> my-file.txt
1012 @end example
1013
1014 to see the full output from the make.
1015
1016 @subsubheading website.make variables
1017
1018 The file begins by setting up some variables.  These
1019 may/might/probably mirror existing variables, but lacking any docs
1020 about those variables, I thought it would be simpler to keep
1021 everything in the same file.
1022
1023 Note that for security reasons, we @strong{don't} call scripts in
1024 the git dir when building on the web server.  See @ref{Uploading
1025 and security}.  So we definitely want to keep those definitions
1026 for the WEBSITE_ONLY_BUILD.
1027
1028 After some split WEBSITE_ONLY_BUILD vs. normal build definitions,
1029 there's another bunch of lines setting up generic variables.
1030
1031 @subsubheading website.make building parts
1032
1033 Parts of @file{website.make}:
1034
1035 @itemize
1036
1037 @item
1038 @code{website:}
1039 this is the "master" rule.  It calls the other rules in order,
1040 then copies some extra files around - see below for further
1041 of the process it produces.
1042
1043 @item
1044 @code{website-version}:
1045 this calls the python scripts below:
1046
1047 @itemize
1048 @item
1049 @example
1050 scripts/build/create-version-itexi.py
1051 @end example
1052
1053 This writes a @@version, @@versionStable, and @@versionDevel based
1054 on the top-level VERSIONS file, to
1055 @code{out-website/version.itexi}
1056
1057 @item
1058 @example
1059 scripts/build/create-weblinks-itexi.py
1060 @end example
1061
1062 This creates a ton of macros in @code{out-website/weblinks.itexi}.
1063 Stuff like @@downloadStableLinuxNormal, @@downloadStableWidows,
1064 @code{@@stableDocsNotationPdf@{@}}, @@downloadDevelSourch-zh.
1065
1066 It's quite monstrous because it deals with combinations of
1067 stable/devel, source/docs, lang/lang/lang*10, etc.
1068
1069 @end itemize
1070
1071
1072 @item
1073 @code{website-xrefs:}
1074 creates files used for complicated "out-of-build" references to
1075 @code{out-website/*.xref-map}
1076
1077 If you just write @@ref@{@}, then all's groovy and we wouldn't
1078 need this.  But if you write @@rlearning@{@}, then our custom
1079 texi2html init file needs to know about our custom xref file
1080 format, which tells our custom texi2html init file how to create
1081 the link.
1082
1083 GP: we should have a separate @@node to discuss xrefs.  Also, take a
1084 quick look at a generated xref file -- it's basically just a list
1085 of @@node's [sic teenager pluralization rule] from the file.
1086
1087 @item
1088 @code{website-bib:}
1089 generates the bibliography texinfo files from the .bib files - in
1090 the case of the website build these are @file{others-did.bib} and
1091 @file{we-wrote.bib}.
1092
1093 @item
1094 @code{website-texinfo:}
1095 this is the main part; it calles texi2html to generate the actual
1096 html.  It also has a ton of options to texi2html to pass info to
1097 our custom init file.
1098
1099 The file actually built is called @file{web.texi}, and is either
1100 in the @file{Documentation} directory, or a sub-directory specific
1101 to the language.
1102
1103 The options file is @file{/Documentation/lilypond-texi2html.init}.
1104 This contains *lots* of option and configuration stuff, and also
1105 includes the line:
1106
1107 @smallexample
1108 print STDERR "Initializing settings for web site: [$Texi2HTML::THISDOC@{current_lang@}]\n";
1109 @end smallexample
1110
1111 This is where one of the console messages is generated.
1112
1113 We have somewhere between 2-4 different ways "to pass info to our
1114 custom init file".  This is highly Not Good (tm), but that's how
1115 things work at the moment.
1116
1117 After texi2html, it does some black magick to deal with
1118 untranslated nodes in the translations.  Despite writing that
1119 part, I can't remember how it works.  But in theory, you could
1120 figure it out by copy&pasting each part of the command (by "part",
1121 I mean "stuff before each | pipe"), substituting the variables,
1122 then looking at the text that's output.  For example,
1123
1124 @example
1125   ls $(OUT)/$$l/*.html
1126 @end example
1127
1128 is going to print a list of all html files, in all languages, in
1129 the build directory.  Then more stuff happens to each of those
1130 files (that's what xargs does).
1131
1132 @item
1133 @code{website-css:}
1134 just copies files to the build dir.
1135
1136 @item
1137 @code{website-pictures, website-examples:}
1138 more file copies, with an if statement to handle if you don't have
1139 any generated pictures/examples.
1140
1141 @item
1142 @code{web-post:}
1143 runs:
1144
1145 @example
1146 scripts/build/website_post.py
1147 @end example
1148
1149 which, it adds the "this page is translated in klingon" to the
1150 bottom of html pages, and adds the google analytics javascript.
1151 It also has hard-coded lilypond version numbers, which is Bad
1152 (tm).
1153
1154 @end itemize
1155
1156 Here's a summary of what gets called, in what order, when we run
1157 @code{make website}
1158
1159 @example
1160 website:
1161   website-texinfo:
1162     website-version:
1163       creates version.itexi and weblinks.itexi
1164     website-xrefs:
1165       runs extract_texi_filenames.py
1166     website-bibs:
1167       creates bibliography files, described above
1168   website-css:
1169     copies css files
1170   website-pictures:
1171     copies pictures
1172   website-examples:
1173     copies examples
1174   web-post:
1175     runs website_post.py
1176   Then some file copying
1177 @end example
1178
1179 @node Building an Ubuntu distro
1180 @section Building an Ubuntu distro
1181
1182
1183 Here's the short instruction on how to create lilybuntu iso image
1184 (Jonathan Kulp did this on a spare drive,
1185 but he supposes it can be done in a VM too):
1186
1187 @enumerate
1188
1189 @item
1190 Install ubuntu, reboot.
1191 @item
1192 Run all updates, reboot if asked.
1193 @item
1194 Enable src repos, refresh package lists.
1195 @item
1196 Install LilyPond build deps:
1197 @example
1198 sudo apt-get build-dep lilypond
1199 @end example
1200 @item
1201 Install git and autoconf:
1202 @example
1203 sudo apt-get install git-core gitk autoconf
1204 @end example
1205
1206 @item
1207 Test to see whether everything works fine now:
1208 @enumerate
1209 @item
1210 use @command{lily-git.tcl} to grab source files
1211 @item
1212 go to source dir and do
1213 @example
1214 "./autogen.sh" ; make ; make doc
1215 @end example
1216 @item
1217 if all compiles, move on to iso creation...
1218 @end enumerate
1219
1220 @item
1221 Download & install "remastersys":
1222 @uref{http://sourceforge.net/projects/remastersys/, http://sourceforge.net/projects/remastersys/}
1223 @item
1224 Copy @command{lily-git.tcl} script file into @file{/etc/skel/}.
1225 @item
1226 Modify @file{/etc/remastersys.conf} as desired (change @code{.iso} name,
1227 default live session username, etc).
1228 @item
1229 Remove non-essential desktop software as desired.
1230 @item
1231 Create iso:
1232 @example
1233 sudo remastersys dist
1234 @end example
1235 New iso is in @file{/home/remastersys/remastersys/}.
1236 @item
1237 Test iso by installing in VM and repeating steps above for
1238 getting source files and building lp and docs.
1239
1240 @end enumerate