1 @c -*- coding: us-ascii; mode: texinfo; -*-
3 @chapter Programming work
6 * LilyPond programming languages::
7 * Programming without compiling::
10 * Debugging LilyPond::
15 @node LilyPond programming languages
16 @section LilyPond programming languages
18 Programming in LilyPond is done in a variety of programming languages. Each
19 language is used for a specific purpose or purposes. This section describes
20 the languages used and provides links to reference manuals and tutorials for
21 the relevant language.
25 The core functionality of LilyPond is implemented in C++.
27 C++ is so ubiquitous that it is difficult to identify either a reference
28 manual or a tutorial. Programmers unfamiliar with C++ will need to spend some
29 time to learn the language before attempting to modify the C++ code.
31 The C++ code calls Scheme/GUILE through the GUILE interface, which is
33 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE
38 The LilyPond parser is implemented in Bison, a GNU parser generator. The
39 Bison homepage is found at @uref{http://www.gnu.org/software/bison/,
40 gnu.org}. The manual (which includes both a reference and tutorial) is
41 @uref{http://www.gnu.org/software/bison/manual/index.html, available} in a
46 GNU Make is used to control the compiling process and to build the
47 documentation and the website. GNU Make documentation is available at
48 @uref{http://www.gnu.org/software/make/manual/, the GNU website}.
50 @subsection GUILE or Scheme
52 GUILE is the dialect of Scheme that is used as LilyPond's extension language. Many extensions to LilyPond are written entirely in GUILE. The
53 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
54 GUILE Reference Manual} is available online.
56 @uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and
57 Interpretation of Computer Programs}, a popular textbook used to teach
58 programming in Scheme is available in its entirety online.
62 MetaFont is used to create the music fonts used by LilyPond. A MetaFont
63 tutorial is available at @uref{http://metafont.tutorial.free.fr/, the
64 METAFONT tutorial page}.
66 @subsection PostScript
68 PostScript is used to generate graphical output. A brief PostScript tutorial
69 is @uref{http://local.wasp.uwa.edu.au/~pbourke/dataformats/postscript/,
70 available online}. The
71 @uref{http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf, PostScript Lanugage
72 Reference} is available online in PDF format.
76 Python is used for XML2ly and is used for buillding the documentation and the
79 Python documentation is available at @uref{http://www.python.org/doc/,
82 @node Programming without compiling
83 @section Programming without compiling
85 Much of the development work in LilyPond takes place by changing *.ly or
86 *.scm files. These changes can be made without compiling LilyPond. Such
87 changes are described in this section.
90 @subsection Modifying distribution files
92 Much of LilyPond is written in Scheme or LilyPond input files. These
93 files are interpreted when the program is run, rather than being compiled
94 when the program is built, and are present in all LilyPond distributions.
95 You will find .ly files in the ly/ directory and the Scheme files in the
96 scm/ directory. Both Scheme files and .ly files can be modified and
97 saved with any text editor. It's probably wise to make a backup copy of
98 your files before you modify them, although you can reinstall if the
99 files become corrupted.
101 Once you've modified the files, you can test the changes just by running
102 LilyPond on some input file. It's a good idea to create a file that
103 demonstrates the feature you're trying to add. This file will eventually
104 become a regression test and will be part of the LilyPond distribution.
106 @subsection Desired file formatting
108 Files that are part of the LilyPond distribution have Unix-style line
109 endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR). Make
110 sure you use the necessary tools to ensure that Unix-style line endings are
111 preserved in the patches you create.
113 Tab characters should not be included in files for distribution. All
114 indentation should be done with spaces. Most editors have settings to
115 allow the setting of tab stops and ensuring that no tab characters are
116 included in the file.
118 Scheme files and LilyPond files should be written according to standard
119 style guidelines. Scheme file guidelines can be found at
120 @uref{http://community.schemewiki.org/?scheme-style}. Following these
121 guidelines will make your code easier to read. Both you and others that
122 work on your code will be glad you followed these guidelines.
124 For LilyPond files, you should follow the guidelines for LilyPond snippets
125 in the documentation. You can find these guidelines at
126 @ref{Texinfo introduction and usage policy}.
128 @node Finding functions
129 @section Finding functions
131 When making changes or fixing bugs in LilyPond, one of the initial
132 challenges is finding out where in the code tree the functions to
133 be modified live. With nearly 3000 files in the source tree,
134 trial-and-error searching is generally ineffective. This section
135 describes a process for finding interesting code.
137 @subsection Using the ROADMAP
139 The file ROADMAP is located in the main directory of the lilypond source.
140 ROADMAP lists all of the directories in the LilPond source tree, along
141 with a brief description of the kind of files found in each directory.
142 This can be a very helpful tool for deciding which directories to search
143 when looking for a function.
146 @subsection Using grep to search
148 Having identified a likely subdirectory to search, the grep utility can
149 be used to search for a function name. The format of the grep command is
152 grep -i functionName subdirectory/*
155 This command will search all the contents of the directory subdirectory/
156 and display every line in any of the files that contains
157 functionName. The @code{-i} option makes @command{grep} ignore
158 case -- this can be very useful if you are not yet familiar with
159 our capitalization conventions.
161 The most likely directories to grep for function names are scm/ for
162 scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
166 @subsection Using git grep to search
168 If you have used git to obtain the source, you have access to a
169 powerful tool to search for functions. The command:
172 git grep functionName
175 will search through all of the files that are present in the git
176 repository looking for functionName. It also presents the results
177 of the search using @code{less}, so the results are displayed one page
180 @subsection Searching on the git repository at Savannah
182 You can also use the equivalent of git grep on the Savannah server.
187 Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
190 In the pulldown box that says commit, select grep.
193 Type functionName in the search box, and hit enter/return
197 This will initiate a search of the remote git repository.
202 @c email to wl@gnu.org when I get here.
207 @subsection Handling errors
209 As a general rule, you should always try to continue computations,
210 even if there is some kind of error. When the program stops, it
211 is often very hard for a user to pinpoint what part of the input
212 causes an error. Finding the culprit is much easier if there is
213 some viewable output.
215 So functions and methods do not return errorcodes, they never
216 crash, but report a programming_error and try to carry on.
218 @subsection Languages
220 C++ and Python are preferred. Python code should use PEP 8.
222 @subsection Filenames
224 Definitions of classes that are only accessed via pointers (*) or
225 references (&) shall not be included as include files.
231 ".cc" Implementation files
232 ".icc" Inline definition files
233 ".tcc" non inline Template defs
237 (setq auto-mode-alist
238 (append '(("\\.make$" . makefile-mode)
239 ("\\.cc$" . c++-mode)
240 ("\\.icc$" . c++-mode)
241 ("\\.tcc$" . c++-mode)
242 ("\\.hh$" . c++-mode)
243 ("\\.pod$" . text-mode)
248 The class Class_name is coded in @q{class-name.*}
250 @subsection Indentation
252 Standard GNU coding style is used. In emacs:
255 (add-hook 'c++-mode-hook
256 '(lambda() (c-set-style "gnu")
260 If you like using font-lock, you can also add this to your
264 (setq font-lock-maximum-decoration t)
265 (setq c++-font-lock-keywords-3
267 c++-font-lock-keywords-3
268 '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
273 @subsection Classes and Types
282 Member variable names end with an underscore:
291 Macro names should be written in uppercase completely.
294 @subsection Broken code
296 Do not write broken code. This includes hardwired dependencies,
297 hardwired constants, slow algorithms and obvious limitations. If
298 you can not avoid it, mark the place clearly, and add a comment
299 explaining shortcomings of the code.
301 We reject broken-in-advance on principle.
308 Messages need to follow Localization.
311 @subsection Localization
313 This document provides some guidelines for programmers write user
314 messages. To help translations, user messages must follow
315 uniform conventions. Follow these rules when coding for LilyPond.
316 Hopefully, this can be replaced by general GNU guidelines in the
317 future. Even better would be to have an English (en_BR, en_AM)
318 guide helping programmers writing consistent messages for all GNU
321 Non-preferred messages are marked with `+'. By convention,
322 ungrammatical examples are marked with `*'. However, such ungrammatical
323 examples may still be preferred.
328 Every message to the user should be localized (and thus be marked
329 for localization). This includes warning and error messages.
332 Don't localize/gettextify:
336 `programming_error ()'s
339 `programming_warning ()'s
345 output strings (PostScript, TeX, etc.)
350 Messages to be localised must be encapsulated in `_ (STRING)' or
351 `_f (FORMAT, ...)'. E.g.:
354 warning (_ ("need music in a score"));
355 error (_f ("cannot open file: `%s'", file_name));
358 In some rare cases you may need to call `gettext ()' by hand. This
359 happens when you pre-define (a list of) string constants for later
360 use. In that case, you'll probably also need to mark these string
361 constants for translation, using `_i (STRING)'. The `_i' macro is
362 a no-op, it only serves as a marker for `xgettext'.
365 char const* messages[] = @{
366 _i ("enable debugging output"),
367 _i ("ignore lilypond version"),
374 puts (gettext (messages i));
378 See also `flower/getopt-long.cc' and `lily/main.cc'.
381 Do not use leading or trailing whitespace in messages. If you need
382 whitespace to be printed, prepend or append it to the translated
386 message ("Calculating line breaks..." + " ");
390 Error or warning messages displayed with a file name and line
391 number never start with a capital, eg,
394 foo.ly: 12: not a duration: 3
397 Messages containing a final verb, or a gerund (`-ing'-form) always
398 start with a capital. Other (simpler) messages start with a
404 Not declaring: `foo'.
408 Avoid abbreviations or short forms, use `cannot' and `do not'
409 rather than `can't' or `don't'
410 To avoid having a number of different messages for the same
411 situation, we'll use quoting like this `"message: `%s'"' for all
412 strings. Numbers are not quoted:
415 _f ("cannot open file: `%s'", name_str)
416 _f ("cannot find character number: %d", i)
420 Think about translation issues. In a lot of cases, it is better to
421 translate a whole message. The english grammar mustn't be imposed
422 on the translator. So, instead of
425 stem at + moment.str () + does not fit in beam
431 _f ("stem at %s does not fit in beam", moment.str ())
435 Split up multi-sentence messages, whenever possible. Instead of
438 warning (_f ("out of tune! Can't find: `%s'", "Key_engraver"));
439 warning (_f ("cannot find font `%s', loading default", font_name));
445 warning (_ ("out of tune:"));
446 warning (_f ("cannot find: `%s', "Key_engraver"));
447 warning (_f ("cannot find font: `%s', font_name));
448 warning (_f ("Loading default font"));
452 If you must have multiple-sentence messages, use full punctuation.
453 Use two spaces after end of sentence punctuation. No punctuation
454 (esp. period) is used at the end of simple messages.
457 _f ("Non-matching braces in text `%s', adding braces", text)
458 _ ("Debug output disabled. Compiled with NPRINT.")
459 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
463 Do not modularise too much; words frequently cannot be translated
464 without context. It's probably safe to treat most occurences of
465 words like stem, beam, crescendo as separately translatable words.
468 When translating, it is preferable to put interesting information
469 at the end of the message, rather than embedded in the middle.
470 This especially applies to frequently used messages, even if this
471 would mean sacrificing a bit of eloquency. This holds for original
472 messages too, of course.
475 en: cannot open: `foo.ly'
476 + nl: kan `foo.ly' niet openen (1)
477 kan niet openen: `foo.ly'* (2)
478 niet te openen: `foo.ly'* (3)
482 The first nl message, although grammatically and stylistically
483 correct, is not friendly for parsing by humans (even if they speak
484 dutch). I guess we'd prefer something like (2) or (3).
487 Do not run make po/po-update with GNU gettext < 0.10.35
493 @node Debugging LilyPond
494 @section Debugging LilyPond
496 The most commonly used tool for debugging LilyPond is the GNU debugger
497 gdb. Use of gdb is described in this section.
499 @subsection Debugging overview
501 Using a debugger simplifies troubleshooting in at least two ways.
503 First, breakpoints can be set to pause execution at any desired point.
504 Then, when execution has paused, debugger commands can be issued to
505 explore the values of various variables or to execute functions.
507 Second, the debugger allows the display of a stack trace, which shows
508 the sequence in which functions are called and the arguments to the
509 various function calls.
512 @subsection Compiling with debugging information
514 In order to use a debugger with LilyPond, it is necessary to compile
515 LilyPond with debugging information. This is accomplished by ...
517 TODO -- get good description here, or perhaps add debugging compile
518 to AU1.1 as it comes to CG and just use a reference here.
520 TODO -- Test the following to make sure it is true.
522 If you want to be able to set breakpoints in Scheme functions, it is
523 necessary to compile guile with debugging information. This is done
526 TODO -- get compiling description for guile here.
528 @subsection Typical gdb usage
530 @subsection Typical .gdbinit files
532 The behavior of gdb can be readily customized through the use of
533 @var{.gdbinit} files. A @var{.gdbinit} file is a file named
534 @var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
535 that is placed in a user's home directory.
537 The @var{.gdbinit} file below is from Han-Wen. It sets breakpoints
538 for all errors and defines functions for displaying scheme objects
539 (ps), grobs (pgrob), and parsed music expressions (pmusic).
542 file lily/out/lilypond
545 b Grob::programming_error
548 print ly_display_scm($arg0)
551 print ly_display_scm($arg0->self_scm_)
552 print ly_display_scm($arg0->mutable_property_alist_)
553 print ly_display_scm($arg0->immutable_property_alist_)
554 print ly_display_scm($arg0->object_alist_)
557 print ly_display_scm($arg0->self_scm_)
558 print ly_display_scm($arg0->mutable_property_alist_)
559 print ly_display_scm($arg0->immutable_property_alist_)
570 Copied from an email from Carl. Maybe already included.
572 - how to use a debugger with lilypond.
574 - how to get lilypond running and pause at a guile prompt
576 - brief overview of how lilypond processes a file.