1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
12 @node Working on LilyPond projects
13 @chapter Working on LilyPond projects
15 This section explains how to solve or avoid certain common
16 problems. If you have programming experience, many of these
17 tips may seem obvious, but it is still advisable to read
22 * When things don't work::
23 * Make and Makefiles::
27 @node When things don't work
28 @section When things don't work
31 * Updating old input files::
33 * Troubleshooting (taking it all apart)::
37 @node Updating old input files
38 @subsection Updating old input files
41 @cindex updating old input files
43 The LilyPond input syntax occasionally changes. As LilyPond itself
44 improves, the syntax (input language) is modified accordingly. Sometimes
45 these changes are made to make the input easier to read and write or
46 sometimes the changes are made to accommodate new features of LilyPond.
48 LilyPond comes with a file that makes this updating easier:
49 @code{convert-ly}. For details about how to run this program, see
50 @rprogram{Updating files with convert-ly}.
52 Unfortunately, @code{convert-ly} cannot handle all input changes. It
53 takes care of simple search-and-replace changes (such as @code{raggedright}
54 becoming @code{ragged-right}), but some changes are too
55 complicated. The syntax changes that @code{convert-ly} cannot handle
56 are listed in @rprogram{Updating files with convert-ly}.
58 For example, in LilyPond 2.4 and earlier, accents and non-English
59 letters were entered using LaTeX -- for example,
60 @code{No\"el} (this would print the French word for
61 @c keep "-matching straight in fancy editors
62 @q{Christmas}). In LilyPond 2.6 and above, the special
63 @code{ë} must be entered directly into the LilyPond file as an
64 UTF-8 character. @code{convert-ly} cannot change all the LaTeX
65 special characters into UTF-8 characters; you must manually update
66 your old LilyPond input files.
69 @subsection Common errors
71 The error conditions described below occur often, yet the cause
72 is not obvious or easily found. Once seen and understood, they
77 * Music runs off the page::
78 * An extra staff appears::
79 * Apparent error in ../ly/init.ly::
80 * Error message Unbound variable %::
81 * Error message FT_Get_Glyph_Name::
84 @node Music runs off the page
85 @unnumberedsubsubsec Music runs off the page
87 Music running off the page over the right margin or appearing
88 unduly compressed is almost always due to entering an incorrect
89 duration on a note, causing the final note in a measure to extend
90 over the bar line. It is not invalid if the final note in a
91 measure does not end on the automatically entered bar line, as the
92 note is simply assumed to carry over into the next measure. But
93 if a long sequence of such carry-over measures occurs the music
94 can appear compressed or may flow off the page because automatic
95 line breaks can be inserted only at the end of complete measures,
96 i.e., where all notes end before or at the end of the measure.
98 @warning{An incorrect duration can cause line breaks to be
99 inhibited, leading to a line of highly compressed music or
100 music which flows off the page.}
102 The incorrect duration can be found easily if bar checks are used,
103 see @ruser{Bar and bar number checks}.
105 If you actually intend to have a series of such carry-over measures
106 you will need to insert an invisible bar line where you want the
107 line to break. For details, see @ruser{Bar lines}.
110 @node An extra staff appears
111 @unnumberedsubsubsec An extra staff appears
113 If contexts are not created explicitly with @code{\new} they will be
114 silently created as soon as a command is encountered which cannot
115 be applied to an existing context. In simple scores the automatic
116 creation of contexts is useful, and most of the examples in the
117 LilyPond manuals take advantage of this simplification. But
118 occasionally the silent creation of contexts can give rise to
119 unexpected new staves or scores. For example, it might be expected
120 that the following code would cause all note heads within the
121 following staff to be colored red, but in fact it results in two
122 staves with the note heads remaining the default black in the lower
125 @lilypond[quote,verbatim,relative=2]
126 \override Staff.NoteHead #'color = #red
130 This is because a @code{Staff} context does not exist when the
131 override is processed, so one is implicitly created and the override
132 is applied to it, but then the @code{\new Staff} command creates
133 another, separate, staff into which the notes are placed. The
134 correct code to color all note heads red is
136 @lilypond[quote,verbatim,relative=2]
138 \override Staff.NoteHead #'color = #red
143 As a second example, if a @code{\relative} command is placed inside
144 a @code{\repeat} command two staves result, the second offset from
145 the first, because the @code{\repeat} command generates two
146 @code{\relative} blocks, which each implicitly create @code{Staff}
147 and @code{Voice} blocks.
149 @lilypond[quote,verbatim]
150 \repeat unfold 2 \relative { c d e f }
153 The correct way is to reverse the @code{\repeat} and
154 @code{\relative} commands, like this:
156 @lilypond[quote,verbatim]
158 \repeat unfold 2 { c d e f }
163 @node Apparent error in ../ly/init.ly
164 @unnumberedsubsubsec Apparent error in @code{../ly/init.ly}
166 Various obscure error messages may appear about syntax errors in
167 @code{../ly/init.ly} if the input file is not correctly formed,
168 for example, if it does not contain correctly
169 matched braces or quote signs.
171 The most common error is a missing brace, (@code{@}}), at the end of
172 a @code{score} block. Here the solution is obvious: check the
173 @code{score} block is correctly terminated. The correct structure
174 of an input file is described in @rlearning{How LilyPond input files work}.
175 Using an editor which automatically highlights matching brackets and
176 braces is helpful to avoid such errors.
178 A second common cause is no white space between the last syllable
179 of a lyrics block and the terminating brace, (@code{@}}). Without
180 this separation the brace is taken to be part of the syllable. It
181 is always advisable to ensure there is white space before and after
182 @emph{every} brace. For the importance of this when using lyrics,
183 see @ruser{Lyrics explained}.
185 This error message can also appear if a terminating quote sign,
186 (@code{"}), is omitted. In this case an accompanying error message
187 @c keep "-matching straight in fancy editors
188 should give a line number close to the line in error. The
189 mismatched quote will usually be on the line one or two above.
191 @node Error message Unbound variable %
192 @unnumberedsubsubsec Error message Unbound variable %
194 This error message will appear at the bottom of the console
195 output or log file together with a @qq{GUILE signalled an error ...}
196 message every time a Scheme routine is called which (invalidly)
197 contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
199 LilyPond comments begin with a percent sign, (@code{%}), and must
200 not be used within Scheme routines. Scheme comments begin with a
201 semi-colon, (@code{;}).
203 @node Error message FT_Get_Glyph_Name
204 @unnumberedsubsubsec Error message FT_Get_Glyph_Name
206 This error messages appears in the console output or log file if
207 an input file contains a non-ASCII character and was not saved in
208 UTF-8 encoding. For details, see @ruser{Text encoding}.
210 @node Troubleshooting (taking it all apart)
211 @subsection Troubleshooting (taking it all apart)
213 Sooner or later, you will write a file that LilyPond cannot
214 compile. The messages that LilyPond gives may help
215 you find the error, but in many cases you need to do some
216 investigation to determine the source of the problem.
218 The most powerful tools for this purpose are the
219 single line comment (indicated by @code{%}) and the block
220 comment (indicated by @code{%@{ ... %@}}). If you don't
221 know where a problem is, start commenting out huge portions
222 of your input file. After you comment out a section, try
223 compiling the file again. If it works, then the problem
224 must exist in the portion you just commented. If it doesn't
225 work, then keep on commenting out material until you have
226 something that works.
228 In an extreme case, you might end up with only
242 (in other words, a file without any music)
244 If that happens, don't give up. Uncomment a bit -- say,
245 the bass part -- and see if it works. If it doesn't work,
246 then comment out all of the bass music (but leave
247 @code{\bass} in the @code{\score} uncommented.
250 bass = \relative c' @{
258 Now start slowly uncommenting more and more of the
259 @code{bass} part until you find the problem line.
261 Another very useful debugging technique is constructing
262 FIXME FIXME @c @ref{Minimal examples}.
265 @node Minimal examples
266 @subsection Minimal examples
268 A minimal example is an example which is as small as possible. These
269 examples are much easier to understand than long examples. Minimal
270 examples are used for
274 @item Sending a help request to mailing lists
275 @item Adding an example to the @uref{http://lsr.dsi.unimi.it/,
276 LilyPond Snippet Repository}
279 To construct an example which is as small as possible, the rule is
280 quite simple: remove anything which is not necessary. When trying to
281 remove unnecessary parts of a file, it is a very good idea to comment
282 out lines instead of deleting them. That way, if you discover that you
283 actually @emph{do} need some lines, you can uncomment them, instead of
284 typing them in from scratch.
286 There are two exceptions to the @qq{as small as possible} rule:
289 @item Include the @code{\version} number.
290 @item If possible, use @code{\paper@{ ragged-right=##t @}} at the
294 The whole point of a minimal example is to make it easy to read:
297 @item Avoid using complicated notes, keys, or time signatures, unless you
298 wish to demonstrate something is about the behavior of those items.
299 @item Do not use @code{\override} commands unless that is the point of the
305 @node Make and Makefiles
306 @section Make and Makefiles
311 Pretty well all the platforms Lilypond can run on support a software
312 facility called @code{make}. This software reads a special file called a
313 @code{Makefile} that defines what files depend on what others and what
314 commands you need to give the operating system to produce one file from
315 another. For example the makefile would spell out how to produce
316 @code{ballad.pdf} and @code{ballad.midi} from @code{ballad.ly} by
319 There are times when it is a good idea to create a @code{Makefile}
320 for your project, either for your own convenience or
321 as a courtesy to others who might have access to your source files.
322 This is true for very large projects with many included files and
323 different output options (e.g. full score, parts, conductor's
324 score, piano reduction, etc.), or for projects that
325 require difficult commands to build them (such as
326 @code{lilypond-book} projects). Makefiles vary greatly in
327 complexity and flexibility, according to the needs and skills of
328 the authors. The program GNU Make comes installed on GNU/Linux
329 distributions and on MacOS X, and it is also available for Windows.
331 See the @strong{GNU Make Manual} for full details on using
332 @code{make}, as what follows here gives only a glimpse of what it
335 The commands to define rules in a makefile differ
336 according to platform; for instance the various forms of Linux and
337 MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on
338 MacOS X, you need to configure the system to use the command-line
339 intepreter. Here are some example makefiles, with versions for both
340 Linux/MacOS and Windows.
342 The first example is for an orchestral work in four
343 movements with a directory structure as follows:
360 | |-- symphony-cello.ly
361 | |-- symphony-horn.ly
362 | |-- symphony-oboes.ly
363 | |-- symphony-viola.ly
364 | |-- symphony-violinOne.ly
365 | `-- symphony-violinTwo.ly
375 The @code{.ly} files in the @code{Scores} and
376 @code{Parts} directories get their notes from @code{.ily}
377 files in the @code{Notes} directory:
380 %%% top of file "symphony-cello.ly"
381 \include ../definitions.ily
382 \include ../Notes/cello.ily
385 The makefile will have targets of @code{score} (entire piece in
386 full score), @code{movements} (individual movements in full score),
387 and @code{parts} (individual parts for performers). There
388 is also a target @code{archive} that will create a tarball of
389 the source files, suitable for sharing via web or email. Here is
390 the makefile for GNU/Linux or MacOS X. It should be saved with the
391 name @code{Makefile} in the top directory of the project:
393 @warning{When a target or pattern rule is defined, the
394 subsequent lines must begin with tabs, not spaces.}
397 # the name stem of the output files
399 # determine how many processors are present
400 CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
401 # The command to run lilypond
402 LILY_CMD = lilypond -ddelete-intermediate-files \
403 -dno-point-and-click -djob-count=$(CPU_CORES)
405 # The suffixes used in this Makefile.
406 .SUFFIXES: .ly .ily .pdf .midi
408 # Input and output files are searched in the directories listed in
409 # the VPATH variable. All of them are subdirectories of the current
410 # directory (given by the GNU make variable `CURDIR').
417 # The pattern rule to create PDF and MIDI files from a LY input file.
418 # The .pdf output files are put into the `PDF' subdirectory, and the
419 # .midi files go into the `MIDI' subdirectory.
421 $(LILY_CMD) $<; \ # this line begins with a tab
422 if test -f "$*.pdf"; then \
425 if test -f "$*.midi"; then \
426 mv "$*.midi" MIDI/; \
437 # The dependencies of the movements.
438 $(piece)I.pdf: $(piece)I.ly $(notes)
439 $(piece)II.pdf: $(piece)II.ly $(notes)
440 $(piece)III.pdf: $(piece)III.ly $(notes)
441 $(piece)IV.pdf: $(piece)IV.ly $(notes)
443 # The dependencies of the full score.
444 $(piece).pdf: $(piece).ly $(notes)
446 # The dependencies of the parts.
447 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
448 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
449 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
450 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
451 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
452 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
454 # Type `make score' to generate the full score of all four
455 # movements as one file.
459 # Type `make parts' to generate all parts.
460 # Type `make foo.pdf' to generate the part for instrument `foo'.
461 # Example: `make symphony-cello.pdf'.
463 parts: $(piece)-cello.pdf \
464 $(piece)-violinOne.pdf \
465 $(piece)-violinTwo.pdf \
470 # Type `make movements' to generate files for the
471 # four movements separately.
473 movements: $(piece)I.pdf \
478 all: score parts movements
481 tar -cvvf stamitz.tar \ # this line begins with a tab
482 --exclude=*pdf --exclude=*~ \
483 --exclude=*midi --exclude=*.tar \
488 There are special complications on the Windows platform. After
489 downloading and installing GNU Make for Windows, you must set the
490 correct path in the system's environment variables so that the
491 DOS shell can find the Make program. To do this, right-click on
492 "My Computer," then choose @code{Properties} and
493 @code{Advanced}. Click @code{Environment Variables}, and then
494 in the @code{System Variables} pane, highlight @code{Path}, click
495 @code{edit}, and add the path to the GNU Make executable file, which
496 will look something like this:
499 C:\Program Files\GnuWin32\bin
502 The makefile itself has to be altered to handle different shell
503 commands and to deal with spaces that are present
504 in some default system directories. The @code{archive} target
505 is eliminated since Windows does not have the @code{tar} command,
506 and Windows also has a different default extension for midi files.
513 LILY_CMD = lilypond -ddelete-intermediate-files \
514 -dno-point-and-click \
515 -djob-count=$(NUMBER_OF_PROCESSORS)
517 #get the 8.3 name of CURDIR (workaround for spaces in PATH)
518 workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
521 .SUFFIXES: .ly .ily .pdf .mid
530 $(LILY_CMD) $< # this line begins with a tab
531 if exist "$*.pdf" move /Y "$*.pdf" PDF/ # begin with tab
532 if exist "$*.mid" move /Y "$*.mid" MIDI/ # begin with tab
544 $(piece)I.pdf: $(piece)I.ly $(notes)
545 $(piece)II.pdf: $(piece)II.ly $(notes)
546 $(piece)III.pdf: $(piece)III.ly $(notes)
547 $(piece)IV.pdf: $(piece)IV.ly $(notes)
549 $(piece).pdf: $(piece).ly $(notes)
551 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
552 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
553 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
554 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
555 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
556 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
562 parts: $(piece)-cello.pdf \
563 $(piece)-violinOne.pdf \
564 $(piece)-violinTwo.pdf \
570 movements: $(piece)I.pdf \
575 all: score parts movements
579 The next Makefile is for a @command{lilypond-book} document done in
580 LaTeX. This project has an index, which requires that the
581 @command{latex} command be run twice to update links. Output files are
582 all stored in the @code{out} directory for .pdf output and in the
583 @code{htmlout} directory for the html output.
592 LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
593 LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
594 PDF=cd $(OUTDIR) && pdflatex $(FILE)
595 HTML=cd $(WEBDIR) && latex2html $(FILE)
596 INDEX=cd $(OUTDIR) && makeindex $(FILE)
597 PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &
602 $(LILYBOOK_PDF) # begin with tab
603 $(PDF) # begin with tab
604 $(INDEX) # begin with tab
605 $(PDF) # begin with tab
606 $(PREVIEW) # begin with tab
609 $(LILYBOOK_HTML) # begin with tab
610 $(HTML) # begin with tab
611 cp -R $(WEBDIR)/$(FILE)/ ./ # begin with tab
612 $(BROWSER) $(FILE)/$(FILE).html & # begin with tab
615 cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf # begin with tab
618 rm -rf $(OUTDIR) # begin with tab
621 rm -rf $(WEBDIR) # begin with tab
624 tar -cvvf myproject.tar \ # begin this line with tab
626 --exclude=htmlout/* \
627 --exclude=myproject/* \
634 TODO: make this thing work on Windows
636 The previous makefile does not work on Windows. An alternative
637 for Windows users would be to create a simple batch file
638 containing the build commands. This will not
639 keep track of dependencies the way a makefile does, but it at
640 least reduces the build process to a single command. Save the
641 following code as @command{build.bat} or @command{build.cmd}.
642 The batch file can be run at the DOS prompt or by simply
643 double-clicking its icon.
646 lilypond-book --output=out --pdf myproject.lytex
652 copy out\myproject.pdf MyProject.pdf
659 @c @rprogram{Setup for MacOS X},
660 @rprogram{Command-line usage},
661 @rprogram{lilypond-book}