1 \input texinfo @c -*-texinfo-*-
2 @setfilename internals.info
3 @settitle LilyPond internals
5 @node Top, LilyPond internals, (dir), (dir)
10 * LilyPond internals::
14 * Items and spanners::
21 @node LilyPond internals, , Top, Top
25 * Request_engraver:: Request_engraver
26 * Items and spanners:: Items and spanners
27 * Dependencies:: Dependencies
31 @chapter LilyPond internals
34 This documents some aspects of the internals of GNU LilyPond. Some of
35 this stuff comes from e-mail I wrote, some from e-mail others wrote,
36 some are large comments taken away from the headers. This page may be
37 a little incoherent. Unfortunately, it is also quite outdated. A
38 more thorough and understandable document is in the works.
40 You should use @code{doc++} to take a peek at the sources.
42 @node Overview, mudela, Top, Top
45 GNU LilyPond is a "multi-pass" system. The different passes have been
46 created so that they do not depend on each other. In a later stage
47 some parts may be moved into libraries, or seperate programs, or they
48 might be integrated in larger systems.
54 No difficult algorithms. The .ly file is read, and converted to a list
55 of @code{Scores}, which each contain @code{Music} and paper/midi-definitions.
57 @item Interpreting music
59 The music is walked through in time-order. The iterators which do the
60 walking report Music to Translators which use this information to
61 create elements, either MIDI or "visual" elements. The translators
62 form a hierarchy; the ones for paper output are Engravers, for MIDI
65 The translators swallow Music (mostly atomic gobs called Requests),
66 create elements, broadcast them to other translators on higher or same
67 level in the hierarchy:
69 The stem of a voice A is broadcast to the staff which contains A, but
70 not to the stems, beams and noteheads of a different voice (say B) or
71 a different staff. The stem and noteheads of A are coupled, because
72 the the Note_heads_engraver broadcasts its heads, and the Stem_engraver catches
75 The engraver which agrees to handle a request decides whether to to
76 honor the request, ignore it, or merge it with other requests. Merging
77 of requests is preferably done with other requests done by members of
78 the same voicegroups (beams, brackets, stems). In this way you can put
79 the voices of 2 instruments in a conductor's score so they make chords
80 (the Beam requests of both instruments will be merged).
84 Breakable stuff (eg. clefs and bars) are copied into pre and
89 Some dependencies are resolved, such as the direction of stems, beams,
90 and "horizontal" placement issues (the order of clefs, keys etc,
91 placement of chords in multi-voice music),
93 @item Break calculation:
95 The lines and horizontal positions of the columns are determined.
99 Through some magical interactions with Line_of_score and Super_elem
100 (check out the source) the "lines" are produced.
102 All other spanners can figure across which lines they are spread. If
103 applicable, they break themselves into pieces. After this, each piece
104 (or, if there are no pieces, the original spanner itself) throws out
105 any dependencies which are in the wrong line.
109 Some items and all spanners need computation after the Paper_column
110 positions are determined. Examples: slurs, vertical positions of
117 @node mudela, Request_engraver, Overview, Top
120 Most information is stored in the form of a request. In music
121 typesetting, the user might want to cram a lot more symbols on the
122 paper than actually fits. To reflect this idea (the user asks more
123 than we can do), the container for this data is called Request.
125 In a lot of other formats this would be called an 'Event'
128 @item @code{Barcheck_req}
129 Checks during music processing if start of this voice element
130 coincides with the start of a measure. Handy to check if you left out
132 @item @code{Note_req}
133 LilyPond has to decide if the ball should be hanging left or
134 right. This influences the horizontal dimensions of a column, and this
135 is why request processing should be done before horizontal spacing.
136 Other voices' frivolities may cause the need for accidentals, so this
137 is also for the to decide. The engraver can decide on positioning based on
138 ottava commands and the appropriate clef.
139 @item @code{Rest_req}
141 @item @code{Span_req}
142 This type of request typically results in the creation of a @code{Spanner}
143 @item @code{Beam_req}
145 Engraver has to combine this request with the stem_request, since the
146 number of flags that a stem wants to carry will determine the
149 Each dynamic is bound to one note (a crescendo spanning multiple
150 notes is thought to be made of two "dynamics": a start and a stop).
151 Dynamic changes can occur in a smaller time than the length of its
152 note, therefore fore each @code{Dynamic} request carries a time, measured
153 from the start of its note.
156 @node Request_engraver, Items and spanners, mudela, Top
157 @section Request_engraver
159 In the previous section the idea of Request has been explained, but
160 this only solves one half of the problem. The other half is deciding
161 which requests should be honored, which should merged with other
162 requests, and which should be ignored. Consider this input
166 \type Staff < % chord
167 @{ \meter 2/4; [c8 c8] @}
168 @{\meter 2/4; [e8 e8] @}
173 Both the cs and es are part of a staff (they are in the same
174 Voice_group), so they should share meters, but the two [ ] pairs
177 The judge in this "allocation" problem a set of brokers: the requests
178 are transmitted to so-called engravers which respond if they want to
179 accept a request eg, the @code{Notehead_engraver} will accept
180 @code{Note_req}s, and turn down @code{Slur_req}s. If the Music_iterator
181 cannot find a engraver that wants the request, it is junked (with a
184 After all requests have been either assigned, or junked, the Engraver
185 will process the requests (which usually means creating an @code{Item}
186 or @code{Spanner}). If a @code{Request_engraver} creates something, it
187 tells the enclosing context. If all items/spanners have been created,
188 then each Engraver is notified of any created Score_element, via a
191 @unnumberedsubsec example:
203 Note_request (duration 1/4)
204 Stem_request (duration 1/4)
208 Note_request will be taken by a @code{Notehead_engraver}, stem_request
209 will be taken by a @code{Stem_beam_engraver}. @code{Notehead_engraver}
210 creates a @code{Notehead}, @code{Stem_beam_engraver} creates a
211 @code{Stem}. Both announce this to the Staff_engraver. Staff_engraver
212 will tell @code{Stem_beam_engraver} about the @code{Notehead}, which
213 will add the @code{Notehead} to the @code{Stem} it just created.
215 To decide on merging, several engravers have been grouped. Please
216 check @file{init/engraver.ly}.
218 @node Items and spanners, Dependencies, Request_engraver, Top
219 @section Items and spanners
221 The symbols that are printed, are generated by items and spanners
222 (staff-elements). An item has one horizontal position, whereas a
223 spanner spans several columns.
225 @node Dependencies, Breaking, Items and spanners, Top
226 @section Dependencies
228 In music symbols depend on each other: the stems of a beam should
229 point in the same direction as the beam itself, so the stems of a beam
230 depend on the beam. In the same way do scripts depend on the direction
231 of the stem. To reflect this, LilyPond has the notion of dependency.
232 It works in the same fashion that @code{make} uses to build programs:
233 before a stem is calculated, its dependencies (the beam) should be
234 calculated. Before a slur is calculated, its dependencies (stems,
235 noteheads) should be calculated.
237 @node Breaking, Making patches, Dependencies, Top
240 So what is this PREBREAK and POSTBREAK stuff?
242 Let's take text as an example. In German some compound
243 words change their spelling if they are broken: "backen" becomes
244 "bak-ken". TeX has a mechanism to deal with this, you would define
245 the spelling of "backen" in TeX in this way
247 \discretionary@{bak-@}@{ken@}@{backen@}
249 These 3 arguments are called "prebreak", "postbreak" and "nobreak"
252 The same problem exists when typesetting music. If a line of music is
253 broken, the next line usually gets a clef. So in TeX terms, the clef
254 is a postbreak. The same thing happens with meter signs: Normally the
255 meter follows the bar. If a line is broken at that bar, the bar along
256 with the meter stays on the "last" line, but the next line also gets a
257 meter sign after the clef. Using the previous notation,
259 \discretionary@{bar meter@}@{clef meter@}@{ bar meter @}
261 In GNU Lilypond, we have the same concepts (and the same
262 terminology). Each (nonrhythmic) symbol is typeset in a nonrhythmic column
263 At a breakpoint, multiple symbols are printed; symbols to be printed
264 if the line is not broken, symbols to appear on the previous line, and
265 on the next line if it is broken.
267 @node Coding standards, , Top, Top
269 @chapter CodingStyle - standards while programming for GNU
272 We use these standards while doing programming for GNU LilyPond. If
273 you do some hacking, we appreciate it if you would follow this rules,
274 but if you don't, we still like you.
276 Functions and methods do not return errorcodes.
280 A program should be light and agile, its subroutines
281 connected like a string of pearls. The spirit and intent of
282 the program should be retained throughout. There should be
283 neither too little nor too much, neither needless loops nor
284 useless variables, neither lack of structure nor overwhelming
287 A program should follow the 'Law of Least
288 Astonishment'. What is this law? It is simply that the
289 program should always respond to the user in the way that
290 astonishes him least.
292 A program, no matter how complex, should act as a
293 single unit. The program should be directed by the logic
294 within rather than by outward appearances.
296 If the program fails in these requirements, it will be
297 in a state of disorder and confusion. The only way to correct
298 this is to rewrite the program.
300 -- Geoffrey James, "The Tao of Programming"
304 @unnumberedsubsec Languages
306 C++ and Python are preferred. Perl is not. Python code should use an
307 indent of 8, using TAB characters.
309 @unnumberedsubsec Filenames
311 Definitions of classes that are only accessed via pointers
312 (*) or references (&) shall not be included as include files.
319 ".cc" Implementation files
320 ".icc" Inline definition files
321 ".tcc" non inline Template defs
329 (setq auto-mode-alist
330 (append '(("\\.make$" . makefile-mode)
331 ("\\.cc$" . c++-mode)
332 ("\\.icc$" . c++-mode)
333 ("\\.tcc$" . c++-mode)
334 ("\\.hh$" . c++-mode)
335 ("\\.pod$" . text-mode)
342 The class Class_name_abbreviation is coded in @file{class-name-abbr.*}
344 @unnumberedsubsec Indentation
346 Standard GNU coding style is used. In emacs:
350 (add-hook 'c++-mode-hook
351 '(lambda() (c-set-style "gnu")
357 If you like using font-lock, you can also add this to your @file{.emacs}:
361 (setq font-lock-maximum-decoration t)
362 (setq c++-font-lock-keywords-3
364 c++-font-lock-keywords-3
365 '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
366 ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
371 @unnumberedsubsec Classes and Types
379 @unnumberedsubsec Members
384 Type Class::member_type_
385 Type Class::member_type ()
389 the @code{type} is a Hungarian notation postfix for @code{Type}. See below
391 @unnumberedsubsec Macros
393 Macros should be written completely in uppercase
395 The code should not be compilable if proper macro declarations are not
398 Don't laugh. It took us a whole evening/night to figure out one of
399 these bugs, because we had a macro that looked like
400 @code{DECLARE_VIRTUAL_FUNCTIONS ()}.
402 @unnumberedsubsec Broken code
404 Broken code (hardwired dependencies, hardwired constants, slow
405 algorithms and obvious limitations) should be marked as such: either
406 with a verbose TODO, or with a short "ugh" comment.
408 @unnumberedsubsec Comments
410 The source is commented in the DOC++ style. Check out doc++ at
411 @uref{http://www.zib.de/Visual/software/doc++/index.html}
416 C style comments for multiline comments.
417 They come before the thing to document.
423 Long class documentation.
426 TODO Fix boring_member ()
437 short memo. long doco of member ()
438 @@param description of arguments
441 Rettype member (Argtype);
445 data_member_ = 121; // ugh
452 Unfortunately most of the code isn't really documented that good.
454 @unnumberedsubsec Members (2)
460 ///check that *this satisfies its invariants, abort if not.
463 /// print *this (and substructures) to debugging log
467 protected member. Usually invoked by non-virtual XXXX ()
471 /**add some data to *this.
472 Presence of these methods usually imply that it is not feasible to this
477 /// replace some data of *this
482 @unnumberedsubsec Constructor
484 Every class should have a default constructor.
486 Don't use non-default constructors if this can be avoided:
494 is less readable than
507 Foo f(Foo_convert::int_to_foo (1))
511 @unnumberedsec Hungarian notation naming convention
513 Proposed is a naming convention derived from the so-called
514 @emph{Hungarian Notation}. Macros, @code{enum}s and @code{const}s are all
515 uppercase, with the parts of the names separated by underscores.
517 @unnumberedsubsec Types
521 unsigned char. (The postfix _by is ambiguous)
535 Zero terminated c string
540 @unnumberedsubsec User defined types
548 Slur* slur_p = new Slur;
552 @unnumberedsubsec Modifiers
554 The following types modify the meaning of the prefix.
555 These are preceded by the prefixes:
563 const. Note that the proper order is @code{Type const}
564 i.s.o. @code{const Type}
566 A const pointer. This would be equivalent to @code{_c_l}, but since any
567 "const" pointer has to be a link (you can't delete a const pointer),
570 temporary pointer to object (link)
572 pointer to newed object
577 @unnumberedsubsec Adjective
579 Adjectives such as global and static should be spelled out in full.
580 They come before the noun that they refer to, just as in normal english.
584 foo_global_i: a global variable of type int commonly called "foo".
588 static class members do not need the static_ prefix in the name (the
589 Class::var notation usually makes it clear that it is static)
593 Variable loop: an integer
595 Temporary variable: an unsigned integer
597 Variable test: a character
598 @item @code{first_name_str}
599 Variable first_name: a String class object
600 @item @code{last_name_ch_a}
601 Variable last_name: a @code{char} array
603 Variable foo: an @code{Int*} that you must delete
605 Variable bar: an @code{Int*} that you must not delete
608 Generally default arguments are taboo, except for nil pointers.
610 The naming convention can be quite conveniently memorised, by
611 expressing the type in english, and abbreviating it
615 static Array<int*> foo
619 @code{foo} can be described as "the static int-pointer user-array", so you get
628 @unnumberedsec Miscellaneous
631 For some tasks, some scripts are supplied, notably creating patches, a
632 mirror of the website, generating the header to put over cc and hh
633 files, doing a release.
637 @node Making patches, , Breaking, Top
643 PATCHES - track and distribute your code changes
645 This page documents how to distribute your changes to GNU lilypond
647 We would like to have unified context diffs with full pathnames. A
648 script automating supplied with Lily.
650 Distributing a change normally goes like this:
653 @item make your fix/add your code
654 @item Add changes to NEWS, and add yourself to Documentation/topdocs/AUTHORS.yo
655 @item generate a patch,
656 @item e-mail your patch to one of the mailing lists
657 gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org
660 Please do not send entire files, even if the patch is bigger than the
661 original. A patch makes it clear what is changed, and it won't
662 overwrite previous not yet released changes.
664 @unnumberedsec Generating a patch
667 In @file{VERSION}, set MY_PATCH_LEVEL:
677 In @file{CHANGES}, enter a summary of changes:
684 Then, from the top of Lily's source tree, type
693 which rolls the tarball @file{../releases/lilypond-0.1.73.tar.gz}
694 and leaves your patch as @file{./lilypond-0.1.73.jcn1.diff}.
695 @footnote{'Make diff' generates a patch between two tarballs. For
696 more info type 'make diff help=='.} We assume that there is a tarball
697 @file{lilypond-0.1.73.tar.gz} in the directory @file{../releases}.
699 If you didn't configure Lily using --srcdir, you can do:
705 tar-ball: ../patches/lilypond-0.1.73.jcn1.gz
706 patch: ../patches/lilypond-0.1.73.jcn1.gz
709 @unnumberedsec Prerequisites
712 For creating a patch you need
715 @item All items mentioned in @file{INSTALL}. You're not going to send a patch
716 that you haven't even built, right?
721 diff -urN lilypond-0.1.73 lilypond-0.1.73.jcn1 > lilypond-0.1.73.jcn1
724 but there are handy python scripts available. If you're doing development,
725 you'll need Python for other LilyPond scripts anyway.
727 @item The Lily directory structure, which looks like:
731 doos/ # gnu/windows32 build and binary releases
732 harmonia -> harmonia-x.y.z
734 lilypond -> lilypond-x.y.z # symlink to development directory
735 lilypond-x.y.z/ # current development
736 patches/ # patches between different releases
737 RedHat/BUILD # RedHat build and binary releases
740 releases/ # .tar.gz releases
741 test/ # tarballs and diffs from current version
746 with prefix @file{$HOME/usr/src}
747 and (for building rpms only) in @file{$HOME/.rpmrc}:
750 topdir: /home/fred/usr/src/RedHat
756 @unnumberedsec Applying patches
759 If you're following LilyPond development regularly, you probably want to
760 download just the patch for each subsequent release.
761 After downloading the patch (into the patches directory, of course), simply
766 gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
770 and don't forget to make automatically generated files:
774 autoconf footnote(patches don't include automatically generated files,
775 i.e. file(configure) and files generated by file(configure).)
781 @unnumberedsec Synchronise
784 If you're not very quick with sending your patch, there's a good
785 chance that an new release of LilyPond comes available. In such a
786 case, the maintainer will probably ask you to make a new patch against
787 the latest release. Your best bet is to download the latest release,
788 and apply your patch against this new source tree:
793 gzip -dc ../patches/lilypond-0.1.73.jcn1.diff.gz | patch -p1 -E
799 Then, make a patch as shown above.
801 @unnumberedsec See also
804 @file{stepmake/INSTALL.txt}
806 @unnumberedsec maintainer
809 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}
811 Just keep on sending those patches!