1 @c -*- coding: us-ascii; mode: texinfo; -*-
3 @chapter Programming work
6 * Introduction to programming::
7 * Programming without compiling::
13 @node Introduction to programming
14 @section Introduction to programming
18 @node Programming without compiling
19 @section Programming without compiling
21 Much of the development work in LilyPond takes place by changing *.ly or
22 *.scm files. These changes can be made without compiling LilyPond. Such
23 changes are described in this section.
26 @subsection Modifying distribution files
28 Mving uch of LilyPond is written in Scheme or LilyPond input files. These
29 files are interpreted when the program is run, rather than being compiled
30 when the program is built, and are present in all LilyPond distributions.
31 You will find .ly files in the ly/ directory and the Scheme files in the
32 scm/ directory. Both Scheme files and .ly files can be modified and
33 saved with any text editor. It's probably wise to make a backup copy of
34 your files before you modify them, although you can reinstall if the
35 files become corrupted.
37 Once you've modified the files, you can test the changes just by running
38 LilyPond on some input file. It's a good idea to create a file that
39 demonstrates the feature you're trying to add. This file will eventually
40 become a regression test and will be part of the LilyPond distribution.
42 @subsection Desired file formatting
44 Files that are part of the LilyPond distribution have Unix-style line
45 endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR). Make
46 sure you use the necessary tools ensure that Unix-style line endings are
47 preserved in the patches you create.
49 Tab characters should not be included in files for distribution. All
50 indentation should be done with spaces. Most editors have settings to
51 allow the setting of tab stops and ensuring that no tab characters are
54 @node Finding functions
55 @section Finding functions
57 When making changes or fixing bugs in LilyPond, one of the initial
58 challenges is finding out where in the code tree the functions to be
59 modified live. With nearly 3000 files in the source tree,
60 trial-and-error searching is generally inefective. This section describes
61 a process for finding interesting code.
63 @subsection Using the ROADMAP
65 The file ROADMAP is located in the main directory of the lilypond source.
66 ROADMAP lists all of the directories in the LilPond source tree, along
67 with a brief description of the kind of files found in each directory.
68 This can be a very helpful tool for deciding which directories to search
69 when looking for a function.
72 @subsection Using grep to search
74 Having identified a likely subdirectory to search, the grep utility can
75 be used to search for a function name. The format of the grep command is
78 grep functionName subdirectory/*
81 This command will search all the contents of the directory subdirectory/
82 and display every line in any of the files that contains functionName.
84 THe most likely directories to grep for function names are scm/ for
85 scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
89 @subsection Using git grep to search
91 If you have used git to obtain the source, you have access to a
92 powerful tool to search for functions. The command:
98 will search through all of the files that are present in the git
99 repository looking for functionName. It also presents the results
100 of the search using @code{less}, so the results are displayed one page
103 @subsection Searching on the git repository at Savannah
105 You can also use the equivalent of git grep on the Savannah server.
110 Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
113 In the pulldown box that says commit, select grep.
116 Type functionName in the search box, and hit enter/return
120 This will initiate a search of the remote git repository.
126 @c email to wl@gnu.org when I get here.
131 @subsection Handling errors
133 As a general rule, you should always try to continue computations,
134 even if there is some kind of error. When the program stops, it
135 is often very hard for a user to pinpoint what part of the input
136 causes an error. Finding the culprit is much easier if there is
137 some viewable output.
139 So functions and methods do not return errorcodes, they never
140 crash, but report a programming_error and try to carry on.
142 @subsection Languages
144 C++ and Python are preferred. Python code should use PEP 8.
146 @subsection Filenames
148 Definitions of classes that are only accessed via pointers (*) or
149 references (&) shall not be included as include files.
155 ".cc" Implementation files
156 ".icc" Inline definition files
157 ".tcc" non inline Template defs
161 (setq auto-mode-alist
162 (append '(("\\.make$" . makefile-mode)
163 ("\\.cc$" . c++-mode)
164 ("\\.icc$" . c++-mode)
165 ("\\.tcc$" . c++-mode)
166 ("\\.hh$" . c++-mode)
167 ("\\.pod$" . text-mode)
172 The class Class_name is coded in @q{class-name.*}
174 @subsection Indentation
176 Standard GNU coding style is used. In emacs:
179 (add-hook 'c++-mode-hook
180 '(lambda() (c-set-style "gnu")
184 If you like using font-lock, you can also add this to your
188 (setq font-lock-maximum-decoration t)
189 (setq c++-font-lock-keywords-3
191 c++-font-lock-keywords-3
192 '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
197 @subsection Classes and Types
206 Member variable names end with an underscore:
215 Macro names should be written in uppercase completely.
218 @subsection Broken code
220 Do not write broken code. This includes hardwired dependencies,
221 hardwired constants, slow algorithms and obvious limitations. If
222 you can not avoid it, mark the place clearly, and add a comment
223 explaining shortcomings of the code.
225 We reject broken-in-advance on principle.
232 Messages need to follow Localization.
235 @subsection Localization
237 This document provides some guidelines for programmers write user
238 messages. To help translations, user messages must follow
239 uniform conventions. Follow these rules when coding for LilyPond.
240 Hopefully, this can be replaced by general GNU guidelines in the
241 future. Even better would be to have an English (en_BR, en_AM)
242 guide helping programmers writing consistent messages for all GNU
245 Non-preferred messages are marked with `+'. By convention,
246 ungrammatical examples are marked with `*'. However, such ungrammatical
247 examples may still be preferred.
252 Every message to the user should be localized (and thus be marked
253 for localization). This includes warning and error messages.
256 Don't localize/gettextify:
260 `programming_error ()'s
263 `programming_warning ()'s
269 output strings (PostScript, TeX, etc.)
274 Messages to be localised must be encapsulated in `_ (STRING)' or
275 `_f (FORMAT, ...)'. Eg:
278 warning (_ ("need music in a score"));
279 error (_f ("cannot open file: `%s'", file_name));
282 In some rare cases you may need to call `gettext ()' by hand. This
283 happens when you pre-define (a list of) string constants for later
284 use. In that case, you'll probably also need to mark these string
285 constants for translation, using `_i (STRING)'. The `_i' macro is
286 a no-op, it only serves as a marker for `xgettext'.
289 char const* messages[] = {
290 _i ("enable debugging output"),
291 _i ("ignore lilypond version"),
299 puts (gettext (messages i));
303 See also `flower/getopt-long.cc' and `lily/main.cc'.
306 Do not use leading or trailing whitespace in messages. If you need
307 whitespace to be printed, prepend or append it to the translated
311 message (Calculating line breaks... + " ");
315 Error or warning messages displayed with a file name and line
316 number never start with a capital, eg,
319 foo.ly: 12: not a duration: 3
322 Messages containing a final verb, or a gerund (`-ing'-form) always
323 start with a capital. Other (simpler) messages start with a
329 Not declaring: `foo'.
333 Avoid abbreviations or short forms, use `cannot' and `do not'
334 rather than `can't' or `don't'
335 To avoid having a number of different messages for the same
336 situation, we'll use quoting like this `"message: `%s'"' for all
337 strings. Numbers are not quoted:
340 _f ("cannot open file: `%s'", name_str)
341 _f ("cannot find character number: %d", i)
345 Think about translation issues. In a lot of cases, it is better to
346 translate a whole message. The english grammar mustn't be imposed
347 on the translator. So, instead of
350 stem at + moment.str () + does not fit in beam
356 _f ("stem at %s does not fit in beam", moment.str ())
360 Split up multi-sentence messages, whenever possible. Instead of
363 warning (_f ("out of tune! Can't find: `%s'",
365 warning (_f ("cannot find font `%s', loading default",
372 warning (out of tune:;
373 warning (_f ("cannot find: `%s', "Key_engraver"));
374 warning (_f ("cannot find font: `%s', font_name));
375 warning (_f ("Loading default font"));
379 If you must have multiple-sentence messages, use full punctuation.
380 Use two spaces after end of sentence punctuation. No punctuation
381 (esp. period) is used at the end of simple messages.
384 _f ("Non-matching braces in text `%s', adding braces", text)
385 Debug output disabled. Compiled with NPRINT.
386 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
390 Do not modularise too much; words frequently cannot be translated
391 without context. It's probably safe to treat most occurences of
392 words like stem, beam, crescendo as separately translatable words.
395 When translating, it is preferable to put interesting information
396 at the end of the message, rather than embedded in the middle.
397 This especially applies to frequently used messages, even if this
398 would mean sacrificing a bit of eloquency. This holds for original
399 messages too, of course.
402 en: cannot open: `foo.ly'
403 + nl: kan `foo.ly' niet openen (1)
404 kan niet openen: `foo.ly'* (2)
405 niet te openen: `foo.ly'* (3)
409 The first nl message, although grammatically and stylistically
410 correct, is not friendly for parsing by humans (even if they speak
411 dutch). I guess we'd prefer something like (2) or (3).
414 Do not run make po/po-update with GNU gettext < 0.10.35