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::
18 @node Overview of LilyPond architecture
19 @section Overview of LilyPond architecture
21 LilyPond processes the input file into graphical and musical output in a
22 number of stages. This process, along with the types of routines that
23 accomplish the various stages of the process, is described in this section. A
24 more complete description of the LilyPond architecture and internal program
25 execution is found in Erik Sandberg's
26 @uref{http://lilypond.org/web/images/thesis-erik-sandberg.pdf, master's
30 The first stage of LilyPond processing is @emph{parsing}. In the parsing
31 process, music expressions in LilyPond input format are converted to music
32 expressions in Scheme format. In Scheme format, a music expression is a list
33 in tree form, with nodes that indicate the relationships between various music
34 events. The LilyPond parser is written in Bison.
36 The second stage of LilyPond processing is @emph{iterating}. Iterating
37 assigns each music event to a context, which is the environment in which the
38 music will be finally engraved. The context is responsible for all further
39 processing of the music. It is during the iteration stage that contexts are
40 created as necessary to ensure that every note has a Voice type context (e.g.
41 Voice, TabVoice, DrumVoice, CueVoice, MensuralVoice, VaticanaVoice,
42 GregorianTranscriptionVoice), that the Voice type contexts exist in
43 appropriate Staff type contexts, and that parallel Staff type contexts exist
44 in StaffGroup type contexts. In addition, during the iteration stage each
45 music event is assigned a moment, or a time in the music when the event
48 Each type of music event has an associated iterator. Iterators are defined in
49 *-iterator.cc. During iteration, an
50 event's iterator is called to deliver that music event to the appropriate
53 The final stage of LilyPond processing is @emph{translation}. During
54 translation, music events are prepared for graphical or midi output. The
55 translation step is accomplished by translators or engravers (the distinction
58 Translators are defined in C++ files named *-engraver.cc. In *-engraver.cc, a
59 C++ class of Engraver type is created. The Engraver is also declared as a
60 translator. Much of the work of translating is handled by Scheme functions,
61 which is one of the keys to LilyPond's exceptional flexibility.
64 @node LilyPond programming languages
65 @section LilyPond programming languages
67 Programming in LilyPond is done in a variety of programming languages. Each
68 language is used for a specific purpose or purposes. This section describes
69 the languages used and provides links to reference manuals and tutorials for
70 the relevant language.
74 The core functionality of LilyPond is implemented in C++.
76 C++ is so ubiquitous that it is difficult to identify either a reference
77 manual or a tutorial. Programmers unfamiliar with C++ will need to spend some
78 time to learn the language before attempting to modify the C++ code.
80 The C++ code calls Scheme/GUILE through the GUILE interface, which is
82 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE
87 The LilyPond parser is implemented in Bison, a GNU parser generator. The
88 Bison homepage is found at @uref{http://www.gnu.org/software/bison/,
89 gnu.org}. The manual (which includes both a reference and tutorial) is
90 @uref{http://www.gnu.org/software/bison/manual/index.html, available} in a
95 GNU Make is used to control the compiling process and to build the
96 documentation and the website. GNU Make documentation is available at
97 @uref{http://www.gnu.org/software/make/manual/, the GNU website}.
99 @subsection GUILE or Scheme
101 GUILE is the dialect of Scheme that is used as LilyPond's extension language. Many extensions to LilyPond are written entirely in GUILE. The
102 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
103 GUILE Reference Manual} is available online.
105 @uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and
106 Interpretation of Computer Programs}, a popular textbook used to teach
107 programming in Scheme is available in its entirety online.
109 An introduction to Guile/Scheme as used in LilyPond can be found in the
110 Learning Manual, see @rlearning{Scheme tutorial}.
114 MetaFont is used to create the music fonts used by LilyPond. A MetaFont
115 tutorial is available at @uref{http://metafont.tutorial.free.fr/, the
116 METAFONT tutorial page}.
118 @subsection PostScript
120 PostScript is used to generate graphical output. A brief PostScript tutorial
121 is @uref{http://local.wasp.uwa.edu.au/~pbourke/dataformats/postscript/,
122 available online}. The
123 @uref{http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf, PostScript Lanugage
124 Reference} is available online in PDF format.
128 Python is used for XML2ly and is used for buillding the documentation and the
131 Python documentation is available at @uref{http://www.python.org/doc/,
134 @node Programming without compiling
135 @section Programming without compiling
137 Much of the development work in LilyPond takes place by changing *.ly or
138 *.scm files. These changes can be made without compiling LilyPond. Such
139 changes are described in this section.
142 @subsection Modifying distribution files
144 Much of LilyPond is written in Scheme or LilyPond input files. These
145 files are interpreted when the program is run, rather than being compiled
146 when the program is built, and are present in all LilyPond distributions.
147 You will find .ly files in the ly/ directory and the Scheme files in the
148 scm/ directory. Both Scheme files and .ly files can be modified and
149 saved with any text editor. It's probably wise to make a backup copy of
150 your files before you modify them, although you can reinstall if the
151 files become corrupted.
153 Once you've modified the files, you can test the changes just by running
154 LilyPond on some input file. It's a good idea to create a file that
155 demonstrates the feature you're trying to add. This file will eventually
156 become a regression test and will be part of the LilyPond distribution.
158 @subsection Desired file formatting
160 Files that are part of the LilyPond distribution have Unix-style line
161 endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR). Make
162 sure you use the necessary tools to ensure that Unix-style line endings are
163 preserved in the patches you create.
165 Tab characters should not be included in files for distribution. All
166 indentation should be done with spaces. Most editors have settings to
167 allow the setting of tab stops and ensuring that no tab characters are
168 included in the file.
170 Scheme files and LilyPond files should be written according to standard
171 style guidelines. Scheme file guidelines can be found at
172 @uref{http://community.schemewiki.org/?scheme-style}. Following these
173 guidelines will make your code easier to read. Both you and others that
174 work on your code will be glad you followed these guidelines.
176 For LilyPond files, you should follow the guidelines for LilyPond snippets
177 in the documentation. You can find these guidelines at
178 @ref{Texinfo introduction and usage policy}.
180 @node Finding functions
181 @section Finding functions
183 When making changes or fixing bugs in LilyPond, one of the initial
184 challenges is finding out where in the code tree the functions to
185 be modified live. With nearly 3000 files in the source tree,
186 trial-and-error searching is generally ineffective. This section
187 describes a process for finding interesting code.
189 @subsection Using the ROADMAP
191 The file ROADMAP is located in the main directory of the lilypond source.
192 ROADMAP lists all of the directories in the LilPond source tree, along
193 with a brief description of the kind of files found in each directory.
194 This can be a very helpful tool for deciding which directories to search
195 when looking for a function.
198 @subsection Using grep to search
200 Having identified a likely subdirectory to search, the grep utility can
201 be used to search for a function name. The format of the grep command is
204 grep -i functionName subdirectory/*
207 This command will search all the contents of the directory subdirectory/
208 and display every line in any of the files that contains
209 functionName. The @code{-i} option makes @command{grep} ignore
210 case -- this can be very useful if you are not yet familiar with
211 our capitalization conventions.
213 The most likely directories to grep for function names are scm/ for
214 scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
218 @subsection Using git grep to search
220 If you have used git to obtain the source, you have access to a
221 powerful tool to search for functions. The command:
224 git grep functionName
227 will search through all of the files that are present in the git
228 repository looking for functionName. It also presents the results
229 of the search using @code{less}, so the results are displayed one page
232 @subsection Searching on the git repository at Savannah
234 You can also use the equivalent of git grep on the Savannah server.
239 Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
242 In the pulldown box that says commit, select grep.
245 Type functionName in the search box, and hit enter/return
249 This will initiate a search of the remote git repository.
258 @subsection Handling errors
260 As a general rule, you should always try to continue computations,
261 even if there is some kind of error. When the program stops, it
262 is often very hard for a user to pinpoint what part of the input
263 causes an error. Finding the culprit is much easier if there is
264 some viewable output.
266 So functions and methods do not return errorcodes, they never
267 crash, but report a programming_error and try to carry on.
269 @subsection Languages
271 C++ and Python are preferred. Python code should use PEP 8.
273 @subsection Filenames
275 Definitions of classes that are only accessed via pointers (*) or
276 references (&) shall not be included as include files.
282 ".cc" Implementation files
283 ".icc" Inline definition files
284 ".tcc" non inline Template defs
288 (setq auto-mode-alist
289 (append '(("\\.make$" . makefile-mode)
290 ("\\.cc$" . c++-mode)
291 ("\\.icc$" . c++-mode)
292 ("\\.tcc$" . c++-mode)
293 ("\\.hh$" . c++-mode)
294 ("\\.pod$" . text-mode)
299 The class Class_name is coded in @q{class-name.*}
301 @subsection Indentation
303 Standard GNU coding style is used. In emacs:
306 (add-hook 'c++-mode-hook
307 '(lambda() (c-set-style "gnu")
311 If you like using font-lock, you can also add this to your
315 (setq font-lock-maximum-decoration t)
316 (setq c++-font-lock-keywords-3
318 c++-font-lock-keywords-3
319 '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
323 @subsection Indenting files with emacs in script mode
325 @c email to wl@gnu.org when I get here.
326 @c should be moved to Indentation section
328 @warning{this is pending some confirmation on -devel. July 2009 -gp}
330 Command-line script to format stuff with emacs:
334 emacs $1 -batch --eval '(indent-region (point-min) (point-max) nil)' -f save-buffer
337 (that's all on one line)
339 Save it as a shell script, then run on the file(s) you modified.
341 @subsection Indenting with vim
343 Although emacs indentation is the LilyPond standard, acceptable
344 indentation can usually be accomplished with vim. Some hints for
356 filetype plugin indent on
358 set ignorecase smartcase
361 set statusline=%F%m%r%h%w\ %{&ff}\ %Y\ [ASCII=\%03.3b]\ [HEX=\%02.2B]\ %04l,%04v\ %p%%\ [LEN=%L]
364 " Remove trailing whitespace on write
365 autocmd BufWritePre * :%s/\s\+$//e
368 With this .vimrc, files can be reindented automatically by highlihting
369 the lines to be indented in visual mode (use V to enter visual mode)
372 A scheme.vim file will help improve the indentation. This one
373 was suggested by Patrick McCarty. It should be saved in
374 ~/.vim/after/syntax/scheme.vim.
377 " Additional Guile-specific 'forms'
378 syn keyword schemeSyntax define-public define* define-safe-public
379 syn keyword schemeSyntax use-modules define-module
380 syn keyword schemeSyntax defmacro-public define-macro
381 syn keyword schemeSyntax define-builtin-markup-command
382 syn keyword schemeSyntax define-markup-command
383 syn keyword schemeSyntax define-builtin-markup-list-command
384 syn keyword schemeSyntax let-keywords* lambda* define*-public
385 syn keyword schemeSyntax defmacro* defmacro*-public
387 " All of the above should influence indenting too
388 set lw+=define-public,define*,define-safe-public,use-modules,define-module
389 set lw+=defmacro-public,define-macro,define-builtin-markup-command
390 set lw+=define-markup-command,define-builtin-markup-list-command
391 set lw+=let-keywords*,lambda*,define*-public,defmacro*,defmacro*-public
393 " These forms should not influence indenting
397 " Try to highlight all ly: procedures
398 syn match schemeFunc "ly:[^) ]\+"
401 @subsection Classes and Types
410 Member variable names end with an underscore:
419 Macro names should be written in uppercase completely.
422 @subsection Broken code
424 Do not write broken code. This includes hardwired dependencies,
425 hardwired constants, slow algorithms and obvious limitations. If
426 you can not avoid it, mark the place clearly, and add a comment
427 explaining shortcomings of the code.
429 We reject broken-in-advance on principle.
436 Messages need to follow Localization.
439 @subsection Localization
441 This document provides some guidelines for programmers write user
442 messages. To help translations, user messages must follow
443 uniform conventions. Follow these rules when coding for LilyPond.
444 Hopefully, this can be replaced by general GNU guidelines in the
445 future. Even better would be to have an English (en_BR, en_AM)
446 guide helping programmers writing consistent messages for all GNU
449 Non-preferred messages are marked with `+'. By convention,
450 ungrammatical examples are marked with `*'. However, such ungrammatical
451 examples may still be preferred.
456 Every message to the user should be localized (and thus be marked
457 for localization). This includes warning and error messages.
460 Do not localize/gettextify:
464 `programming_error ()'s
467 `programming_warning ()'s
473 output strings (PostScript, TeX, etc.)
478 Messages to be localised must be encapsulated in `_ (STRING)' or
479 `_f (FORMAT, ...)'. E.g.:
482 warning (_ ("need music in a score"));
483 error (_f ("cannot open file: `%s'", file_name));
486 In some rare cases you may need to call `gettext ()' by hand. This
487 happens when you pre-define (a list of) string constants for later
488 use. In that case, you'll probably also need to mark these string
489 constants for translation, using `_i (STRING)'. The `_i' macro is
490 a no-op, it only serves as a marker for `xgettext'.
493 char const* messages[] = @{
494 _i ("enable debugging output"),
495 _i ("ignore lilypond version"),
502 puts (gettext (messages i));
506 See also `flower/getopt-long.cc' and `lily/main.cc'.
509 Do not use leading or trailing whitespace in messages. If you need
510 whitespace to be printed, prepend or append it to the translated
514 message ("Calculating line breaks..." + " ");
518 Error or warning messages displayed with a file name and line
519 number never start with a capital, eg,
522 foo.ly: 12: not a duration: 3
525 Messages containing a final verb, or a gerund (`-ing'-form) always
526 start with a capital. Other (simpler) messages start with a
532 Not declaring: `foo'.
536 Avoid abbreviations or short forms, use `cannot' and `do not'
537 rather than `can't' or `don't'
538 To avoid having a number of different messages for the same
539 situation, well will use quoting like this `"message: `%s'"' for all
540 strings. Numbers are not quoted:
543 _f ("cannot open file: `%s'", name_str)
544 _f ("cannot find character number: %d", i)
548 Think about translation issues. In a lot of cases, it is better to
549 translate a whole message. The english grammar must not be imposed
550 on the translator. So, instead of
553 stem at + moment.str () + does not fit in beam
559 _f ("stem at %s does not fit in beam", moment.str ())
563 Split up multi-sentence messages, whenever possible. Instead of
566 warning (_f ("out of tune! Can't find: `%s'", "Key_engraver"));
567 warning (_f ("cannot find font `%s', loading default", font_name));
573 warning (_ ("out of tune:"));
574 warning (_f ("cannot find: `%s', "Key_engraver"));
575 warning (_f ("cannot find font: `%s', font_name));
576 warning (_f ("Loading default font"));
580 If you must have multiple-sentence messages, use full punctuation.
581 Use two spaces after end of sentence punctuation. No punctuation
582 (esp. period) is used at the end of simple messages.
585 _f ("Non-matching braces in text `%s', adding braces", text)
586 _ ("Debug output disabled. Compiled with NPRINT.")
587 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
591 Do not modularise too much; words frequently cannot be translated
592 without context. It is probably safe to treat most occurences of
593 words like stem, beam, crescendo as separately translatable words.
596 When translating, it is preferable to put interesting information
597 at the end of the message, rather than embedded in the middle.
598 This especially applies to frequently used messages, even if this
599 would mean sacrificing a bit of eloquency. This holds for original
600 messages too, of course.
603 en: cannot open: `foo.ly'
604 + nl: kan `foo.ly' niet openen (1)
605 kan niet openen: `foo.ly'* (2)
606 niet te openen: `foo.ly'* (3)
610 The first nl message, although grammatically and stylistically
611 correct, is not friendly for parsing by humans (even if they speak
612 dutch). I guess we would prefer something like (2) or (3).
615 Do not run make po/po-update with GNU gettext < 0.10.35
621 @node Debugging LilyPond
622 @section Debugging LilyPond
624 The most commonly used tool for debugging LilyPond is the GNU debugger
625 gdb. Use of gdb is described in this section.
627 @subsection Debugging overview
629 Using a debugger simplifies troubleshooting in at least two ways.
631 First, breakpoints can be set to pause execution at any desired point.
632 Then, when execution has paused, debugger commands can be issued to
633 explore the values of various variables or to execute functions.
635 Second, the debugger allows the display of a stack trace, which shows
636 the sequence in which functions are called and the arguments to the
637 various function calls.
640 @subsection Compiling with debugging information
642 In order to use a debugger with LilyPond, it is necessary to compile
643 LilyPond with debugging information. This is accomplished by running
644 the following commands in the main LilyPond source directory.
647 ./configure --disable-optimising
652 This will create a version of LilyPond that contains the debugging
653 information that will allow the debugger to tie the source code
654 to the compiled code.
656 You should not do @var{make install} if you want to use a debugger
657 with LilyPond. @var{make install} will strip the debugging information
658 from the LilyPond binary.
660 To set breakpoints in Scheme functions, put
663 \include "guile-debugger.ly"
666 in your input file after any scheme procedures you have defined in
667 that file. When your input file is processed, a guile prompt
668 will be displayed. At the guile prompt, you can set breakpoints with
669 the @code{break!} procedure:
672 guile> (break! my-scheme-procedure)
675 Once you have set the desired breakpoints, you exit the guile repl frame
682 When one of the scheme routines for which you have set breakpoints is
683 entered, guile will interrupt execution in a debug frame. At this point,
684 you will have access to guile debugging commands. For a listing of these
691 @subsection Typical gdb usage
693 @subsection Typical .gdbinit files
695 The behavior of gdb can be readily customized through the use of
696 @var{.gdbinit} files. A @var{.gdbinit} file is a file named
697 @var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
698 that is placed in a user's home directory.
700 The @var{.gdbinit} file below is from Han-Wen. It sets breakpoints
701 for all errors and defines functions for displaying scheme objects
702 (ps), grobs (pgrob), and parsed music expressions (pmusic).
705 file lily/out/lilypond
707 b Grob::programming_error
710 print ly_display_scm($arg0)
713 print ly_display_scm($arg0->self_scm_)
714 print ly_display_scm($arg0->mutable_property_alist_)
715 print ly_display_scm($arg0->immutable_property_alist_)
716 print ly_display_scm($arg0->object_alist_)
719 print ly_display_scm($arg0->self_scm_)
720 print ly_display_scm($arg0->mutable_property_alist_)
721 print ly_display_scm($arg0->immutable_property_alist_)
725 @subsection Using Guile interactively with LilyPond
727 In order to experiment with Scheme programming in the LilyPond
728 environment, it is convenient to have a Guile interpreter that
729 has all the LilyPond modules loaded. This requires the following
732 First, define a Scheme symbol for the active module
736 #(module-define! (resolve-module '(guile-user))
737 'lilypond-module (current-module))
740 Second, place a Scheme function in the .ly file that gives an interactive Guile
747 When the .ly file is compiled, this causes the compilation to be interrupted
748 and an interactive guile prompt to appear. When the guile prompt appears,
749 the LilyPond active module must be set as the current guile module:
752 guile> (set-current-module lilypond-module)
755 Proper operation of these commands can be demonstrated by typing the name
756 of a LilyPond public scheme function to see if it's properly defined:
759 guile> fret-diagram-verbose-markup
760 #<procedure fret-diagram-verbose-markup (layout props marking-list)>
763 If the LilyPond module has not been correctly loaded, an error
764 message will be generated:
767 guile> fret-diagram-verbose-markup
768 ERROR: Unbound variable: fret-diagram-verbose-markup
769 ABORT: (unbound-variable)
772 Once the module is properly loaded, any valid LilyPond Scheme expression
773 can be entered at the interactive prompt.
775 After the investigation is complete, the interactive guile interpreter
782 The compilation of the .ly file will then continue.
784 @node Adding or modifying features
785 @section Adding or modifying features
787 When a new feature is to be added to LilyPond, it is necessary to
788 ensure that the feature is properly integrated to maintain
789 its long-term support. This section describes the steps necessary
790 for feature addition and modification.
792 @subsection Write the code
794 You should probably create a new git branch for writing the code, as that
795 will separate it from the master branch and allow you to continue
796 to work on small projects related to master.
798 Please be sure to follow the rules for programming style discussed
799 earlier in this chapter.
801 @subsection Write regression tests
803 In order to demonstrate that the code works properly, you will
804 need to write one or more regression tests. These tests are
805 typically .ly files that are found in input/regression.
807 Regression tests should be as brief as possible to demonstrate the
808 functionality of the code.
810 Regression tests should generally cover one issue per test. Several
811 short, single-issue regression tests are preferred to a single, long,
812 multiple-issue regression test.
814 Use existing regression tests as templates to demonstrate the type of
815 header information that should be included in a regression test.
817 @subsection Write convert-ly rule
819 If the modification changes the input syntax, a convert-ly rule
820 should be written to automatically update input files from older
823 convert-ly rules are found in python/convertrules.py
825 If possible, the convert-ly rule should allow automatic updating
826 of the file. In some cases, this will not be possible, so the
827 rule will simply point out to the user that the feature needs
830 @subsection Automatically update documentation, snippets, and regtests
832 convert-ly should be used to update the documentation, the snippets,
833 and the regression tests. This not only makes the necessary syntax
834 changes, it also tests the convert-ly rules.
836 The automatic updating is a three step process. First, be sure you
837 are in the top-level source directory. Then, for the
841 find Documentation/ -name '*.itely' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
845 where @var{X.Y.Z} is the version number of the last released development
848 Next, for the snippets, do:
851 find Documentation/snippets/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
854 Finally, for the regression tests, do:
857 find input/regression/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
861 @subsection Manually update documentation, snippets, and regtests
863 Where the convert-ly rule is not able to automatically update the inline
864 lilypond code in the documentation (i.e. if a NOT_SMART rule is used), the
865 documentation must be manually updated. The inline snippets that require
866 changing must be changed in the English version of the docs and all
867 translated versions. If the inline code is not changed in the
868 translated documentation, the old snippets will show up in the
869 English version of the documentation.
871 Where the convert-ly rule is not able to automatically update snippets
872 in Documentation/snippets/, those snippets must be manually updated.
873 Those snippets should be copied to Documentation/snippets/new. The
874 comments at the top of the snippet describing its automatice generation
875 should be removed. All translated texidoc strings should be removed.
876 The comment @qq{% begin verbatim} should be removed. The syntax of
877 the snippet should then be manually edited.
879 Where snippets in Documentation/snippets are made obsolete, the snippet
880 should be copied to Documentation/snippets/new. The comments and
881 texidoc strings should be removed as described above. Then the body
882 of the snippet should be changed to:
886 "This snippet is deprecated as of version X.Y.Z and
887 will be removed from the documentation."
892 where X.Y.Z is the version number for which the convert-ly rule was
895 Update the snippet files by running:
898 scripts\auxiliar\makelsr.py
901 Where the convert-ly rule is not able to automatically update regression
902 tests, the regression tests in input/regression should be manually
905 Although it is not required, it is helpful if the developer
906 can write relevant material for inclusion in the Notation
907 Reference. If the developer does not feel qualified to write
908 the documentation, a documentation editor will be able to
909 write it from the regression tests. The text that is added to
910 or removed from the documentation should be changed only in
913 @subsection Write NEWS entry
915 An entry should be added to the NEWS file to describe the feature
916 changes to be implemented. This is especially important for changes
917 that change input file syntax.
919 Hints for NEWS file entries are given at the top of the NEWS file.
921 New entries in NEWS go at the top of the file.
923 The NEWS entry should be written to show how the new change
924 improves LilyPond, if possible.
926 @subsection Verify successful build
928 When the changes have been made, successful completion must be
936 When these commands complete without error, the patch is
937 considered to function successfully.
939 Developers on Windows who are unable to build LilyPond should
940 get help from a Linux or OSX developer to do the make tests.
942 @subsection Verify regression test
944 In order to avoid breaking LilyPond, it is important to verify that
945 the regression tests all succeed. This process is described in
946 @ref{Regression tests}.
948 @subsection Post patch for comments
950 For any change other than a minor change, a patch set should be
951 posted on Rietveld for comment. This requires the use of an
952 external package, git-cl.
954 git-cl is installed by:
957 git clone git://neugierig.org/git-cl.git
960 Then, add the git-cl directory to your PATH, or create a
961 symbolic link to the git-cl and upload.py in one of your
962 PATH directories (like usr/bin). git-cl will is then
970 and answering the questions that are asked.
972 The patch set is posted by issuing the following command, after
973 first committing all changes:
976 git-cl upload <reference SHA1 ID>
980 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
981 as a reference source for the patch (generally, this will be the
982 SHA1 ID of origin/master).
984 After prompting for an email and a password, the patch set will be
987 An email should then be sent to lilypond-devel, with a subject line
988 starting with PATCH:, asking for comments on the patch.
990 As revisions are made in response to comments, successive patch sets
991 for the same issue can be uploaded by reissuing the git-cl command.
993 @subsection Push patch
995 Once all the comments have been addressed, the patch can be pushed.
997 If the author has push privileges, the author will push the patch.
998 Otherwise, a developer with push privileges will push the patch.
1000 @subsection Closing the issues
1002 Once the patch has been pushed, all the relevant issues should be
1005 On Rietveld, the author should log in an close the issue either by
1006 using the @q{Edit Issue} link, or by clicking the circled x icon
1007 to the left of the issue name.
1009 If the changes were in response to a feature request on the Google
1010 issue tracker for LilyPond, the author should change the status to
1011 @q{Fixed_x_y_z} where the patch was fixed in version x.y.z. If
1012 the author does not have privileges to change the status, an email
1013 should be sent to bug-lilypond requesting the BugMeister to change
1016 @node Iterator tutorial
1017 @section Iterator tutorial
1019 FIXME -- this is a placeholder for a tutorial on iterators
1021 @node Engraver tutorial
1022 @section Engraver tutorial
1024 FIXME -- This is a placeholder for a tutorial on how engravers work.
1026 @node Callback tutorial
1027 @section Callback tutorial
1029 FIXME -- This is a placeholder for a tutorial on callback functions.