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::
12 * Adding or modifying features::
19 @node Overview of LilyPond architecture
20 @section Overview of LilyPond architecture
22 LilyPond processes the input file into graphical and musical output in a
23 number of stages. This process, along with the types of routines that
24 accomplish the various stages of the process, is described in this section. A
25 more complete description of the LilyPond architecture and internal program
26 execution is found in Erik Sandberg's
27 @uref{http://lilypond.org/web/images/thesis-erik-sandberg.pdf, master's
31 The first stage of LilyPond processing is @emph{parsing}. In the parsing
32 process, music expressions in LilyPond input format are converted to music
33 expressions in Scheme format. In Scheme format, a music expression is a list
34 in tree form, with nodes that indicate the relationships between various music
35 events. The LilyPond parser is written in Bison.
37 The second stage of LilyPond processing is @emph{iterating}. Iterating
38 assigns each music event to a context, which is the environment in which the
39 music will be finally engraved. The context is responsible for all further
40 processing of the music. It is during the iteration stage that contexts are
41 created as necessary to ensure that every note has a Voice type context (e.g.
42 Voice, TabVoice, DrumVoice, CueVoice, MensuralVoice, VaticanaVoice,
43 GregorianTranscriptionVoice), that the Voice type contexts exist in
44 appropriate Staff type contexts, and that parallel Staff type contexts exist
45 in StaffGroup type contexts. In addition, during the iteration stage each
46 music event is assigned a moment, or a time in the music when the event
49 Each type of music event has an associated iterator. Iterators are defined in
50 *-iterator.cc. During iteration, an
51 event's iterator is called to deliver that music event to the appropriate
54 The final stage of LilyPond processing is @emph{translation}. During
55 translation, music events are prepared for graphical or midi output. The
56 translation step is accomplished by translators or engravers (the distinction
59 Translators are defined in C++ files named *-engraver.cc. In *-engraver.cc, a
60 C++ class of Engraver type is created. The Engraver is also declared as a
61 translator. Much of the work of translating is handled by Scheme functions,
62 which is one of the keys to LilyPond's exceptional flexibility.
65 @node LilyPond programming languages
66 @section LilyPond programming languages
68 Programming in LilyPond is done in a variety of programming languages. Each
69 language is used for a specific purpose or purposes. This section describes
70 the languages used and provides links to reference manuals and tutorials for
71 the relevant language.
75 The core functionality of LilyPond is implemented in C++.
77 C++ is so ubiquitous that it is difficult to identify either a reference
78 manual or a tutorial. Programmers unfamiliar with C++ will need to spend some
79 time to learn the language before attempting to modify the C++ code.
81 The C++ code calls Scheme/GUILE through the GUILE interface, which is
83 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE
88 The LilyPond parser is implemented in Bison, a GNU parser generator. The
89 Bison homepage is found at @uref{http://www.gnu.org/software/bison/,
90 gnu.org}. The manual (which includes both a reference and tutorial) is
91 @uref{http://www.gnu.org/software/bison/manual/index.html, available} in a
96 GNU Make is used to control the compiling process and to build the
97 documentation and the website. GNU Make documentation is available at
98 @uref{http://www.gnu.org/software/make/manual/, the GNU website}.
100 @subsection GUILE or Scheme
102 GUILE is the dialect of Scheme that is used as LilyPond's extension language. Many extensions to LilyPond are written entirely in GUILE. The
103 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
104 GUILE Reference Manual} is available online.
106 @uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and
107 Interpretation of Computer Programs}, a popular textbook used to teach
108 programming in Scheme is available in its entirety online.
110 An introduction to Guile/Scheme as used in LilyPond can be found in the
111 Learning Manual, see @rlearning{Scheme tutorial}.
115 MetaFont is used to create the music fonts used by LilyPond. A MetaFont
116 tutorial is available at @uref{http://metafont.tutorial.free.fr/, the
117 METAFONT tutorial page}.
119 @subsection PostScript
121 PostScript is used to generate graphical output. A brief PostScript tutorial
122 is @uref{http://local.wasp.uwa.edu.au/~pbourke/dataformats/postscript/,
123 available online}. The
124 @uref{http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf, PostScript Lanugage
125 Reference} is available online in PDF format.
129 Python is used for XML2ly and is used for buillding the documentation and the
132 Python documentation is available at @uref{http://www.python.org/doc/,
135 @node Programming without compiling
136 @section Programming without compiling
138 Much of the development work in LilyPond takes place by changing *.ly or
139 *.scm files. These changes can be made without compiling LilyPond. Such
140 changes are described in this section.
143 @subsection Modifying distribution files
145 Much of LilyPond is written in Scheme or LilyPond input files. These
146 files are interpreted when the program is run, rather than being compiled
147 when the program is built, and are present in all LilyPond distributions.
148 You will find .ly files in the ly/ directory and the Scheme files in the
149 scm/ directory. Both Scheme files and .ly files can be modified and
150 saved with any text editor. It's probably wise to make a backup copy of
151 your files before you modify them, although you can reinstall if the
152 files become corrupted.
154 Once you've modified the files, you can test the changes just by running
155 LilyPond on some input file. It's a good idea to create a file that
156 demonstrates the feature you're trying to add. This file will eventually
157 become a regression test and will be part of the LilyPond distribution.
159 @subsection Desired file formatting
161 Files that are part of the LilyPond distribution have Unix-style line
162 endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR). Make
163 sure you use the necessary tools to ensure that Unix-style line endings are
164 preserved in the patches you create.
166 Tab characters should not be included in files for distribution. All
167 indentation should be done with spaces. Most editors have settings to
168 allow the setting of tab stops and ensuring that no tab characters are
169 included in the file.
171 Scheme files and LilyPond files should be written according to standard
172 style guidelines. Scheme file guidelines can be found at
173 @uref{http://community.schemewiki.org/?scheme-style}. Following these
174 guidelines will make your code easier to read. Both you and others that
175 work on your code will be glad you followed these guidelines.
177 For LilyPond files, you should follow the guidelines for LilyPond snippets
178 in the documentation. You can find these guidelines at
179 @ref{Texinfo introduction and usage policy}.
181 @node Finding functions
182 @section Finding functions
184 When making changes or fixing bugs in LilyPond, one of the initial
185 challenges is finding out where in the code tree the functions to
186 be modified live. With nearly 3000 files in the source tree,
187 trial-and-error searching is generally ineffective. This section
188 describes a process for finding interesting code.
190 @subsection Using the ROADMAP
192 The file ROADMAP is located in the main directory of the lilypond source.
193 ROADMAP lists all of the directories in the LilPond source tree, along
194 with a brief description of the kind of files found in each directory.
195 This can be a very helpful tool for deciding which directories to search
196 when looking for a function.
199 @subsection Using grep to search
201 Having identified a likely subdirectory to search, the grep utility can
202 be used to search for a function name. The format of the grep command is
205 grep -i functionName subdirectory/*
208 This command will search all the contents of the directory subdirectory/
209 and display every line in any of the files that contains
210 functionName. The @code{-i} option makes @command{grep} ignore
211 case -- this can be very useful if you are not yet familiar with
212 our capitalization conventions.
214 The most likely directories to grep for function names are scm/ for
215 scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
219 @subsection Using git grep to search
221 If you have used git to obtain the source, you have access to a
222 powerful tool to search for functions. The command:
225 git grep functionName
228 will search through all of the files that are present in the git
229 repository looking for functionName. It also presents the results
230 of the search using @code{less}, so the results are displayed one page
233 @subsection Searching on the git repository at Savannah
235 You can also use the equivalent of git grep on the Savannah server.
240 Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
243 In the pulldown box that says commit, select grep.
246 Type functionName in the search box, and hit enter/return
250 This will initiate a search of the remote git repository.
259 @subsection Handling errors
261 As a general rule, you should always try to continue computations,
262 even if there is some kind of error. When the program stops, it
263 is often very hard for a user to pinpoint what part of the input
264 causes an error. Finding the culprit is much easier if there is
265 some viewable output.
267 So functions and methods do not return errorcodes, they never
268 crash, but report a programming_error and try to carry on.
270 @subsection Languages
272 C++ and Python are preferred. Python code should use PEP 8.
274 @subsection Filenames
276 Definitions of classes that are only accessed via pointers (*) or
277 references (&) shall not be included as include files.
283 ".cc" Implementation files
284 ".icc" Inline definition files
285 ".tcc" non inline Template defs
289 (setq auto-mode-alist
290 (append '(("\\.make$" . makefile-mode)
291 ("\\.cc$" . c++-mode)
292 ("\\.icc$" . c++-mode)
293 ("\\.tcc$" . c++-mode)
294 ("\\.hh$" . c++-mode)
295 ("\\.pod$" . text-mode)
300 The class Class_name is coded in @q{class-name.*}
302 @subsection Indentation
304 Standard GNU coding style is used. In emacs:
307 (add-hook 'c++-mode-hook
308 '(lambda() (c-set-style "gnu")
312 If you like using font-lock, you can also add this to your
316 (setq font-lock-maximum-decoration t)
317 (setq c++-font-lock-keywords-3
319 c++-font-lock-keywords-3
320 '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
324 Some source files may not currently have proper indenting. If this
325 is the case, it is desirable to fix the improper indenting when the
326 file is modified, with the hope of continually improving the code.
328 @subsection Indenting files with emacs in script mode
330 @c email to wl@gnu.org when I get here.
332 @warning{this is pending some confirmation on -devel. July 2009 -gp}
334 Command-line script to format stuff with emacs:
338 emacs $1 -batch --eval '(indent-region (point-min) (point-max) nil)' -f save-buffer
341 (that's all on one line)
343 Save it as a shell script, then run on the file(s) you modified.
345 @subsection Indenting with vim
347 Although emacs indentation is the LilyPond standard, acceptable
348 indentation can usually be accomplished with vim. Some hints for
360 filetype plugin indent on
362 set ignorecase smartcase
365 set statusline=%F%m%r%h%w\ %{&ff}\ %Y\ [ASCII=\%03.3b]\ [HEX=\%02.2B]\ %04l,%04v\ %p%%\ [LEN=%L]
368 " Remove trailing whitespace on write
369 autocmd BufWritePre * :%s/\s\+$//e
372 With this .vimrc, files can be reindented automatically by highlihting
373 the lines to be indented in visual mode (use V to enter visual mode)
376 A scheme.vim file will help improve the indentation. This one
377 was suggested by Patrick McCarty. It should be saved in
378 ~/.vim/after/syntax/scheme.vim.
381 " Additional Guile-specific 'forms'
382 syn keyword schemeSyntax define-public define* define-safe-public
383 syn keyword schemeSyntax use-modules define-module
384 syn keyword schemeSyntax defmacro-public define-macro
385 syn keyword schemeSyntax define-builtin-markup-command
386 syn keyword schemeSyntax define-markup-command
387 syn keyword schemeSyntax define-builtin-markup-list-command
388 syn keyword schemeSyntax let-keywords* lambda* define*-public
389 syn keyword schemeSyntax defmacro* defmacro*-public
391 " All of the above should influence indenting too
392 set lw+=define-public,define*,define-safe-public,use-modules,define-module
393 set lw+=defmacro-public,define-macro,define-builtin-markup-command
394 set lw+=define-markup-command,define-builtin-markup-list-command
395 set lw+=let-keywords*,lambda*,define*-public,defmacro*,defmacro*-public
397 " These forms should not influence indenting
401 " Try to highlight all ly: procedures
402 syn match schemeFunc "ly:[^) ]\+"
405 @subsection Classes and Types
414 Member variable names end with an underscore:
423 Macro names should be written in uppercase completely.
426 @subsection Broken code
428 Do not write broken code. This includes hardwired dependencies,
429 hardwired constants, slow algorithms and obvious limitations. If
430 you can not avoid it, mark the place clearly, and add a comment
431 explaining shortcomings of the code.
433 We reject broken-in-advance on principle.
437 Variable names should be complete words, rather than abbreviations.
438 For example, it is preferred to use @code{thickness} rather than
439 @code{th} or @code{t}.
441 Multi-word variable names in C++ should have the words separated
442 by the underscore character (@q{_}).
444 Multi-word variable names in Scheme should have the words separated
449 Comments may not be needed if descriptive variable names are used
450 in the code and the logic is straightforward. However, if the
451 logic is difficult to follow, and particularly if non-obvious
452 code has been included to resolve a bug, a comment describing
453 the logic and/or the need for the non-obvious code should be included.
455 There are instances where the current code could be commented better.
456 If significant time is required to understand the code as part of
457 preparing a patch, it would be wise to add comments reflecting your
458 understanding to make future work easier.
462 Messages need to follow Localization.
465 @subsection Localization
467 This document provides some guidelines for programmers write user
468 messages. To help translations, user messages must follow
469 uniform conventions. Follow these rules when coding for LilyPond.
470 Hopefully, this can be replaced by general GNU guidelines in the
471 future. Even better would be to have an English (en_BR, en_AM)
472 guide helping programmers writing consistent messages for all GNU
475 Non-preferred messages are marked with `+'. By convention,
476 ungrammatical examples are marked with `*'. However, such ungrammatical
477 examples may still be preferred.
482 Every message to the user should be localized (and thus be marked
483 for localization). This includes warning and error messages.
486 Do not localize/gettextify:
490 `programming_error ()'s
493 `programming_warning ()'s
499 output strings (PostScript, TeX, etc.)
504 Messages to be localized must be encapsulated in `_ (STRING)' or
505 `_f (FORMAT, ...)'. E.g.:
508 warning (_ ("need music in a score"));
509 error (_f ("cannot open file: `%s'", file_name));
512 In some rare cases you may need to call `gettext ()' by hand. This
513 happens when you pre-define (a list of) string constants for later
514 use. In that case, you'll probably also need to mark these string
515 constants for translation, using `_i (STRING)'. The `_i' macro is
516 a no-op, it only serves as a marker for `xgettext'.
519 char const* messages[] = @{
520 _i ("enable debugging output"),
521 _i ("ignore lilypond version"),
528 puts (gettext (messages i));
532 See also `flower/getopt-long.cc' and `lily/main.cc'.
535 Do not use leading or trailing whitespace in messages. If you need
536 whitespace to be printed, prepend or append it to the translated
540 message ("Calculating line breaks..." + " ");
544 Error or warning messages displayed with a file name and line
545 number never start with a capital, eg,
548 foo.ly: 12: not a duration: 3
551 Messages containing a final verb, or a gerund (`-ing'-form) always
552 start with a capital. Other (simpler) messages start with a
558 Not declaring: `foo'.
562 Avoid abbreviations or short forms, use `cannot' and `do not'
563 rather than `can't' or `don't'
564 To avoid having a number of different messages for the same
565 situation, well will use quoting like this `"message: `%s'"' for all
566 strings. Numbers are not quoted:
569 _f ("cannot open file: `%s'", name_str)
570 _f ("cannot find character number: %d", i)
574 Think about translation issues. In a lot of cases, it is better to
575 translate a whole message. The english grammar must not be imposed
576 on the translator. So, instead of
579 stem at + moment.str () + does not fit in beam
585 _f ("stem at %s does not fit in beam", moment.str ())
589 Split up multi-sentence messages, whenever possible. Instead of
592 warning (_f ("out of tune! Can't find: `%s'", "Key_engraver"));
593 warning (_f ("cannot find font `%s', loading default", font_name));
599 warning (_ ("out of tune:"));
600 warning (_f ("cannot find: `%s', "Key_engraver"));
601 warning (_f ("cannot find font: `%s', font_name));
602 warning (_f ("Loading default font"));
606 If you must have multiple-sentence messages, use full punctuation.
607 Use two spaces after end of sentence punctuation. No punctuation
608 (esp. period) is used at the end of simple messages.
611 _f ("Non-matching braces in text `%s', adding braces", text)
612 _ ("Debug output disabled. Compiled with NPRINT.")
613 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
617 Do not modularize too much; words frequently cannot be translated
618 without context. It is probably safe to treat most occurences of
619 words like stem, beam, crescendo as separately translatable words.
622 When translating, it is preferable to put interesting information
623 at the end of the message, rather than embedded in the middle.
624 This especially applies to frequently used messages, even if this
625 would mean sacrificing a bit of eloquency. This holds for original
626 messages too, of course.
629 en: cannot open: `foo.ly'
630 + nl: kan `foo.ly' niet openen (1)
631 kan niet openen: `foo.ly'* (2)
632 niet te openen: `foo.ly'* (3)
636 The first nl message, although grammatically and stylistically
637 correct, is not friendly for parsing by humans (even if they speak
638 dutch). I guess we would prefer something like (2) or (3).
641 Do not run make po/po-update with GNU gettext < 0.10.35
647 @node Debugging LilyPond
648 @section Debugging LilyPond
650 The most commonly used tool for debugging LilyPond is the GNU debugger
651 gdb. Use of gdb is described in this section.
653 @subsection Debugging overview
655 Using a debugger simplifies troubleshooting in at least two ways.
657 First, breakpoints can be set to pause execution at any desired point.
658 Then, when execution has paused, debugger commands can be issued to
659 explore the values of various variables or to execute functions.
661 Second, the debugger allows the display of a stack trace, which shows
662 the sequence in which functions are called and the arguments to the
663 various function calls.
666 @subsection Compiling with debugging information
668 In order to use a debugger with LilyPond, it is necessary to compile
669 LilyPond with debugging information. This is accomplished by running
670 the following commands in the main LilyPond source directory.
673 ./configure --disable-optimising
678 This will create a version of LilyPond that contains the debugging
679 information that will allow the debugger to tie the source code
680 to the compiled code.
682 You should not do @var{make install} if you want to use a debugger
683 with LilyPond. @var{make install} will strip the debugging information
684 from the LilyPond binary.
686 To set breakpoints in Scheme functions, put
689 \include "guile-debugger.ly"
692 in your input file after any scheme procedures you have defined in
693 that file. When your input file is processed, a guile prompt
694 will be displayed. At the guile prompt, you can set breakpoints with
695 the @code{break!} procedure:
698 guile> (break! my-scheme-procedure)
701 Once you have set the desired breakpoints, you exit the guile repl frame
708 When one of the scheme routines for which you have set breakpoints is
709 entered, guile will interrupt execution in a debug frame. At this point,
710 you will have access to guile debugging commands. For a listing of these
717 @subsection Typical gdb usage
719 @subsection Typical .gdbinit files
721 The behavior of gdb can be readily customized through the use of
722 @var{.gdbinit} files. A @var{.gdbinit} file is a file named
723 @var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
724 that is placed in a user's home directory.
726 The @var{.gdbinit} file below is from Han-Wen. It sets breakpoints
727 for all errors and defines functions for displaying scheme objects
728 (ps), grobs (pgrob), and parsed music expressions (pmusic).
731 file lily/out/lilypond
733 b Grob::programming_error
736 print ly_display_scm($arg0)
739 print ly_display_scm($arg0->self_scm_)
740 print ly_display_scm($arg0->mutable_property_alist_)
741 print ly_display_scm($arg0->immutable_property_alist_)
742 print ly_display_scm($arg0->object_alist_)
745 print ly_display_scm($arg0->self_scm_)
746 print ly_display_scm($arg0->mutable_property_alist_)
747 print ly_display_scm($arg0->immutable_property_alist_)
751 @subsection Using Guile interactively with LilyPond
753 In order to experiment with Scheme programming in the LilyPond
754 environment, it is convenient to have a Guile interpreter that
755 has all the LilyPond modules loaded. This requires the following
758 First, define a Scheme symbol for the active module
762 #(module-define! (resolve-module '(guile-user))
763 'lilypond-module (current-module))
766 Second, place a Scheme function in the .ly file that gives an interactive Guile
773 When the .ly file is compiled, this causes the compilation to be interrupted
774 and an interactive guile prompt to appear. When the guile prompt appears,
775 the LilyPond active module must be set as the current guile module:
778 guile> (set-current-module lilypond-module)
781 Proper operation of these commands can be demonstrated by typing the name
782 of a LilyPond public scheme function to see if it's properly defined:
785 guile> fret-diagram-verbose-markup
786 #<procedure fret-diagram-verbose-markup (layout props marking-list)>
789 If the LilyPond module has not been correctly loaded, an error
790 message will be generated:
793 guile> fret-diagram-verbose-markup
794 ERROR: Unbound variable: fret-diagram-verbose-markup
795 ABORT: (unbound-variable)
798 Once the module is properly loaded, any valid LilyPond Scheme expression
799 can be entered at the interactive prompt.
801 After the investigation is complete, the interactive guile interpreter
808 The compilation of the .ly file will then continue.
810 @node Adding or modifying features
811 @section Adding or modifying features
813 When a new feature is to be added to LilyPond, it is necessary to
814 ensure that the feature is properly integrated to maintain
815 its long-term support. This section describes the steps necessary
816 for feature addition and modification.
818 @subsection Write the code
820 You should probably create a new git branch for writing the code, as that
821 will separate it from the master branch and allow you to continue
822 to work on small projects related to master.
824 Please be sure to follow the rules for programming style discussed
825 earlier in this chapter.
827 @subsection Write regression tests
829 In order to demonstrate that the code works properly, you will
830 need to write one or more regression tests. These tests are
831 typically .ly files that are found in input/regression.
833 Regression tests should be as brief as possible to demonstrate the
834 functionality of the code.
836 Regression tests should generally cover one issue per test. Several
837 short, single-issue regression tests are preferred to a single, long,
838 multiple-issue regression test.
840 Use existing regression tests as templates to demonstrate the type of
841 header information that should be included in a regression test.
843 @subsection Write convert-ly rule
845 If the modification changes the input syntax, a convert-ly rule
846 should be written to automatically update input files from older
849 convert-ly rules are found in python/convertrules.py
851 If possible, the convert-ly rule should allow automatic updating
852 of the file. In some cases, this will not be possible, so the
853 rule will simply point out to the user that the feature needs
856 @subsection Automatically update documentation, snippets, and regtests
858 convert-ly should be used to update the documentation, the snippets,
859 and the regression tests. This not only makes the necessary syntax
860 changes, it also tests the convert-ly rules.
862 The automatic updating is a three step process. First, be sure you
863 are in the top-level source directory. Then, for the
867 find Documentation/ -name '*.itely' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
871 where @var{X.Y.Z} is the version number of the last released development
874 Next, for the snippets, do:
877 find Documentation/snippets/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
880 Finally, for the regression tests, do:
883 find input/regression/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
887 @subsection Manually update documentation, snippets, and regtests
889 Where the convert-ly rule is not able to automatically update the inline
890 lilypond code in the documentation (i.e. if a NOT_SMART rule is used), the
891 documentation must be manually updated. The inline snippets that require
892 changing must be changed in the English version of the docs and all
893 translated versions. If the inline code is not changed in the
894 translated documentation, the old snippets will show up in the
895 English version of the documentation.
897 Where the convert-ly rule is not able to automatically update snippets
898 in Documentation/snippets/, those snippets must be manually updated.
899 Those snippets should be copied to Documentation/snippets/new. The
900 comments at the top of the snippet describing its automatice generation
901 should be removed. All translated texidoc strings should be removed.
902 The comment @qq{% begin verbatim} should be removed. The syntax of
903 the snippet should then be manually edited.
905 Where snippets in Documentation/snippets are made obsolete, the snippet
906 should be copied to Documentation/snippets/new. The comments and
907 texidoc strings should be removed as described above. Then the body
908 of the snippet should be changed to:
912 "This snippet is deprecated as of version X.Y.Z and
913 will be removed from the documentation."
918 where X.Y.Z is the version number for which the convert-ly rule was
921 Update the snippet files by running:
924 scripts\auxiliar\makelsr.py
927 Where the convert-ly rule is not able to automatically update regression
928 tests, the regression tests in input/regression should be manually
931 Although it is not required, it is helpful if the developer
932 can write relevant material for inclusion in the Notation
933 Reference. If the developer does not feel qualified to write
934 the documentation, a documentation editor will be able to
935 write it from the regression tests. The text that is added to
936 or removed from the documentation should be changed only in
939 @subsection Write NEWS entry
941 An entry should be added to the NEWS file to describe the feature
942 changes to be implemented. This is especially important for changes
943 that change input file syntax.
945 Hints for NEWS file entries are given at the top of the NEWS file.
947 New entries in NEWS go at the top of the file.
949 The NEWS entry should be written to show how the new change
950 improves LilyPond, if possible.
952 @subsection Verify successful build
954 When the changes have been made, successful completion must be
962 When these commands complete without error, the patch is
963 considered to function successfully.
965 Developers on Windows who are unable to build LilyPond should
966 get help from a Linux or OSX developer to do the make tests.
968 @subsection Verify regression test
970 In order to avoid breaking LilyPond, it is important to verify that
971 the regression tests all succeed. This process is described in
972 @ref{Regression tests}.
974 @subsection Post patch for comments
976 For any change other than a minor change, a patch set should be
977 posted on Rietveld for comment. This requires the use of an
978 external package, git-cl.
980 git-cl is installed by:
983 git clone git://neugierig.org/git-cl.git
986 Then, add the git-cl directory to your PATH, or create a
987 symbolic link to the git-cl and upload.py in one of your
988 PATH directories (like usr/bin). git-cl will is then
996 and answering the questions that are asked.
998 The patch set is posted by issuing the following command, after
999 first committing all changes:
1002 git-cl upload <reference SHA1 ID>
1006 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1007 as a reference source for the patch (generally, this will be the
1008 SHA1 ID of origin/master).
1010 After prompting for an email and a password, the patch set will be
1013 An email should then be sent to lilypond-devel, with a subject line
1014 starting with PATCH:, asking for comments on the patch.
1016 As revisions are made in response to comments, successive patch sets
1017 for the same issue can be uploaded by reissuing the git-cl command.
1019 @subsection Push patch
1021 Once all the comments have been addressed, the patch can be pushed.
1023 If the author has push privileges, the author will push the patch.
1024 Otherwise, a developer with push privileges will push the patch.
1026 @subsection Closing the issues
1028 Once the patch has been pushed, all the relevant issues should be
1031 On Rietveld, the author should log in an close the issue either by
1032 using the @q{Edit Issue} link, or by clicking the circled x icon
1033 to the left of the issue name.
1035 If the changes were in response to a feature request on the Google
1036 issue tracker for LilyPond, the author should change the status to
1037 @q{Fixed_x_y_z} where the patch was fixed in version x.y.z. If
1038 the author does not have privileges to change the status, an email
1039 should be sent to bug-lilypond requesting the BugMeister to change
1042 @node Iterator tutorial
1043 @section Iterator tutorial
1045 FIXME -- this is a placeholder for a tutorial on iterators
1047 Iterators are routines written in C++ that process music expressions
1048 and sent the music events to the appropriate engravers and/or
1051 @node Engraver tutorial
1052 @section Engraver tutorial
1054 FIXME -- This is a placeholder for a tutorial on how engravers work.
1056 Engravers are C++ classes that catch music events and
1057 create the appropriate grobs for display on the page. Each different
1058 type of grob has its own engraver.
1060 A typical engraver has protected functions including some or all
1064 @item @code{start_translation_timestep ()}
1065 @item @code{process_music ()}
1066 @item @code{stop_translation_timestep ()}
1067 @item @code{derived_mark ()}
1068 @item @code{try_music ()}
1069 @item @code{finalize ()}
1072 There are also protected functions that are specific to particular
1073 engraver, as needed by the engraving process.
1075 External interfaces to to the engraver are implemented by protected
1076 macros including one or more of the following:
1079 @item @code{DECLARE_ACKNOWLEDGER (grob)}
1080 @item @code{DECLARE_TRANSLATOR_LISTENER (grob)}
1081 @item @code{DECLARE_END_ACKNOWLEDGER (grob)}
1085 where @var{grob} is the
1086 type of grob with which the engraver works.
1087 These macros declare the kinds of grobs that will be processed by
1090 An engraver will also generally have a public macro
1093 @item @code{TRANSLATOR_DECLARATIONS (Engraver_name)}
1097 where @code{Engraver_name} is the name of the engraver.
1099 At the end of the engraver file, the following macros are generally
1103 @item @code{ADD_ACKNOWLEDGER (Engraver_name, grob)}
1104 @item @code{ADD_TRANSLATOR (Engraver_name, Engraver_doc,
1105 Engraver_creates, Engraver_reads, Engraver_writes)}
1109 where @code{Engraver_name} is the name of the engraver, @code{grob}
1110 is a placeholder for a grob that will be acknowledged,
1111 @code{Engraver_doc} is a docstring for the engraver,
1112 @code{Engraver_creates} is the grob created by the engraver,
1113 @code{Engraver_reads} is the set of properties read by the engraver,
1114 and @code{Engraver_writes} is the set of properties written by
1117 @node Callback tutorial
1118 @section Callback tutorial
1120 FIXME -- This is a placeholder for a tutorial on callback functions.
1122 @node LilyPond scoping
1123 @section LilyPond scoping
1125 The Lilypond language has a concept of scoping, ie you can do
1131 (display (+ foo 2)))
1134 @noindent with @code{\paper}, @code{\midi} and @code{\header} being
1135 nested scope inside the .ly file-level scope. @w{@code{foo = 1}} is
1136 translated in to a scheme variable definition.
1138 This implemented using modules, with each scope being an anonymous
1139 module that imports its enclosing scope's module.
1141 The reason to put some functions (@qq{builtin}) outside the .ly level,
1149 we want to reuse the built-in definitions, without changes
1150 effected in a.ly leaking into the processing of b.ly.
1152 Maintaining this scoping when one .ly file can be included in another
1153 .ly file can be challenging. A @code{define-public-toplevel} macro
1154 has been created in order to handle a difficulty caused by the modules
1155 being not the same when a .ly file is included into another.
1156 This provided a way to define all markup commands in the same module.
1157 At this time, we have found no easier way to define a function in a given
1158 module (not the current one) than to define this macro.
1160 With this architecture, the guile module system is not bypassed:
1161 module-define!, module-export! and module-ref are all guile module
1164 A second reason for using this current architecture is to avoid memory
1165 leaks that could occur when running multiple files if toplevel
1166 functions were registered permanently.