1 @c -*- coding: us-ascii; mode: texinfo; -*
4 @chapter Programming work
7 * Introduction to programming::
8 * Programming without compiling::
11 * Debugging LilyPond::
15 @node Introduction to programming
16 @section Introduction to programming
20 @node Programming without compiling
21 @section Programming without compiling
23 Much of the development work in LilyPond takes place by changing *.ly or
24 *.scm files. These changes can be made without compiling LilyPond. Such
25 changes are described in this section.
28 @subsection Modifying distribution files
30 Mving uch of LilyPond is written in Scheme or LilyPond input files. These
31 files are interpreted when the program is run, rather than being compiled
32 when the program is built, and are present in all LilyPond distributions.
33 You will find .ly files in the ly/ directory and the Scheme files in the
34 scm/ directory. Both Scheme files and .ly files can be modified and
35 saved with any text editor. It's probably wise to make a backup copy of
36 your files before you modify them, although you can reinstall if the
37 files become corrupted.
39 Once you've modified the files, you can test the changes just by running
40 LilyPond on some input file. It's a good idea to create a file that
41 demonstrates the feature you're trying to add. This file will eventually
42 become a regression test and will be part of the LilyPond distribution.
44 @subsection Desired file formatting
46 Files that are part of the LilyPond distribution have Unix-style line
47 endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR). Make
48 sure you use the necessary tools ensure that Unix-style line endings are
49 preserved in the patches you create.
51 Tab characters should not be included in files for distribution. All
52 indentation should be done with spaces. Most editors have settings to
53 allow the setting of tab stops and ensuring that no tab characters are
56 @node Finding functions
57 @section Finding functions
59 When making changes or fixing bugs in LilyPond, one of the initial
60 challenges is finding out where in the code tree the functions to be
61 modified live. With nearly 3000 files in the source tree,
62 trial-and-error searching is generally inefective. This section describes
63 a process for finding interesting code.
65 @subsection Using the ROADMAP
67 The file ROADMAP is located in the main directory of the lilypond source.
68 ROADMAP lists all of the directories in the LilPond source tree, along
69 with a brief description of the kind of files found in each directory.
70 This can be a very helpful tool for deciding which directories to search
71 when looking for a function.
74 @subsection Using grep to search
76 Having identified a likely subdirectory to search, the grep utility can
77 be used to search for a function name. The format of the grep command is
80 grep functionName subdirectory/*
83 This command will search all the contents of the directory subdirectory/
84 and display every line in any of the files that contains functionName.
86 THe most likely directories to grep for function names are scm/ for
87 scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
91 @subsection Using git grep to search
93 If you have used git to obtain the source, you have access to a
94 powerful tool to search for functions. The command:
100 will search through all of the files that are present in the git
101 repository looking for functionName. It also presents the results
102 of the search using @code{less}, so the results are displayed one page
105 @subsection Searching on the git repository at Savannah
107 You can also use the equivalent of git grep on the Savannah server.
112 Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
115 In the pulldown box that says commit, select grep.
118 Type functionName in the search box, and hit enter/return
122 This will initiate a search of the remote git repository.
128 @c email to wl@gnu.org when I get here.
133 @subsection Handling errors
135 As a general rule, you should always try to continue computations,
136 even if there is some kind of error. When the program stops, it
137 is often very hard for a user to pinpoint what part of the input
138 causes an error. Finding the culprit is much easier if there is
139 some viewable output.
141 So functions and methods do not return errorcodes, they never
142 crash, but report a programming_error and try to carry on.
144 @subsection Languages
146 C++ and Python are preferred. Python code should use PEP 8.
148 @subsection Filenames
150 Definitions of classes that are only accessed via pointers (*) or
151 references (&) shall not be included as include files.
157 ".cc" Implementation files
158 ".icc" Inline definition files
159 ".tcc" non inline Template defs
163 (setq auto-mode-alist
164 (append '(("\\.make$" . makefile-mode)
165 ("\\.cc$" . c++-mode)
166 ("\\.icc$" . c++-mode)
167 ("\\.tcc$" . c++-mode)
168 ("\\.hh$" . c++-mode)
169 ("\\.pod$" . text-mode)
174 The class Class_name is coded in @q{class-name.*}
176 @subsection Indentation
178 Standard GNU coding style is used. In emacs:
181 (add-hook 'c++-mode-hook
182 '(lambda() (c-set-style "gnu")
186 If you like using font-lock, you can also add this to your
190 (setq font-lock-maximum-decoration t)
191 (setq c++-font-lock-keywords-3
193 c++-font-lock-keywords-3
194 '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
199 @subsection Classes and Types
208 Member variable names end with an underscore:
217 Macro names should be written in uppercase completely.
220 @subsection Broken code
222 Do not write broken code. This includes hardwired dependencies,
223 hardwired constants, slow algorithms and obvious limitations. If
224 you can not avoid it, mark the place clearly, and add a comment
225 explaining shortcomings of the code.
227 We reject broken-in-advance on principle.
234 Messages need to follow Localization.
237 @subsection Localization
239 This document provides some guidelines for programmers write user
240 messages. To help translations, user messages must follow
241 uniform conventions. Follow these rules when coding for LilyPond.
242 Hopefully, this can be replaced by general GNU guidelines in the
243 future. Even better would be to have an English (en_BR, en_AM)
244 guide helping programmers writing consistent messages for all GNU
247 Non-preferred messages are marked with `+'. By convention,
248 ungrammatical examples are marked with `*'. However, such ungrammatical
249 examples may still be preferred.
254 Every message to the user should be localized (and thus be marked
255 for localization). This includes warning and error messages.
258 Don't localize/gettextify:
262 `programming_error ()'s
265 `programming_warning ()'s
271 output strings (PostScript, TeX, etc.)
276 Messages to be localised must be encapsulated in `_ (STRING)' or
277 `_f (FORMAT, ...)'. Eg:
280 warning (_ ("need music in a score"));
281 error (_f ("cannot open file: `%s'", file_name));
284 In some rare cases you may need to call `gettext ()' by hand. This
285 happens when you pre-define (a list of) string constants for later
286 use. In that case, you'll probably also need to mark these string
287 constants for translation, using `_i (STRING)'. The `_i' macro is
288 a no-op, it only serves as a marker for `xgettext'.
291 char const* messages[] = {
292 _i ("enable debugging output"),
293 _i ("ignore lilypond version"),
301 puts (gettext (messages i));
305 See also `flower/getopt-long.cc' and `lily/main.cc'.
308 Do not use leading or trailing whitespace in messages. If you need
309 whitespace to be printed, prepend or append it to the translated
313 message (Calculating line breaks... + " ");
317 Error or warning messages displayed with a file name and line
318 number never start with a capital, eg,
321 foo.ly: 12: not a duration: 3
324 Messages containing a final verb, or a gerund (`-ing'-form) always
325 start with a capital. Other (simpler) messages start with a
331 Not declaring: `foo'.
335 Avoid abbreviations or short forms, use `cannot' and `do not'
336 rather than `can't' or `don't'
337 To avoid having a number of different messages for the same
338 situation, we'll use quoting like this `"message: `%s'"' for all
339 strings. Numbers are not quoted:
342 _f ("cannot open file: `%s'", name_str)
343 _f ("cannot find character number: %d", i)
347 Think about translation issues. In a lot of cases, it is better to
348 translate a whole message. The english grammar mustn't be imposed
349 on the translator. So, instead of
352 stem at + moment.str () + does not fit in beam
358 _f ("stem at %s does not fit in beam", moment.str ())
362 Split up multi-sentence messages, whenever possible. Instead of
365 warning (_f ("out of tune! Can't find: `%s'",
367 warning (_f ("cannot find font `%s', loading default",
374 warning (out of tune:;
375 warning (_f ("cannot find: `%s', "Key_engraver"));
376 warning (_f ("cannot find font: `%s', font_name));
377 warning (_f ("Loading default font"));
381 If you must have multiple-sentence messages, use full punctuation.
382 Use two spaces after end of sentence punctuation. No punctuation
383 (esp. period) is used at the end of simple messages.
386 _f ("Non-matching braces in text `%s', adding braces", text)
387 Debug output disabled. Compiled with NPRINT.
388 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
392 Do not modularise too much; words frequently cannot be translated
393 without context. It's probably safe to treat most occurences of
394 words like stem, beam, crescendo as separately translatable words.
397 When translating, it is preferable to put interesting information
398 at the end of the message, rather than embedded in the middle.
399 This especially applies to frequently used messages, even if this
400 would mean sacrificing a bit of eloquency. This holds for original
401 messages too, of course.
404 en: cannot open: `foo.ly'
405 + nl: kan `foo.ly' niet openen (1)
406 kan niet openen: `foo.ly'* (2)
407 niet te openen: `foo.ly'* (3)
411 The first nl message, although grammatically and stylistically
412 correct, is not friendly for parsing by humans (even if they speak
413 dutch). I guess we'd prefer something like (2) or (3).
416 Do not run make po/po-update with GNU gettext < 0.10.35
422 @node Debugging LilyPond
423 @section Debugging LilyPond
425 The most commonly used tool for debugging LilyPond is the GNU debugger
426 gdb. Use of gdb is described in this section.
428 @subsection Debugging overview
430 Using a debugger simplifies troubleshooting in at least two ways.
432 First, breakpoints can be set to pause execution at any desired point.
433 Then, when execution has paused, debugger commands can be issued to
434 explore the values of various variables or to execute functions.
436 Second, the debugger allows the display of a stack trace, which shows
437 the sequence in which functions are called and the arguments to the
438 various function calls.
441 @subsection Compiling with debugging information
443 In order to use a debugger with LilyPond, it is necessary to compile
444 LilyPond with debugging information. This is accomplished by ...
446 TODO -- get good description here, or perhaps add debugging compile
447 to AU1.1 as it comes to CG and just use a reference here.
449 TODO -- Test the following to make sure it is true.
451 If you want to be able to set breakpoints in Scheme functions, it is
452 necessary to compile guile with debugging information. This is done
455 TODO -- get compiling description for guile here.
457 @subsection Typical gdb usage
459 @subsection Typical .gdbinit files
461 The behavior of gdb can be readily customized through the use of
462 .gdbinit files. The file below is from Han-Wen. It sets breakpoints
463 for all errors and defines functions for displaying scheme objects
464 (ps), grobs (pgrob), and parsed music expressions (pmusic).
467 file lily/out/lilypond
470 b Grob::programming_error
473 print ly_display_scm($arg0)
476 print ly_display_scm($arg0->self_scm_)
477 print ly_display_scm($arg0->mutable_property_alist_)
478 print ly_display_scm($arg0->immutable_property_alist_)
479 print ly_display_scm($arg0->object_alist_)
482 print ly_display_scm($arg0->self_scm_)
483 print ly_display_scm($arg0->mutable_property_alist_)
484 print ly_display_scm($arg0->immutable_property_alist_)