1 @c -*- coding: us-ascii; mode: texinfo; -*-
3 @chapter Programming work
6 * Introduction to programming::
7 * Programming without compiling::
10 * 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 crash course}.
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
72 be modified live. With nearly 3000 files in the source tree,
73 trial-and-error searching is generally ineffective. This section
74 describes 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 -i 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
96 functionName. The @code{-i} option makes @command{grep} ignore
97 case -- this can be very useful if you are not yet familiar with
98 our capitalization conventions.
100 The most likely directories to grep for function names are scm/ for
101 scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
105 @subsection Using git grep to search
107 If you have used git to obtain the source, you have access to a
108 powerful tool to search for functions. The command:
111 git grep functionName
114 will search through all of the files that are present in the git
115 repository looking for functionName. It also presents the results
116 of the search using @code{less}, so the results are displayed one page
119 @subsection Searching on the git repository at Savannah
121 You can also use the equivalent of git grep on the Savannah server.
126 Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
129 In the pulldown box that says commit, select grep.
132 Type functionName in the search box, and hit enter/return
136 This will initiate a search of the remote git repository.
141 @c email to wl@gnu.org when I get here.
146 @subsection Handling errors
148 As a general rule, you should always try to continue computations,
149 even if there is some kind of error. When the program stops, it
150 is often very hard for a user to pinpoint what part of the input
151 causes an error. Finding the culprit is much easier if there is
152 some viewable output.
154 So functions and methods do not return errorcodes, they never
155 crash, but report a programming_error and try to carry on.
157 @subsection Languages
159 C++ and Python are preferred. Python code should use PEP 8.
161 @subsection Filenames
163 Definitions of classes that are only accessed via pointers (*) or
164 references (&) shall not be included as include files.
170 ".cc" Implementation files
171 ".icc" Inline definition files
172 ".tcc" non inline Template defs
176 (setq auto-mode-alist
177 (append '(("\\.make$" . makefile-mode)
178 ("\\.cc$" . c++-mode)
179 ("\\.icc$" . c++-mode)
180 ("\\.tcc$" . c++-mode)
181 ("\\.hh$" . c++-mode)
182 ("\\.pod$" . text-mode)
187 The class Class_name is coded in @q{class-name.*}
189 @subsection Indentation
191 Standard GNU coding style is used. In emacs:
194 (add-hook 'c++-mode-hook
195 '(lambda() (c-set-style "gnu")
199 If you like using font-lock, you can also add this to your
203 (setq font-lock-maximum-decoration t)
204 (setq c++-font-lock-keywords-3
206 c++-font-lock-keywords-3
207 '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
212 @subsection Classes and Types
221 Member variable names end with an underscore:
230 Macro names should be written in uppercase completely.
233 @subsection Broken code
235 Do not write broken code. This includes hardwired dependencies,
236 hardwired constants, slow algorithms and obvious limitations. If
237 you can not avoid it, mark the place clearly, and add a comment
238 explaining shortcomings of the code.
240 We reject broken-in-advance on principle.
247 Messages need to follow Localization.
250 @subsection Localization
252 This document provides some guidelines for programmers write user
253 messages. To help translations, user messages must follow
254 uniform conventions. Follow these rules when coding for LilyPond.
255 Hopefully, this can be replaced by general GNU guidelines in the
256 future. Even better would be to have an English (en_BR, en_AM)
257 guide helping programmers writing consistent messages for all GNU
260 Non-preferred messages are marked with `+'. By convention,
261 ungrammatical examples are marked with `*'. However, such ungrammatical
262 examples may still be preferred.
267 Every message to the user should be localized (and thus be marked
268 for localization). This includes warning and error messages.
271 Don't localize/gettextify:
275 `programming_error ()'s
278 `programming_warning ()'s
284 output strings (PostScript, TeX, etc.)
289 Messages to be localised must be encapsulated in `_ (STRING)' or
290 `_f (FORMAT, ...)'. E.g.:
293 warning (_ ("need music in a score"));
294 error (_f ("cannot open file: `%s'", file_name));
297 In some rare cases you may need to call `gettext ()' by hand. This
298 happens when you pre-define (a list of) string constants for later
299 use. In that case, you'll probably also need to mark these string
300 constants for translation, using `_i (STRING)'. The `_i' macro is
301 a no-op, it only serves as a marker for `xgettext'.
304 char const* messages[] = {
305 _i ("enable debugging output"),
306 _i ("ignore lilypond version"),
313 puts (gettext (messages i));
317 See also `flower/getopt-long.cc' and `lily/main.cc'.
320 Do not use leading or trailing whitespace in messages. If you need
321 whitespace to be printed, prepend or append it to the translated
325 message ("Calculating line breaks..." + " ");
329 Error or warning messages displayed with a file name and line
330 number never start with a capital, eg,
333 foo.ly: 12: not a duration: 3
336 Messages containing a final verb, or a gerund (`-ing'-form) always
337 start with a capital. Other (simpler) messages start with a
343 Not declaring: `foo'.
347 Avoid abbreviations or short forms, use `cannot' and `do not'
348 rather than `can't' or `don't'
349 To avoid having a number of different messages for the same
350 situation, we'll use quoting like this `"message: `%s'"' for all
351 strings. Numbers are not quoted:
354 _f ("cannot open file: `%s'", name_str)
355 _f ("cannot find character number: %d", i)
359 Think about translation issues. In a lot of cases, it is better to
360 translate a whole message. The english grammar mustn't be imposed
361 on the translator. So, instead of
364 stem at + moment.str () + does not fit in beam
370 _f ("stem at %s does not fit in beam", moment.str ())
374 Split up multi-sentence messages, whenever possible. Instead of
377 warning (_f ("out of tune! Can't find: `%s'", "Key_engraver"));
378 warning (_f ("cannot find font `%s', loading default", font_name));
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_)
505 Copied from an email from Carl. Maybe already included.
507 - how to use a debugger with lilypond.
509 - how to get lilypond running and pause at a guile prompt
511 - brief overview of how lilypond processes a file.