1 @c -*- coding: us-ascii; mode: texinfo; -*-
3 @chapter Programming work
6 * Overview of LilyPond architecture::
7 * LilyPond programming languages::
8 * Programming without compiling::
11 * Debugging LilyPond::
14 @node Overview of LilyPond architecture::
15 @section Overview of LilyPond architecture::
17 TODO -- put in brief description along with link to Erik Sandberg's
22 Parsing converts input file to scheme music expressions.
24 Iterating converts scheme music expressions into a context tree.
26 Translation converts the context tree into graphical and/or midi output.
28 Music expressions provide relative timing for music events.
30 Contexts provide an evaluation environment within which an engraver converts
31 the music event to output.
33 Question: What is an engraver? I think an engraver handles both iteration
34 and translation, but I need to check on that.
36 Sandberg says that "translator" and "engraver" are synonymous for his thesis;
37 the distinction between them is not relevant for that document. What is the
40 @node LilyPond programming languages
41 @section LilyPond programming languages
43 Programming in LilyPond is done in a variety of programming languages. Each
44 language is used for a specific purpose or purposes. This section describes
45 the languages used and provides links to reference manuals and tutorials for
46 the relevant language.
50 The core functionality of LilyPond is implemented in C++.
52 C++ is so ubiquitous that it is difficult to identify either a reference
53 manual or a tutorial. Programmers unfamiliar with C++ will need to spend some
54 time to learn the language before attempting to modify the C++ code.
56 The C++ code calls Scheme/GUILE through the GUILE interface, which is
58 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE
63 The LilyPond parser is implemented in Bison, a GNU parser generator. The
64 Bison homepage is found at @uref{http://www.gnu.org/software/bison/,
65 gnu.org}. The manual (which includes both a reference and tutorial) is
66 @uref{http://www.gnu.org/software/bison/manual/index.html, available} in a
71 GNU Make is used to control the compiling process and to build the
72 documentation and the website. GNU Make documentation is available at
73 @uref{http://www.gnu.org/software/make/manual/, the GNU website}.
75 @subsection GUILE or Scheme
77 GUILE is the dialect of Scheme that is used as LilyPond's extension language. Many extensions to LilyPond are written entirely in GUILE. The
78 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
79 GUILE Reference Manual} is available online.
81 @uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and
82 Interpretation of Computer Programs}, a popular textbook used to teach
83 programming in Scheme is available in its entirety online.
87 MetaFont is used to create the music fonts used by LilyPond. A MetaFont
88 tutorial is available at @uref{http://metafont.tutorial.free.fr/, the
89 METAFONT tutorial page}.
91 @subsection PostScript
93 PostScript is used to generate graphical output. A brief PostScript tutorial
94 is @uref{http://local.wasp.uwa.edu.au/~pbourke/dataformats/postscript/,
95 available online}. The
96 @uref{http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf, PostScript Lanugage
97 Reference} is available online in PDF format.
101 Python is used for XML2ly and is used for buillding the documentation and the
104 Python documentation is available at @uref{http://www.python.org/doc/,
107 @node Programming without compiling
108 @section Programming without compiling
110 Much of the development work in LilyPond takes place by changing *.ly or
111 *.scm files. These changes can be made without compiling LilyPond. Such
112 changes are described in this section.
115 @subsection Modifying distribution files
117 Much of LilyPond is written in Scheme or LilyPond input files. These
118 files are interpreted when the program is run, rather than being compiled
119 when the program is built, and are present in all LilyPond distributions.
120 You will find .ly files in the ly/ directory and the Scheme files in the
121 scm/ directory. Both Scheme files and .ly files can be modified and
122 saved with any text editor. It's probably wise to make a backup copy of
123 your files before you modify them, although you can reinstall if the
124 files become corrupted.
126 Once you've modified the files, you can test the changes just by running
127 LilyPond on some input file. It's a good idea to create a file that
128 demonstrates the feature you're trying to add. This file will eventually
129 become a regression test and will be part of the LilyPond distribution.
131 @subsection Desired file formatting
133 Files that are part of the LilyPond distribution have Unix-style line
134 endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR). Make
135 sure you use the necessary tools to ensure that Unix-style line endings are
136 preserved in the patches you create.
138 Tab characters should not be included in files for distribution. All
139 indentation should be done with spaces. Most editors have settings to
140 allow the setting of tab stops and ensuring that no tab characters are
141 included in the file.
143 Scheme files and LilyPond files should be written according to standard
144 style guidelines. Scheme file guidelines can be found at
145 @uref{http://community.schemewiki.org/?scheme-style}. Following these
146 guidelines will make your code easier to read. Both you and others that
147 work on your code will be glad you followed these guidelines.
149 For LilyPond files, you should follow the guidelines for LilyPond snippets
150 in the documentation. You can find these guidelines at
151 @ref{Texinfo introduction and usage policy}.
153 @node Finding functions
154 @section Finding functions
156 When making changes or fixing bugs in LilyPond, one of the initial
157 challenges is finding out where in the code tree the functions to
158 be modified live. With nearly 3000 files in the source tree,
159 trial-and-error searching is generally ineffective. This section
160 describes a process for finding interesting code.
162 @subsection Using the ROADMAP
164 The file ROADMAP is located in the main directory of the lilypond source.
165 ROADMAP lists all of the directories in the LilPond source tree, along
166 with a brief description of the kind of files found in each directory.
167 This can be a very helpful tool for deciding which directories to search
168 when looking for a function.
171 @subsection Using grep to search
173 Having identified a likely subdirectory to search, the grep utility can
174 be used to search for a function name. The format of the grep command is
177 grep -i functionName subdirectory/*
180 This command will search all the contents of the directory subdirectory/
181 and display every line in any of the files that contains
182 functionName. The @code{-i} option makes @command{grep} ignore
183 case -- this can be very useful if you are not yet familiar with
184 our capitalization conventions.
186 The most likely directories to grep for function names are scm/ for
187 scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
191 @subsection Using git grep to search
193 If you have used git to obtain the source, you have access to a
194 powerful tool to search for functions. The command:
197 git grep functionName
200 will search through all of the files that are present in the git
201 repository looking for functionName. It also presents the results
202 of the search using @code{less}, so the results are displayed one page
205 @subsection Searching on the git repository at Savannah
207 You can also use the equivalent of git grep on the Savannah server.
212 Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
215 In the pulldown box that says commit, select grep.
218 Type functionName in the search box, and hit enter/return
222 This will initiate a search of the remote git repository.
227 @c email to wl@gnu.org when I get here.
232 @subsection Handling errors
234 As a general rule, you should always try to continue computations,
235 even if there is some kind of error. When the program stops, it
236 is often very hard for a user to pinpoint what part of the input
237 causes an error. Finding the culprit is much easier if there is
238 some viewable output.
240 So functions and methods do not return errorcodes, they never
241 crash, but report a programming_error and try to carry on.
243 @subsection Languages
245 C++ and Python are preferred. Python code should use PEP 8.
247 @subsection Filenames
249 Definitions of classes that are only accessed via pointers (*) or
250 references (&) shall not be included as include files.
256 ".cc" Implementation files
257 ".icc" Inline definition files
258 ".tcc" non inline Template defs
262 (setq auto-mode-alist
263 (append '(("\\.make$" . makefile-mode)
264 ("\\.cc$" . c++-mode)
265 ("\\.icc$" . c++-mode)
266 ("\\.tcc$" . c++-mode)
267 ("\\.hh$" . c++-mode)
268 ("\\.pod$" . text-mode)
273 The class Class_name is coded in @q{class-name.*}
275 @subsection Indentation
277 Standard GNU coding style is used. In emacs:
280 (add-hook 'c++-mode-hook
281 '(lambda() (c-set-style "gnu")
285 If you like using font-lock, you can also add this to your
289 (setq font-lock-maximum-decoration t)
290 (setq c++-font-lock-keywords-3
292 c++-font-lock-keywords-3
293 '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
298 @subsection Classes and Types
307 Member variable names end with an underscore:
316 Macro names should be written in uppercase completely.
319 @subsection Broken code
321 Do not write broken code. This includes hardwired dependencies,
322 hardwired constants, slow algorithms and obvious limitations. If
323 you can not avoid it, mark the place clearly, and add a comment
324 explaining shortcomings of the code.
326 We reject broken-in-advance on principle.
333 Messages need to follow Localization.
336 @subsection Localization
338 This document provides some guidelines for programmers write user
339 messages. To help translations, user messages must follow
340 uniform conventions. Follow these rules when coding for LilyPond.
341 Hopefully, this can be replaced by general GNU guidelines in the
342 future. Even better would be to have an English (en_BR, en_AM)
343 guide helping programmers writing consistent messages for all GNU
346 Non-preferred messages are marked with `+'. By convention,
347 ungrammatical examples are marked with `*'. However, such ungrammatical
348 examples may still be preferred.
353 Every message to the user should be localized (and thus be marked
354 for localization). This includes warning and error messages.
357 Don't localize/gettextify:
361 `programming_error ()'s
364 `programming_warning ()'s
370 output strings (PostScript, TeX, etc.)
375 Messages to be localised must be encapsulated in `_ (STRING)' or
376 `_f (FORMAT, ...)'. E.g.:
379 warning (_ ("need music in a score"));
380 error (_f ("cannot open file: `%s'", file_name));
383 In some rare cases you may need to call `gettext ()' by hand. This
384 happens when you pre-define (a list of) string constants for later
385 use. In that case, you'll probably also need to mark these string
386 constants for translation, using `_i (STRING)'. The `_i' macro is
387 a no-op, it only serves as a marker for `xgettext'.
390 char const* messages[] = @{
391 _i ("enable debugging output"),
392 _i ("ignore lilypond version"),
399 puts (gettext (messages i));
403 See also `flower/getopt-long.cc' and `lily/main.cc'.
406 Do not use leading or trailing whitespace in messages. If you need
407 whitespace to be printed, prepend or append it to the translated
411 message ("Calculating line breaks..." + " ");
415 Error or warning messages displayed with a file name and line
416 number never start with a capital, eg,
419 foo.ly: 12: not a duration: 3
422 Messages containing a final verb, or a gerund (`-ing'-form) always
423 start with a capital. Other (simpler) messages start with a
429 Not declaring: `foo'.
433 Avoid abbreviations or short forms, use `cannot' and `do not'
434 rather than `can't' or `don't'
435 To avoid having a number of different messages for the same
436 situation, we'll use quoting like this `"message: `%s'"' for all
437 strings. Numbers are not quoted:
440 _f ("cannot open file: `%s'", name_str)
441 _f ("cannot find character number: %d", i)
445 Think about translation issues. In a lot of cases, it is better to
446 translate a whole message. The english grammar mustn't be imposed
447 on the translator. So, instead of
450 stem at + moment.str () + does not fit in beam
456 _f ("stem at %s does not fit in beam", moment.str ())
460 Split up multi-sentence messages, whenever possible. Instead of
463 warning (_f ("out of tune! Can't find: `%s'", "Key_engraver"));
464 warning (_f ("cannot find font `%s', loading default", font_name));
470 warning (_ ("out of tune:"));
471 warning (_f ("cannot find: `%s', "Key_engraver"));
472 warning (_f ("cannot find font: `%s', font_name));
473 warning (_f ("Loading default font"));
477 If you must have multiple-sentence messages, use full punctuation.
478 Use two spaces after end of sentence punctuation. No punctuation
479 (esp. period) is used at the end of simple messages.
482 _f ("Non-matching braces in text `%s', adding braces", text)
483 _ ("Debug output disabled. Compiled with NPRINT.")
484 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
488 Do not modularise too much; words frequently cannot be translated
489 without context. It's probably safe to treat most occurences of
490 words like stem, beam, crescendo as separately translatable words.
493 When translating, it is preferable to put interesting information
494 at the end of the message, rather than embedded in the middle.
495 This especially applies to frequently used messages, even if this
496 would mean sacrificing a bit of eloquency. This holds for original
497 messages too, of course.
500 en: cannot open: `foo.ly'
501 + nl: kan `foo.ly' niet openen (1)
502 kan niet openen: `foo.ly'* (2)
503 niet te openen: `foo.ly'* (3)
507 The first nl message, although grammatically and stylistically
508 correct, is not friendly for parsing by humans (even if they speak
509 dutch). I guess we'd prefer something like (2) or (3).
512 Do not run make po/po-update with GNU gettext < 0.10.35
518 @node Debugging LilyPond
519 @section Debugging LilyPond
521 The most commonly used tool for debugging LilyPond is the GNU debugger
522 gdb. Use of gdb is described in this section.
524 @subsection Debugging overview
526 Using a debugger simplifies troubleshooting in at least two ways.
528 First, breakpoints can be set to pause execution at any desired point.
529 Then, when execution has paused, debugger commands can be issued to
530 explore the values of various variables or to execute functions.
532 Second, the debugger allows the display of a stack trace, which shows
533 the sequence in which functions are called and the arguments to the
534 various function calls.
537 @subsection Compiling with debugging information
539 In order to use a debugger with LilyPond, it is necessary to compile
540 LilyPond with debugging information. This is accomplished by ...
542 TODO -- get good description here, or perhaps add debugging compile
543 to AU1.1 as it comes to CG and just use a reference here.
545 TODO -- Test the following to make sure it is true.
547 If you want to be able to set breakpoints in Scheme functions, it is
548 necessary to compile guile with debugging information. This is done
551 TODO -- get compiling description for guile here.
553 @subsection Typical gdb usage
555 @subsection Typical .gdbinit files
557 The behavior of gdb can be readily customized through the use of
558 @var{.gdbinit} files. A @var{.gdbinit} file is a file named
559 @var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
560 that is placed in a user's home directory.
562 The @var{.gdbinit} file below is from Han-Wen. It sets breakpoints
563 for all errors and defines functions for displaying scheme objects
564 (ps), grobs (pgrob), and parsed music expressions (pmusic).
567 file lily/out/lilypond
570 b Grob::programming_error
573 print ly_display_scm($arg0)
576 print ly_display_scm($arg0->self_scm_)
577 print ly_display_scm($arg0->mutable_property_alist_)
578 print ly_display_scm($arg0->immutable_property_alist_)
579 print ly_display_scm($arg0->object_alist_)
582 print ly_display_scm($arg0->self_scm_)
583 print ly_display_scm($arg0->mutable_property_alist_)
584 print ly_display_scm($arg0->immutable_property_alist_)
588 @subsection Using Guile interactively with LilyPond
590 In order to experiment with Scheme programming in the LilyPond
591 environment, it is convenient to have a Guile interpreter that
592 has all the LilyPond modules loaded. This requires the following
595 First, define a Scheme symbol for the active module
599 #(module-define! (resolve-module '(guile-user))
600 'lilypond-module (current-module))
603 Second, place a Scheme function in the .ly file that gives an interactive Guile
610 When the .ly file is compiled, this causes the compilation to be interrupted
611 and an interactive guile prompt to appear. When the guile prompt appears,
612 the LilyPond active module must be set as the current guile module:
615 guile> (set-current-module lilypond-module)
618 Proper operation of these commands can be demonstrated by typing the name
619 of a LilyPond public scheme function to see if it's properly defined:
622 guile> fret-diagram-verbose-markup
623 #<procedure fret-diagram-verbose-markup (layout props marking-list)>
626 If the LilyPond module has not been correctly loaded, an error
627 message will be generated:
630 guile> fret-diagram-verbose-markup
631 ERROR: Unbound variable: fret-diagram-verbose-markup
632 ABORT: (unbound-variable)
635 Once the module is properly loaded, any valid LilyPond Scheme expression
636 can be entered at the interactive prompt.
638 After the investigation is complete, the interactive guile interpreter
645 The compilation of the .ly file will then continue.