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
18 FIXME -- decide what goes in here and put it here. I'm not sure what
21 @node Programming without compiling
22 @section Programming without compiling
24 Much of the development work in LilyPond takes place by changing *.ly or
25 *.scm files. These changes can be made without compiling LilyPond. Such
26 changes are described in this section.
29 @subsection Modifying distribution files
31 Much of LilyPond is written in Scheme or LilyPond input files. These
32 files are interpreted when the program is run, rather than being compiled
33 when the program is built, and are present in all LilyPond distributions.
34 You will find .ly files in the ly/ directory and the Scheme files in the
35 scm/ directory. Both Scheme files and .ly files can be modified and
36 saved with any text editor. It's probably wise to make a backup copy of
37 your files before you modify them, although you can reinstall if the
38 files become corrupted.
40 Once you've modified the files, you can test the changes just by running
41 LilyPond on some input file. It's a good idea to create a file that
42 demonstrates the feature you're trying to add. This file will eventually
43 become a regression test and will be part of the LilyPond distribution.
45 @subsection Desired file formatting
47 Files that are part of the LilyPond distribution have Unix-style line
48 endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR). Make
49 sure you use the necessary tools to ensure that Unix-style line endings are
50 preserved in the patches you create.
52 Tab characters should not be included in files for distribution. All
53 indentation should be done with spaces. Most editors have settings to
54 allow the setting of tab stops and ensuring that no tab characters are
57 Scheme files and LilyPond files should be written according to standard
58 style guidelines. Scheme file guidelines can be found at
59 @uref{http://community.schemewiki.org/?scheme-style}. Following these
60 guidelines will make your code easier to read. Both you and others that
61 work on your code will be glad you followed these guidelines.
63 For LilyPond files, you should follow the guidelines for LilyPond snippets
64 in the documentation. You can find these guidelines at
65 @ref{Texinfo introduction and usage policy}.
67 @node Finding functions
68 @section Finding functions
70 When making changes or fixing bugs in LilyPond, one of the initial
71 challenges is finding out where in the code tree the functions to be
72 modified live. With nearly 3000 files in the source tree,
73 trial-and-error searching is generally inefective. This section describes
74 a process for finding interesting code.
76 @subsection Using the ROADMAP
78 The file ROADMAP is located in the main directory of the lilypond source.
79 ROADMAP lists all of the directories in the LilPond source tree, along
80 with a brief description of the kind of files found in each directory.
81 This can be a very helpful tool for deciding which directories to search
82 when looking for a function.
85 @subsection Using grep to search
87 Having identified a likely subdirectory to search, the grep utility can
88 be used to search for a function name. The format of the grep command is
91 grep functionName subdirectory/*
94 This command will search all the contents of the directory subdirectory/
95 and display every line in any of the files that contains functionName.
97 The most likely directories to grep for function names are scm/ for
98 scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
102 @subsection Using git grep to search
104 If you have used git to obtain the source, you have access to a
105 powerful tool to search for functions. The command:
108 git grep functionName
111 will search through all of the files that are present in the git
112 repository looking for functionName. It also presents the results
113 of the search using @code{less}, so the results are displayed one page
116 @subsection Searching on the git repository at Savannah
118 You can also use the equivalent of git grep on the Savannah server.
123 Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
126 In the pulldown box that says commit, select grep.
129 Type functionName in the search box, and hit enter/return
133 This will initiate a search of the remote git repository.
138 @c email to wl@gnu.org when I get here.
143 @subsection Handling errors
145 As a general rule, you should always try to continue computations,
146 even if there is some kind of error. When the program stops, it
147 is often very hard for a user to pinpoint what part of the input
148 causes an error. Finding the culprit is much easier if there is
149 some viewable output.
151 So functions and methods do not return errorcodes, they never
152 crash, but report a programming_error and try to carry on.
154 @subsection Languages
156 C++ and Python are preferred. Python code should use PEP 8.
158 @subsection Filenames
160 Definitions of classes that are only accessed via pointers (*) or
161 references (&) shall not be included as include files.
167 ".cc" Implementation files
168 ".icc" Inline definition files
169 ".tcc" non inline Template defs
173 (setq auto-mode-alist
174 (append '(("\\.make$" . makefile-mode)
175 ("\\.cc$" . c++-mode)
176 ("\\.icc$" . c++-mode)
177 ("\\.tcc$" . c++-mode)
178 ("\\.hh$" . c++-mode)
179 ("\\.pod$" . text-mode)
184 The class Class_name is coded in @q{class-name.*}
186 @subsection Indentation
188 Standard GNU coding style is used. In emacs:
191 (add-hook 'c++-mode-hook
192 '(lambda() (c-set-style "gnu")
196 If you like using font-lock, you can also add this to your
200 (setq font-lock-maximum-decoration t)
201 (setq c++-font-lock-keywords-3
203 c++-font-lock-keywords-3
204 '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
209 @subsection Classes and Types
218 Member variable names end with an underscore:
227 Macro names should be written in uppercase completely.
230 @subsection Broken code
232 Do not write broken code. This includes hardwired dependencies,
233 hardwired constants, slow algorithms and obvious limitations. If
234 you can not avoid it, mark the place clearly, and add a comment
235 explaining shortcomings of the code.
237 We reject broken-in-advance on principle.
244 Messages need to follow Localization.
247 @subsection Localization
249 This document provides some guidelines for programmers write user
250 messages. To help translations, user messages must follow
251 uniform conventions. Follow these rules when coding for LilyPond.
252 Hopefully, this can be replaced by general GNU guidelines in the
253 future. Even better would be to have an English (en_BR, en_AM)
254 guide helping programmers writing consistent messages for all GNU
257 Non-preferred messages are marked with `+'. By convention,
258 ungrammatical examples are marked with `*'. However, such ungrammatical
259 examples may still be preferred.
264 Every message to the user should be localized (and thus be marked
265 for localization). This includes warning and error messages.
268 Don't localize/gettextify:
272 `programming_error ()'s
275 `programming_warning ()'s
281 output strings (PostScript, TeX, etc.)
286 Messages to be localised must be encapsulated in `_ (STRING)' or
287 `_f (FORMAT, ...)'. Eg:
290 warning (_ ("need music in a score"));
291 error (_f ("cannot open file: `%s'", file_name));
294 In some rare cases you may need to call `gettext ()' by hand. This
295 happens when you pre-define (a list of) string constants for later
296 use. In that case, you'll probably also need to mark these string
297 constants for translation, using `_i (STRING)'. The `_i' macro is
298 a no-op, it only serves as a marker for `xgettext'.
301 char const* messages[] = {
302 _i ("enable debugging output"),
303 _i ("ignore lilypond version"),
311 puts (gettext (messages i));
315 See also `flower/getopt-long.cc' and `lily/main.cc'.
318 Do not use leading or trailing whitespace in messages. If you need
319 whitespace to be printed, prepend or append it to the translated
323 message (Calculating line breaks... + " ");
327 Error or warning messages displayed with a file name and line
328 number never start with a capital, eg,
331 foo.ly: 12: not a duration: 3
334 Messages containing a final verb, or a gerund (`-ing'-form) always
335 start with a capital. Other (simpler) messages start with a
341 Not declaring: `foo'.
345 Avoid abbreviations or short forms, use `cannot' and `do not'
346 rather than `can't' or `don't'
347 To avoid having a number of different messages for the same
348 situation, we'll use quoting like this `"message: `%s'"' for all
349 strings. Numbers are not quoted:
352 _f ("cannot open file: `%s'", name_str)
353 _f ("cannot find character number: %d", i)
357 Think about translation issues. In a lot of cases, it is better to
358 translate a whole message. The english grammar mustn't be imposed
359 on the translator. So, instead of
362 stem at + moment.str () + does not fit in beam
368 _f ("stem at %s does not fit in beam", moment.str ())
372 Split up multi-sentence messages, whenever possible. Instead of
375 warning (_f ("out of tune! Can't find: `%s'",
377 warning (_f ("cannot find font `%s', loading default",
384 warning (out of tune:;
385 warning (_f ("cannot find: `%s', "Key_engraver"));
386 warning (_f ("cannot find font: `%s', font_name));
387 warning (_f ("Loading default font"));
391 If you must have multiple-sentence messages, use full punctuation.
392 Use two spaces after end of sentence punctuation. No punctuation
393 (esp. period) is used at the end of simple messages.
396 _f ("Non-matching braces in text `%s', adding braces", text)
397 Debug output disabled. Compiled with NPRINT.
398 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
402 Do not modularise too much; words frequently cannot be translated
403 without context. It's probably safe to treat most occurences of
404 words like stem, beam, crescendo as separately translatable words.
407 When translating, it is preferable to put interesting information
408 at the end of the message, rather than embedded in the middle.
409 This especially applies to frequently used messages, even if this
410 would mean sacrificing a bit of eloquency. This holds for original
411 messages too, of course.
414 en: cannot open: `foo.ly'
415 + nl: kan `foo.ly' niet openen (1)
416 kan niet openen: `foo.ly'* (2)
417 niet te openen: `foo.ly'* (3)
421 The first nl message, although grammatically and stylistically
422 correct, is not friendly for parsing by humans (even if they speak
423 dutch). I guess we'd prefer something like (2) or (3).
426 Do not run make po/po-update with GNU gettext < 0.10.35
432 @node Debugging LilyPond
433 @section Debugging LilyPond
435 The most commonly used tool for debugging LilyPond is the GNU debugger
436 gdb. Use of gdb is described in this section.
438 @subsection Debugging overview
440 Using a debugger simplifies troubleshooting in at least two ways.
442 First, breakpoints can be set to pause execution at any desired point.
443 Then, when execution has paused, debugger commands can be issued to
444 explore the values of various variables or to execute functions.
446 Second, the debugger allows the display of a stack trace, which shows
447 the sequence in which functions are called and the arguments to the
448 various function calls.
451 @subsection Compiling with debugging information
453 In order to use a debugger with LilyPond, it is necessary to compile
454 LilyPond with debugging information. This is accomplished by ...
456 TODO -- get good description here, or perhaps add debugging compile
457 to AU1.1 as it comes to CG and just use a reference here.
459 TODO -- Test the following to make sure it is true.
461 If you want to be able to set breakpoints in Scheme functions, it is
462 necessary to compile guile with debugging information. This is done
465 TODO -- get compiling description for guile here.
467 @subsection Typical gdb usage
469 @subsection Typical .gdbinit files
471 The behavior of gdb can be readily customized through the use of
472 .gdbinit files. The file below is from Han-Wen. It sets breakpoints
473 for all errors and defines functions for displaying scheme objects
474 (ps), grobs (pgrob), and parsed music expressions (pmusic).
477 file lily/out/lilypond
480 b Grob::programming_error
483 print ly_display_scm($arg0)
486 print ly_display_scm($arg0->self_scm_)
487 print ly_display_scm($arg0->mutable_property_alist_)
488 print ly_display_scm($arg0->immutable_property_alist_)
489 print ly_display_scm($arg0->object_alist_)
492 print ly_display_scm($arg0->self_scm_)
493 print ly_display_scm($arg0->mutable_property_alist_)
494 print ly_display_scm($arg0->immutable_property_alist_)