]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/contributor/build-notes.itexi
CG: more website build details.
[lilypond.git] / 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 @item
78 First task: understand how @code{make website} works,
79 @emph{without} the translations.  Looking at the english-only
80 website is the best introduction to the build system... it only
81 covers about 5% of the whole thing, but even that will likely take
82 10 hours or more.
83
84 @end itemize
85
86
87 @node General build system notes
88 @section General build system notes
89
90 @menu
91 * How stepmake works::
92 @end menu
93
94 @node How stepmake works
95 @subsection How stepmake works
96
97 Typing make website runs the file @file{GNUmakefile} from the
98 build directory.  This only contains 3 lines:
99
100 @example
101 depth = .
102 include config$(if $(conf),-$(conf),).make
103 include $(configure-srcdir)/GNUmakefile.in
104 @end example
105
106 The variable @code{depth} is used throughout the make system to
107 track how far down the directory structure the make is.  The first
108 include sets lots of variables but doesn't "do" anything.  The
109 second runs the file @file{GNUmakefile.in} from the top level
110 source directory.
111
112 This sets another load of variables, and then includes (i.e.
113 immediately runs) @file{stepmake.make} from the @file{make}
114 subdirectory.  This sets a load of other variables, does some
115 testing to see if SCONS (another build tool?) is being used, and
116 then runs @file{make/config.make} - which doesn't seem to exist...
117
118 GP: scons is indeed a different build tool; I think that Jan
119 experimented with it 5 years ago or something.  It seems like we
120 still have bits and pieces of it floating around.
121
122 Next, it runs @file{make/toplevel-version.make}, which sets the
123 version variables for major, minor, patch, stable, development and
124 mypatchlevel (which seems to be used for patch numbers for
125 non-stable versions only?).
126
127 Next - @file{make/local.make}, which doesn't exist.
128
129 Then a few more variable and the interesting comment:
130
131 @example
132 # Don't try to outsmart us, you puny computer!
133 # Well, UGH.  This only removes builtin rules from
134 @end example
135
136 and then tests to see whether BUILTINS_REMOVED is defined.  It
137 appears to be when I run make, and so
138 @file{stepmake/stepmake/no-builtin-rules.make} is run.  The
139 comment at the head of this file says:
140
141 @example
142 # UGH.  GNU make comes with implicit rules.
143 # We don't want any of them, and can't force users to run
144 # --no-builtin-rules
145 @end example
146
147 I've not studied that file at length, but assume it removes all
148 make's build-in rules (e.g. @file{*.c} files are run through the
149 GNU C compiler) - there's a lot of them in here, and a lot of
150 comments, and I'd guess most of it isn't needed.
151
152 We return to @file{stepmake.make}, where we hit the make rule all:
153 The first line of this is:
154
155 @example
156 -include $(addprefix $(depth)/make/,$(addsuffix -inclusions.make, $(LOCALSTEPMAKE_TEMPLATES)))
157 @end example
158
159 which, when the variables are substituted, gives:
160
161 @example
162 ./make/generic-inclusions.make
163 ./make/lilypond-inclusions.make.
164 @end example
165
166 (Note - according to the make documentation, -include is only
167 different from include in that it doesn't produce any kind of
168 error message when the included file doesn't exist).
169
170 And the first file doesn't exist.  Nor the second.  Next:
171
172 @example
173 -include $(addprefix $(stepdir)/,$(addsuffix -inclusions.make, $(STEPMAKE_TEMPLATES)))
174 @end example
175
176 which expands to the following files:
177
178 @example
179 /home/phil/lilypond-git/stepmake/stepmake/generic-inclusions.make
180 /home/phil/lilypond-git/stepmake/stepmake/toplevel-inclusions.make
181 /home/phil/lilypond-git/stepmake/stepmake/po-inclusions.make
182 /home/phil/lilypond-git/stepmake/stepmake/install-inclusions.make.
183 @end example
184
185 One little feature to notice here - these are all absolute file
186 locations - the line prior to this used relative locations.  And
187 none of these files exist, either.  (Further note - I'm assuming
188 all these lines of make I'm following are autogenerated, but
189 that'll be something else to discover.)
190
191 Next in @file{stepmake.make}:
192
193 @example
194 include $(addprefix $(stepdir)/,$(addsuffix -vars.make, $(STEPMAKE_TEMPLATES)))
195 @end example
196
197 which expands to:
198
199 @example
200 /home/phil/lilypond-git/stepmake/stepmake/generic-vars.make
201 /home/phil/lilypond-git/stepmake/stepmake/toplevel-vars.make
202 /home/phil/lilypond-git/stepmake/stepmake/po-vars.make
203 /home/phil/lilypond-git/stepmake/stepmake/install-vars.make.
204 @end example
205
206 Woo.  They all exist (they should as there's no - in front of the
207 include).  @file{generic-vars.make} sets loads of variables
208 (funnily enough).  @file{toplevel-vars.make} is very short - one
209 line commented as @code{# override Generic_vars.make:} and 2 as
210 follows:
211
212 @example
213 # urg?
214 include $(stepdir)/documentation-vars.make
215 @end example
216
217 I assume the urg comment refers to the fact that this should
218 really just create more variables, but it actually sends us off to
219 @file{/home/phil/lilypond-git/stepmake/stepmake/documentation-vars.make}.
220
221 That file is a 3 line variable setting one.
222
223 @file{po-vars.make} has the one-line comment @code{# empty}, as
224 does @file{install-vars.make}.
225
226 So now we're back to @file{stepmake.make}.
227
228 The next lines are
229 :
230 @example
231 # ugh. need to do this because of PATH :=$(top-src-dir)/..:$(PATH)
232 include $(addprefix $(depth)/make/,$(addsuffix -vars.make, $(LOCALSTEPMAKE_TEMPLATES)))
233 @end example
234
235 and the include expands to:
236
237 @example
238 include ./make/generic-vars.make ./make/lilypond-vars.make.
239 @end example
240
241 These again set variables, and in some cases export them to allow
242 child @code{make} processes to use them.
243
244 The final 4 lines of @file{stepmake.make} are:
245
246 @example
247 include $(addprefix $(depth)/make/,$(addsuffix -rules.make, $(LOCALSTEPMAKE_TEMPLATES)))
248 include $(addprefix $(stepdir)/,$(addsuffix -rules.make, $(STEPMAKE_TEMPLATES)))
249 include $(addprefix $(depth)/make/,$(addsuffix -targets.make, $(LOCALSTEPMAKE_TEMPLATES)))
250 include $(addprefix $(stepdir)/,$(addsuffix -targets.make, $(STEPMAKE_TEMPLATES)))
251 @end example
252
253 which expand as follows:
254
255 @example
256 include ./make/generic-rules.make ./make/lilypond-rules.make
257 include
258   /home/phil/lilypond-git/stepmake/stepmake/generic-rules.make
259   /home/phil/lilypond-git/stepmake/stepmake/toplevel-rules.make
260   /home/phil/lilypond-git/stepmake/stepmake/po-rules.make
261   /home/phil/lilypond-git/stepmake/stepmake/install-rules.make
262 include ./make/generic-targets.make ./make/lilypond-targets.make
263 include
264   /home/phil/lilypond-git/stepmake/stepmake/generic-targets.make
265   /home/phil/lilypond-git/stepmake/stepmake/toplevel-targets.make
266   /home/phil/lilypond-git/stepmake/stepmake/po-targets.make
267   /home/phil/lilypond-git/stepmake/stepmake/install-targets.make
268 @end example
269
270 @file{lilypond-rules.make} is @code{#empty}
271 @file{generic-rules.make} does seem to have 2 rules in it.  They
272 are:
273
274 @example
275 $(outdir)/%.ly: %.lym4
276         $(M4) $< | sed "s/\`/,/g" > $@
277
278 $(outdir)/%: %.in
279         rm -f $@
280         cat $< | sed $(sed-atfiles) | sed $(sed-atvariables) > $@
281 @end example
282
283 I believe the first rule is for *.ly files, and has a prerequisite
284 that *.lym4 files must be built first.  The recipe is @code{m4  |
285 sed "s/\`/,/g" >}.  Perhaps someone with more Unix/make knowledge
286 can comment on exactly what the rules mean/do.
287
288 @file{toplevel-rules.make} is @code{#empty}
289 @file{po-rules.make} is @code{#empty}
290 @file{install-rules.make} is @code{#empty}
291 @file{generic-targets.make} contains 2 lines of comments.
292 @file{lilypond-targets.make} contains only:
293
294 @example
295 ## TODO: fail dist or web if no \version present.
296 check-version:
297         grep -L version $(LY_FILES)
298 @end example
299
300 @file{stepmake/generic-targets.make} contains lots of rules - too
301 many to list here - it seems to be the main file for rules. (FWIW
302 I haven't actually found a rule for website: anywhere, although
303 it clearly exists.  I have also found that you can display a rule
304 in the terminal by typing, say @code{make -n website}.  This is
305 probably common knowledge.
306
307 @file{stepmake/toplevel-targets.make} adds a load of other (and
308 occasionally the same) rules to the gernric-targets.
309
310 @file{stepmake/po-targets.make} is rules for po* makes.
311
312 @file{stepmake/install-targets.make} has rules for local-install*.
313
314 And that's the end of stepmake.make.  Back to
315 @file{GNUmakefile.in}.  More some other time.
316
317 Another alterative approach to understanding the website build
318 would be to redirect @code{make -n website} and @code{make website}
319 to a text file and work through a) what it does and b) where the
320 errors are occurring.
321
322 GP: wow, all the above is much more complicated than I've ever
323 looked at stuff -- I tend to do a "back first" approach (where I
324 begin from the command-line that I want to modify, figure out
325 where it's generated, and then figure out how to change the
326 generated command-line), rather than a "front first" (where you
327 begin from the "make" command).
328
329
330 @node Doc build
331 @section Doc build
332
333 @menu
334 * Building a bibliography::
335 @end menu
336
337 @node Building a bibliography
338 @subsection Building a bibliography
339
340 Bibliography files contain a list of citations, like this:
341
342 @example
343 @@Book@{vinci,
344   author = @{Vinci, Albert C.@},
345   title = @{Fundamentals of Traditional Music Notation@},
346   publisher = @{Kent State University Press@},
347   year = @{1989@}
348 @}
349 @end example
350
351 There are a variety of types of citation (e.g. Book (as above),
352 article, publication).  Each cited publication has a list of
353 entries that can be used to identify the publication.
354 Bibliograpies are normally stored as files with a .bib
355 extension.  One part of the doc-build process is transforming the
356 bibliography information into @code{texinfo} files.  The commands
357 to do this are in the @file{GNUmakefile} in the
358 @file{Documentation} directory.
359
360 A typical line of the makefile to translate a single bibliography
361 is:
362
363 @example
364 $(outdir)/colorado.itexi:
365         BSTINPUTS=$(src-dir)/essay $(buildscript-dir)/bib2texi \
366                 -s $(top-src-dir)/Documentation/lily-bib \
367                 -o $(outdir)/colorado.itexi \
368                 $(src-dir)/essay/colorado.bib
369 @end example
370
371 Line by line:
372
373 @example
374 $(outdir)/colorado.itexi:
375 @end example
376
377 We're making the file @file{colorado.itexi} and so this is the
378 make instruction.
379
380 @example
381         BSTINPUTS=$(src-dir)/essay $(buildscript-dir)/bib2texi \
382 @end example
383
384 It's in the @file{essay} directory and we want to run the
385 bib2texi.py script against it.
386
387 @example
388                 -s $(top-src-dir)/Documentation/lily-bib \
389 @end example
390
391 The style template is @file{lily-bib.bst} and is found in the
392 @file{Documentation} directory.
393
394 @example
395                 -o $(outdir)/colorado.itexi \
396 @end example
397
398 The output file in @file{colorado.itexi}.
399
400 @example
401                 $(src-dir)/essay/colorado.bib
402 @end example
403
404 The input file is @file{colorado.bib} in the @file{essay}
405 directory.
406
407 The @code{bib2texi} Python script used to be used with a variety
408 of options, but now is always called using the same options, as
409 above.  Its job is to create the file containing the options for
410 @code{bibtex} (the program that actually does the translation),
411 run bibtex, and then clean up some temporary files.  Its main
412 "value add" is the creation of the options file, using this code:
413
414 @example
415 open (tmpfile + '.aux', 'w').write (r'''
416 \relax
417 \citation@{*@}
418 \bibstyle@{%(style)s@}
419 \bibdata@{%(files)s@}''' % vars ())
420 @end example
421
422 The key items are the style file (now always lily-bib for us) and
423 the input file.
424
425 The style file is written in its own specialised language,
426 described to some extent at
427
428 @example
429 @uref{http://amath.colorado.edu/documentation/LaTeX/reference/faq/bibtex.pdf}
430 @end example
431
432 The file @file{lily-bib.bst} also has fairly extensive commenting.
433
434 @node Website build
435 @section Website build
436
437 Start here: @file{make/website.make}
438
439 The overall build system begins with @ref{How stepmake works}.
440
441 However, we do believe that note that *none* of the variables that
442 are loaded (from depth to version numbers to whatever) are used in
443 @file{website.make}.  Instead, @file{website.make} sets up its own
444 variables at the top of the file.  If you're wondering if there's
445 some smart reason for this, then the answer is "no".  It's because
446 I didn't know/trust the original variables when I was writing that
447 file.
448
449
450 Website build includes @ref{Building a bibliography}.
451
452
453 @subsubheading website.make variables
454
455 The file begins by setting up some variables.  These
456 may/might/probably mirror existing variables, but lacking any docs
457 about those variables, I thought it would be simpler to keep
458 everything in the same file.
459
460 Note that for security reasons, we @strong{don't} call scripts in
461 the git dir when building on the web server.  See @ref{Uploading
462 and security}.  So we definitely want to keep those definitions
463 for the WEBSITE_ONLY_BUILD.
464
465 After some split WEBSITE_ONLY_BUILD vs. normal build definitions,
466 there's another bunch of lines setting up generic variables.
467
468 @subsubheading website.make building parts
469
470 Parts of @file{website.make}:
471
472 @itemize
473
474 @item
475 @code{website-version}:
476 this calls python scripts to define teinxfo macros.
477
478 @itemize
479 @item
480 @example
481 scripts/build/create-version-itexi.py
482 @end example
483
484 This writes a @@version, @@versionStable, and @@versionDevel based
485 on the top-level VERSIONS file, to
486 @code{out-website/version.itexi}
487
488 @item
489 @example
490 scripts/build/create-weblinks-itexi.py
491 @end example
492
493 This creates a ton of macros in @code{out-website/weblinks.itexi}.
494 Stuff like @@downloadStableLinuxNormal, @@downloadStableWidows,
495 @code{@@stableDocsNotationPdf@{@}}, @@downloadDevelSourch-zh.
496
497 It's quite monstrous because it deals with combinations of
498 stable/devel, source/docs, lang/lang/lang*10, etc.
499
500 @end itemize
501
502
503 @item
504 @code{website-xrefs:}
505 creates files used for complicated "out-of-build" references to
506 @code{out-website/*.xref-map}
507
508 If you just write @@ref@{@}, then all's groovy and we wouldn't
509 need this.  But if you write @@rlearning@{@}, then our custom
510 texi2html init file needs to know about our custom xref file
511 format, which tells our custom texi2html init file how to create
512 the link.
513
514 GP: we should have a separate @@node to discuss xrefs.  Also, take a
515 quick look at a generated xref file -- it's basically just a list
516 of @@node's [sic teenager pluralization rule] from the file.
517
518 @item
519 @code{website-bib:}
520 generates the bibliography texinfo files from the .bib files.
521
522 @item
523 @code{website-texinfo:}
524 this is the main part; it calles texi2html to generate the actual
525 html.  It also has a ton of options to texi2html to pass info to
526 our custom init file.
527
528 We have somewhere between 2-4 different ways "to pass info to our
529 custom init file".  This is highly Not Good (tm), but that's how
530 things work at the moment.
531
532 After texi2html, it does some black magick to deal with
533 untranslated nodes in the translations.  Despite writing that
534 part, I can't remember how it works.  But in theory, you could
535 figure it out by copy&pasting each part of the command (by "part",
536 I mean "stuff before each | pipe"), substituting the variables,
537 then looking at the text that's output.  For example,
538
539 @example
540   ls $(OUT)/$$l/*.html
541 @end example
542
543 is going to print a list of all html files, in all languages, in
544 the build directory.  Then more stuff happens to each of those
545 files (that's what xargs does).
546
547 @item
548 @code{website-css:}
549 just copies files to the build dir.
550
551 @item
552 @code{website-pictures, website-examples:}
553 more file copies, with an if statement to handle if you don't have
554 any generated pictures/examples.
555
556 @item
557 @code{web-post:}
558 runs:
559
560 @example
561 scripts/build/website_post.py
562 @end example
563
564 which, it adds the "this page is translated in klingon" to the
565 bottom of html pages, and adds the google analytics javascript.
566 It also has hard-coded lilypond version numbers, which is Bad
567 (tm).
568
569 @item
570 @code{website:}
571 this is the "master" rule.  It calls the bits and pieces in order,
572 then copies some extra files around.
573
574 @end itemize
575
576
577 @node Building an Ubuntu distro
578 @section Building an Ubuntu distro
579
580 @enumerate
581 @item
582 Install ubuntu, reboot
583 @item
584 Run all updates, reboot if asked
585 @item
586 Enable src repos, refresh package lists
587 @item
588 Install LilyPond build deps:
589 @example
590   sudo apt-get build-dep lilypond
591 @end example
592 @item
593 Install git and autoconf:
594 @example
595   sudo apt-get install git-core gitk autoconf
596 @end example
597
598 @item
599 TEST TO SEE WHETHER EVERYTHING WORKS NOW:
600 @enumerate
601 @item
602 Use lily-git.tcl to grab source files
603 @item
604 Go to source dir and do "./autogen.sh" ; make ; make doc
605 @item
606 If all compiles, move on to iso creation...
607
608 @end enumerate
609
610 @item
611 Download & install "remastersys":
612 @example
613   http://sourceforge.net/projects/remastersys/
614 @end example
615 @item
616 Copy lily-git.tcl script file into /etc/skel/
617 @item
618 Modify /etc/remastersys.conf as desired (change .iso name, default
619 live session username, etc)
620 @item
621 Remove non-essential desktop software as desired
622 @item
623 Create iso:  sudo remastersys dist
624 @item
625 New iso is in /home/remastersys/remastersys/
626 @item
627 Test iso by installing in VM and repeating steps above for
628 getting source files and building lp and docs
629 @end enumerate
630
631
632