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
376 " Additional Guile-specific 'forms'
377 syn keyword schemeSyntax define-public define* define-safe-public
378 syn keyword schemeSyntax use-modules define-module
379 syn keyword schemeSyntax defmacro-public define-macro
380 syn keyword schemeSyntax define-builtin-markup-command
381 syn keyword schemeSyntax define-markup-command
382 syn keyword schemeSyntax define-builtin-markup-list-command
383 syn keyword schemeSyntax let-keywords* lambda* define*-public
384 syn keyword schemeSyntax defmacro* defmacro*-public
386 " All of the above should influence indenting too
387 set lw+=define-public,define*,define-safe-public,use-modules,define-module
388 set lw+=defmacro-public,define-macro,define-builtin-markup-command
389 set lw+=define-markup-command,define-builtin-markup-list-command
390 set lw+=let-keywords*,lambda*,define*-public,defmacro*,defmacro*-public
392 " These forms should not influence indenting
396 " Try to highlight all ly: procedures
397 syn match schemeFunc "ly:[^) ]\+"
399 @subsection Classes and Types
408 Member variable names end with an underscore:
417 Macro names should be written in uppercase completely.
420 @subsection Broken code
422 Do not write broken code. This includes hardwired dependencies,
423 hardwired constants, slow algorithms and obvious limitations. If
424 you can not avoid it, mark the place clearly, and add a comment
425 explaining shortcomings of the code.
427 We reject broken-in-advance on principle.
434 Messages need to follow Localization.
437 @subsection Localization
439 This document provides some guidelines for programmers write user
440 messages. To help translations, user messages must follow
441 uniform conventions. Follow these rules when coding for LilyPond.
442 Hopefully, this can be replaced by general GNU guidelines in the
443 future. Even better would be to have an English (en_BR, en_AM)
444 guide helping programmers writing consistent messages for all GNU
447 Non-preferred messages are marked with `+'. By convention,
448 ungrammatical examples are marked with `*'. However, such ungrammatical
449 examples may still be preferred.
454 Every message to the user should be localized (and thus be marked
455 for localization). This includes warning and error messages.
458 Do not localize/gettextify:
462 `programming_error ()'s
465 `programming_warning ()'s
471 output strings (PostScript, TeX, etc.)
476 Messages to be localised must be encapsulated in `_ (STRING)' or
477 `_f (FORMAT, ...)'. E.g.:
480 warning (_ ("need music in a score"));
481 error (_f ("cannot open file: `%s'", file_name));
484 In some rare cases you may need to call `gettext ()' by hand. This
485 happens when you pre-define (a list of) string constants for later
486 use. In that case, you'll probably also need to mark these string
487 constants for translation, using `_i (STRING)'. The `_i' macro is
488 a no-op, it only serves as a marker for `xgettext'.
491 char const* messages[] = @{
492 _i ("enable debugging output"),
493 _i ("ignore lilypond version"),
500 puts (gettext (messages i));
504 See also `flower/getopt-long.cc' and `lily/main.cc'.
507 Do not use leading or trailing whitespace in messages. If you need
508 whitespace to be printed, prepend or append it to the translated
512 message ("Calculating line breaks..." + " ");
516 Error or warning messages displayed with a file name and line
517 number never start with a capital, eg,
520 foo.ly: 12: not a duration: 3
523 Messages containing a final verb, or a gerund (`-ing'-form) always
524 start with a capital. Other (simpler) messages start with a
530 Not declaring: `foo'.
534 Avoid abbreviations or short forms, use `cannot' and `do not'
535 rather than `can't' or `don't'
536 To avoid having a number of different messages for the same
537 situation, well will use quoting like this `"message: `%s'"' for all
538 strings. Numbers are not quoted:
541 _f ("cannot open file: `%s'", name_str)
542 _f ("cannot find character number: %d", i)
546 Think about translation issues. In a lot of cases, it is better to
547 translate a whole message. The english grammar must not be imposed
548 on the translator. So, instead of
551 stem at + moment.str () + does not fit in beam
557 _f ("stem at %s does not fit in beam", moment.str ())
561 Split up multi-sentence messages, whenever possible. Instead of
564 warning (_f ("out of tune! Can't find: `%s'", "Key_engraver"));
565 warning (_f ("cannot find font `%s', loading default", font_name));
571 warning (_ ("out of tune:"));
572 warning (_f ("cannot find: `%s', "Key_engraver"));
573 warning (_f ("cannot find font: `%s', font_name));
574 warning (_f ("Loading default font"));
578 If you must have multiple-sentence messages, use full punctuation.
579 Use two spaces after end of sentence punctuation. No punctuation
580 (esp. period) is used at the end of simple messages.
583 _f ("Non-matching braces in text `%s', adding braces", text)
584 _ ("Debug output disabled. Compiled with NPRINT.")
585 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
589 Do not modularise too much; words frequently cannot be translated
590 without context. It is probably safe to treat most occurences of
591 words like stem, beam, crescendo as separately translatable words.
594 When translating, it is preferable to put interesting information
595 at the end of the message, rather than embedded in the middle.
596 This especially applies to frequently used messages, even if this
597 would mean sacrificing a bit of eloquency. This holds for original
598 messages too, of course.
601 en: cannot open: `foo.ly'
602 + nl: kan `foo.ly' niet openen (1)
603 kan niet openen: `foo.ly'* (2)
604 niet te openen: `foo.ly'* (3)
608 The first nl message, although grammatically and stylistically
609 correct, is not friendly for parsing by humans (even if they speak
610 dutch). I guess we would prefer something like (2) or (3).
613 Do not run make po/po-update with GNU gettext < 0.10.35
619 @node Debugging LilyPond
620 @section Debugging LilyPond
622 The most commonly used tool for debugging LilyPond is the GNU debugger
623 gdb. Use of gdb is described in this section.
625 @subsection Debugging overview
627 Using a debugger simplifies troubleshooting in at least two ways.
629 First, breakpoints can be set to pause execution at any desired point.
630 Then, when execution has paused, debugger commands can be issued to
631 explore the values of various variables or to execute functions.
633 Second, the debugger allows the display of a stack trace, which shows
634 the sequence in which functions are called and the arguments to the
635 various function calls.
638 @subsection Compiling with debugging information
640 In order to use a debugger with LilyPond, it is necessary to compile
641 LilyPond with debugging information. This is accomplished by running
642 the following commands in the main LilyPond source directory.
645 ./configure --disable-optimising
650 This will create a version of LilyPond that contains the debugging
651 information that will allow the debugger to tie the source code
652 to the compiled code.
654 You should not do @var{make install} if you want to use a debugger
655 with LilyPond. @var{make install} will strip the debugging information
656 from the LilyPond binary.
658 To set breakpoints in Scheme functions, put
661 \include "guile-debugger.ly"
664 in your input file after any scheme procedures you have defined in
665 that file. When your input file is processed, a guile prompt
666 will be displayed. At the guile prompt, you can set breakpoints with
667 the @code{break!} procedure:
670 guile> (break! my-scheme-procedure)
673 Once you have set the desired breakpoints, you exit the guile repl frame
680 When one of the scheme routines for which you have set breakpoints is
681 entered, guile will interrupt execution in a debug frame. At this point,
682 you will have access to guile debugging commands. For a listing of these
689 @subsection Typical gdb usage
691 @subsection Typical .gdbinit files
693 The behavior of gdb can be readily customized through the use of
694 @var{.gdbinit} files. A @var{.gdbinit} file is a file named
695 @var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
696 that is placed in a user's home directory.
698 The @var{.gdbinit} file below is from Han-Wen. It sets breakpoints
699 for all errors and defines functions for displaying scheme objects
700 (ps), grobs (pgrob), and parsed music expressions (pmusic).
703 file lily/out/lilypond
705 b Grob::programming_error
708 print ly_display_scm($arg0)
711 print ly_display_scm($arg0->self_scm_)
712 print ly_display_scm($arg0->mutable_property_alist_)
713 print ly_display_scm($arg0->immutable_property_alist_)
714 print ly_display_scm($arg0->object_alist_)
717 print ly_display_scm($arg0->self_scm_)
718 print ly_display_scm($arg0->mutable_property_alist_)
719 print ly_display_scm($arg0->immutable_property_alist_)
723 @subsection Using Guile interactively with LilyPond
725 In order to experiment with Scheme programming in the LilyPond
726 environment, it is convenient to have a Guile interpreter that
727 has all the LilyPond modules loaded. This requires the following
730 First, define a Scheme symbol for the active module
734 #(module-define! (resolve-module '(guile-user))
735 'lilypond-module (current-module))
738 Second, place a Scheme function in the .ly file that gives an interactive Guile
745 When the .ly file is compiled, this causes the compilation to be interrupted
746 and an interactive guile prompt to appear. When the guile prompt appears,
747 the LilyPond active module must be set as the current guile module:
750 guile> (set-current-module lilypond-module)
753 Proper operation of these commands can be demonstrated by typing the name
754 of a LilyPond public scheme function to see if it's properly defined:
757 guile> fret-diagram-verbose-markup
758 #<procedure fret-diagram-verbose-markup (layout props marking-list)>
761 If the LilyPond module has not been correctly loaded, an error
762 message will be generated:
765 guile> fret-diagram-verbose-markup
766 ERROR: Unbound variable: fret-diagram-verbose-markup
767 ABORT: (unbound-variable)
770 Once the module is properly loaded, any valid LilyPond Scheme expression
771 can be entered at the interactive prompt.
773 After the investigation is complete, the interactive guile interpreter
780 The compilation of the .ly file will then continue.
782 @node Adding or modifying features
783 @section Adding or modifying features
785 When a new feature is to be added to LilyPond, it is necessary to
786 ensure that the feature is properly integrated to maintain
787 its long-term support. This section describes the steps necessary
788 for feature addition and modification.
790 @subsection Write the code
792 You should probably create a new git branch for writing the code, as that
793 will separate it from the master branch and allow you to continue
794 to work on small projects related to master.
796 Please be sure to follow the rules for programming style discussed
797 earlier in this chapter.
799 @subsection Write regression tests
801 In order to demonstrate that the code works properly, you will
802 need to write one or more regression tests. These tests are
803 typically .ly files that are found in input/regression.
805 Regression tests should be as brief as possible to demonstrate the
806 functionality of the code.
808 Regression tests should generally cover one issue per test. Several
809 short, single-issue regression tests are preferred to a single, long,
810 multiple-issue regression test.
812 Use existing regression tests as templates to demonstrate the type of
813 header information that should be included in a regression test.
815 @subsection Write convert-ly rule
817 If the modification changes the input syntax, a convert-ly rule
818 should be written to automatically update input files from older
821 convert-ly rules are found in python/convertrules.py
823 If possible, the convert-ly rule should allow automatic updating
824 of the file. In some cases, this will not be possible, so the
825 rule will simply point out to the user that the feature needs
828 @subsection Automatically update documentation, snippets, and regtests
830 convert-ly should be used to update the documentation, the snippets,
831 and the regression tests. This not only makes the necessary syntax
832 changes, it also tests the convert-ly rules.
834 The automatic updating is a three step process. First, be sure you
835 are in the top-level source directory. Then, for the
839 find Documentation/ -name '*.itely' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
843 where @var{X.Y.Z} is the version number of the last released development
846 Next, for the snippets, do:
849 find Documentation/snippets/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
852 Finally, for the regression tests, do:
855 find input/regression/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
859 @subsection Manually update documentation, snippets, and regtests
861 Where the convert-ly rule is not able to automatically update the inline
862 lilypond code in the documentation (i.e. if a NOT_SMART rule is used), the
863 documentation must be manually updated. The inline snippets that require
864 changing must be changed in the English version of the docs and all
865 translated versions. If the inline code is not changed in the
866 translated documentation, the old snippets will show up in the
867 English version of the documentation.
869 Where the convert-ly rule is not able to automatically update snippets
870 in Documentation/snippets/, those snippets must be manually updated.
871 Those snippets should be copied to Documentation/snippets/new. The
872 comments at the top of the snippet describing its automatice generation
873 should be removed. All translated texidoc strings should be removed.
874 The comment @qq{% begin verbatim} should be removed. The syntax of
875 the snippet should then be manually edited.
877 Where snippets in Documentation/snippets are made obsolete, the snippet
878 should be copied to Documentation/snippets/new. The comments and
879 texidoc strings should be removed as described above. Then the body
880 of the snippet should be changed to:
884 "This snippet is deprecated as of version X.Y.Z and
885 will be removed from the documentation."
890 where X.Y.Z is the version number for which the convert-ly rule was
893 Update the snippet files by running:
896 scripts\auxiliar\makelsr.py
899 Where the convert-ly rule is not able to automatically update regression
900 tests, the regression tests in input/regression should be manually
903 Although it is not required, it is helpful if the developer
904 can write relevant material for inclusion in the Notation
905 Reference. If the developer does not feel qualified to write
906 the documentation, a documentation editor will be able to
907 write it from the regression tests. The text that is added to
908 or removed from the documentation should be changed only in
911 @subsection Write NEWS entry
913 An entry should be added to the NEWS file to describe the feature
914 changes to be implemented. This is especially important for changes
915 that change input file syntax.
917 Hints for NEWS file entries are given at the top of the NEWS file.
919 New entries in NEWS go at the top of the file.
921 The NEWS entry should be written to show how the new change
922 improves LilyPond, if possible.
924 @subsection Verify successful build
926 When the changes have been made, successful completion must be
934 When these commands complete without error, the patch is
935 considered to function successfully.
937 Developers on Windows who are unable to build LilyPond should
938 get help from a Linux or OSX developer to do the make tests.
940 @subsection Verify regression test
942 In order to avoid breaking LilyPond, it is important to verify that
943 the regression tests all succeed. This process is described in
944 @ref{Regression tests}.
946 @subsection Post patch for comments
948 For any change other than a minor change, a patch set should be
949 posted on Rietveld for comment. This requires the use of an
950 external package, git-cl.
952 git-cl is installed by:
955 git clone git://neugierig.org/git-cl.git
958 Then, add the git-cl directory to your PATH, or create a
959 symbolic link to the git-cl and upload.py in one of your
960 PATH directories (like usr/bin). git-cl will is then
968 and answering the questions that are asked.
970 The patch set is posted by issuing the following command, after
971 first committing all changes:
974 git-cl upload <reference SHA1 ID>
978 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
979 as a reference source for the patch (generally, this will be the
980 SHA1 ID of origin/master).
982 After prompting for an email and a password, the patch set will be
985 An email should then be sent to lilypond-devel, with a subject line
986 starting with PATCH:, asking for comments on the patch.
988 As revisions are made in response to comments, successive patch sets
989 for the same issue can be uploaded by reissuing the git-cl command.
991 @subsection Push patch
993 Once all the comments have been addressed, the patch can be pushed.
995 If the author has push privileges, the author will push the patch.
996 Otherwise, a developer with push privileges will push the patch.
998 @subsection Closing the issues
1000 Once the patch has been pushed, all the relevant issues should be
1003 On Rietveld, the author should log in an close the issue either by
1004 using the @q{Edit Issue} link, or by clicking the circled x icon
1005 to the left of the issue name.
1007 If the changes were in response to a feature request on the Google
1008 issue tracker for LilyPond, the author should change the status to
1009 @q{Fixed_x_y_z} where the patch was fixed in version x.y.z. If
1010 the author does not have privileges to change the status, an email
1011 should be sent to bug-lilypond requesting the BugMeister to change
1014 @node Iterator tutorial
1015 @section Iterator tutorial
1017 FIXME -- this is a placeholder for a tutorial on iterators
1019 @node Engraver tutorial
1020 @section Engraver tutorial
1022 FIXME -- This is a placeholder for a tutorial on how engravers work.
1024 @node Callback tutorial
1025 @section Callback tutorial
1027 FIXME -- This is a placeholder for a tutorial on callback functions.