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)::
36 @node Updating old input files
37 @subsection Updating old input files
40 @cindex updating old input files
42 The LilyPond input syntax occasionally changes. As LilyPond itself
43 improves, the syntax (input language) is modified accordingly. Sometimes
44 these changes are made to make the input easier to read and write or
45 sometimes the changes are made to accommodate new features of LilyPond.
47 LilyPond comes with a file that makes this updating easier:
48 @code{convert-ly}. For details about how to run this program, see
49 @rprogram{Updating files with convert-ly}.
51 Unfortunately, @code{convert-ly} cannot handle all input changes. It
52 takes care of simple search-and-replace changes (such as @code{raggedright}
53 becoming @code{ragged-right}), but some changes are too
54 complicated. The syntax changes that @code{convert-ly} cannot handle
55 are listed in @rprogram{Updating files with convert-ly}.
57 For example, in LilyPond 2.4 and earlier, accents and non-English
58 letters were entered using LaTeX -- for example,
59 @code{No\"el} (this would print the French word for
60 @c keep "-matching straight in fancy editors
61 @q{Christmas}). In LilyPond 2.6 and above, the special
62 @code{ë} must be entered directly into the LilyPond file as an
63 UTF-8 character. @code{convert-ly} cannot change all the LaTeX
64 special characters into UTF-8 characters; you must manually update
65 your old LilyPond input files.
68 @subsection Common errors
70 The error conditions described below occur often, yet the cause
71 is not obvious or easily found. Once seen and understood, they
76 * Music runs off the page::
77 * An extra staff appears::
78 * Apparent error in ../ly/init.ly::
79 * Error message Unbound variable %::
80 * Error message FT_Get_Glyph_Name::
83 @node Music runs off the page
84 @unnumberedsubsubsec Music runs off the page
86 Music running off the page over the right margin or appearing
87 unduly compressed is almost always due to entering an incorrect
88 duration on a note, causing the final note in a measure to extend
89 over the bar line. It is not invalid if the final note in a
90 measure does not end on the automatically entered bar line, as the
91 note is simply assumed to carry over into the next measure. But
92 if a long sequence of such carry-over measures occurs the music
93 can appear compressed or may flow off the page because automatic
94 line breaks can be inserted only at the end of complete measures,
95 i.e., where all notes end before or at the end of the measure.
97 @warning{An incorrect duration can cause line breaks to be
98 inhibited, leading to a line of highly compressed music or
99 music which flows off the page.}
101 The incorrect duration can be found easily if bar checks are used,
102 see @ruser{Bar and bar number checks}.
104 If you actually intend to have a series of such carry-over measures
105 you will need to insert an invisible bar line where you want the
106 line to break. For details, see @ruser{Bar lines}.
109 @node An extra staff appears
110 @unnumberedsubsubsec An extra staff appears
112 If contexts are not created explicitly with @code{\new} they will be
113 silently created as soon as a command is encountered which cannot
114 be applied to an existing context. In simple scores the automatic
115 creation of contexts is useful, and most of the examples in the
116 LilyPond manuals take advantage of this simplification. But
117 occasionally the silent creation of contexts can give rise to
118 unexpected new staves or scores. For example, it might be expected
119 that the following code would cause all note heads within the
120 following staff to be colored red, but in fact it results in two
121 staves with the note heads remaining the default black in the lower
124 @lilypond[quote,verbatim,relative=2]
125 \override Staff.NoteHead #'color = #red
129 This is because a @code{Staff} context does not exist when the
130 override is processed, so one is implicitly created and the override
131 is applied to it, but then the @code{\new Staff} command creates
132 another, separate, staff into which the notes are placed. The
133 correct code to color all note heads red is
135 @lilypond[quote,verbatim,relative=2]
137 \override Staff.NoteHead #'color = #red
142 As a second example, if a @code{\relative} command is placed inside
143 a @code{\repeat} command two staves result, the second offset from
144 the first, because the @code{\repeat} command generates two
145 @code{\relative} blocks, which each implicitly create @code{Staff}
146 and @code{Voice} blocks.
148 @lilypond[quote,verbatim]
149 \repeat unfold 2 \relative { c d e f }
152 The correct way is to reverse the @code{\repeat} and
153 @code{\relative} commands, like this:
155 @lilypond[quote,verbatim]
157 \repeat unfold 2 { c d e f }
162 @node Apparent error in ../ly/init.ly
163 @unnumberedsubsubsec Apparent error in @code{../ly/init.ly}
165 Various obscure error messages may appear about syntax errors in
166 @code{../ly/init.ly} if the input file is not correctly formed,
167 for example, if it does not contain correctly
168 matched braces or quote signs.
170 The most common error is a missing brace, (@code{@}}), at the end of
171 a @code{score} block. Here the solution is obvious: check the
172 @code{score} block is correctly terminated. The correct structure
173 of an input file is described in @rlearning{How LilyPond input files work}.
174 Using an editor which automatically highlights matching brackets and
175 braces is helpful to avoid such errors.
177 A second common cause is no white space between the last syllable
178 of a lyrics block and the terminating brace, (@code{@}}). Without
179 this separation the brace is taken to be part of the syllable. It
180 is always advisable to ensure there is white space before and after
181 @emph{every} brace. For the importance of this when using lyrics,
182 see @ruser{Lyrics explained}.
184 This error message can also appear if a terminating quote sign,
185 (@code{"}), is omitted. In this case an accompanying error message
186 @c keep "-matching straight in fancy editors
187 should give a line number close to the line in error. The
188 mismatched quote will usually be on the line one or two above.
190 @node Error message Unbound variable %
191 @unnumberedsubsubsec Error message Unbound variable %
193 This error message will appear at the bottom of the console
194 output or log file together with a @qq{GUILE signalled an error ...}
195 message every time a Scheme routine is called which (invalidly)
196 contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
198 LilyPond comments begin with a percent sign, (@code{%}), and must
199 not be used within Scheme routines. Scheme comments begin with a
200 semi-colon, (@code{;}).
202 @node Error message FT_Get_Glyph_Name
203 @unnumberedsubsubsec Error message FT_Get_Glyph_Name
205 This error messages appears in the console output or log file if
206 an input file contains a non-ASCII character and was not saved in
207 UTF-8 encoding. For details, see @ruser{Text encoding}.
209 @node Troubleshooting (taking it all apart)
210 @subsection Troubleshooting (taking it all apart)
212 Sooner or later, you will write a file that LilyPond cannot
213 compile. The messages that LilyPond gives may help
214 you find the error, but in many cases you need to do some
215 investigation to determine the source of the problem.
217 The most powerful tools for this purpose are the
218 single line comment (indicated by @code{%}) and the block
219 comment (indicated by @code{%@{ ... %@}}). If you don't
220 know where a problem is, start commenting out huge portions
221 of your input file. After you comment out a section, try
222 compiling the file again. If it works, then the problem
223 must exist in the portion you just commented. If it doesn't
224 work, then keep on commenting out material until you have
225 something that works.
227 In an extreme case, you might end up with only
241 (in other words, a file without any music)
243 If that happens, don't give up. Uncomment a bit -- say,
244 the bass part -- and see if it works. If it doesn't work,
245 then comment out all of the bass music (but leave
246 @code{\bass} in the @code{\score} uncommented.
249 bass = \relative c' @{
257 Now start slowly uncommenting more and more of the
258 @code{bass} part until you find the problem line.
260 Another very useful debugging technique is constructing
261 @rgeneral{Tiny examples}.
264 @node Make and Makefiles
265 @section Make and Makefiles
270 Pretty well all the platforms Lilypond can run on support a software
271 facility called @code{make}. This software reads a special file called a
272 @code{Makefile} that defines what files depend on what others and what
273 commands you need to give the operating system to produce one file from
274 another. For example the makefile would spell out how to produce
275 @code{ballad.pdf} and @code{ballad.midi} from @code{ballad.ly} by
278 There are times when it is a good idea to create a @code{Makefile}
279 for your project, either for your own convenience or
280 as a courtesy to others who might have access to your source files.
281 This is true for very large projects with many included files and
282 different output options (e.g. full score, parts, conductor's
283 score, piano reduction, etc.), or for projects that
284 require difficult commands to build them (such as
285 @code{lilypond-book} projects). Makefiles vary greatly in
286 complexity and flexibility, according to the needs and skills of
287 the authors. The program GNU Make comes installed on GNU/Linux
288 distributions and on MacOS X, and it is also available for Windows.
290 See the @strong{GNU Make Manual} for full details on using
291 @code{make}, as what follows here gives only a glimpse of what it
294 The commands to define rules in a makefile differ
295 according to platform; for instance the various forms of Linux and
296 MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on
297 MacOS X, you need to configure the system to use the command-line
298 intepreter. Here are some example makefiles, with versions for both
299 Linux/MacOS and Windows.
301 The first example is for an orchestral work in four
302 movements with a directory structure as follows:
319 | |-- symphony-cello.ly
320 | |-- symphony-horn.ly
321 | |-- symphony-oboes.ly
322 | |-- symphony-viola.ly
323 | |-- symphony-violinOne.ly
324 | `-- symphony-violinTwo.ly
334 The @code{.ly} files in the @code{Scores} and
335 @code{Parts} directories get their notes from @code{.ily}
336 files in the @code{Notes} directory:
339 %%% top of file "symphony-cello.ly"
340 \include ../definitions.ily
341 \include ../Notes/cello.ily
344 The makefile will have targets of @code{score} (entire piece in
345 full score), @code{movements} (individual movements in full score),
346 and @code{parts} (individual parts for performers). There
347 is also a target @code{archive} that will create a tarball of
348 the source files, suitable for sharing via web or email. Here is
349 the makefile for GNU/Linux or MacOS X. It should be saved with the
350 name @code{Makefile} in the top directory of the project:
352 @warning{When a target or pattern rule is defined, the
353 subsequent lines must begin with tabs, not spaces.}
356 # the name stem of the output files
358 # determine how many processors are present
359 CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
360 # The command to run lilypond
361 LILY_CMD = lilypond -ddelete-intermediate-files \
362 -dno-point-and-click -djob-count=$(CPU_CORES)
364 # The suffixes used in this Makefile.
365 .SUFFIXES: .ly .ily .pdf .midi
367 # Input and output files are searched in the directories listed in
368 # the VPATH variable. All of them are subdirectories of the current
369 # directory (given by the GNU make variable `CURDIR').
376 # The pattern rule to create PDF and MIDI files from a LY input file.
377 # The .pdf output files are put into the `PDF' subdirectory, and the
378 # .midi files go into the `MIDI' subdirectory.
380 $(LILY_CMD) $<; \ # this line begins with a tab
381 if test -f "$*.pdf"; then \
384 if test -f "$*.midi"; then \
385 mv "$*.midi" MIDI/; \
396 # The dependencies of the movements.
397 $(piece)I.pdf: $(piece)I.ly $(notes)
398 $(piece)II.pdf: $(piece)II.ly $(notes)
399 $(piece)III.pdf: $(piece)III.ly $(notes)
400 $(piece)IV.pdf: $(piece)IV.ly $(notes)
402 # The dependencies of the full score.
403 $(piece).pdf: $(piece).ly $(notes)
405 # The dependencies of the parts.
406 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
407 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
408 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
409 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
410 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
411 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
413 # Type `make score' to generate the full score of all four
414 # movements as one file.
418 # Type `make parts' to generate all parts.
419 # Type `make foo.pdf' to generate the part for instrument `foo'.
420 # Example: `make symphony-cello.pdf'.
422 parts: $(piece)-cello.pdf \
423 $(piece)-violinOne.pdf \
424 $(piece)-violinTwo.pdf \
429 # Type `make movements' to generate files for the
430 # four movements separately.
432 movements: $(piece)I.pdf \
437 all: score parts movements
440 tar -cvvf stamitz.tar \ # this line begins with a tab
441 --exclude=*pdf --exclude=*~ \
442 --exclude=*midi --exclude=*.tar \
447 There are special complications on the Windows platform. After
448 downloading and installing GNU Make for Windows, you must set the
449 correct path in the system's environment variables so that the
450 DOS shell can find the Make program. To do this, right-click on
451 "My Computer," then choose @code{Properties} and
452 @code{Advanced}. Click @code{Environment Variables}, and then
453 in the @code{System Variables} pane, highlight @code{Path}, click
454 @code{edit}, and add the path to the GNU Make executable file, which
455 will look something like this:
458 C:\Program Files\GnuWin32\bin
461 The makefile itself has to be altered to handle different shell
462 commands and to deal with spaces that are present
463 in some default system directories. The @code{archive} target
464 is eliminated since Windows does not have the @code{tar} command,
465 and Windows also has a different default extension for midi files.
472 LILY_CMD = lilypond -ddelete-intermediate-files \
473 -dno-point-and-click \
474 -djob-count=$(NUMBER_OF_PROCESSORS)
476 #get the 8.3 name of CURDIR (workaround for spaces in PATH)
477 workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
480 .SUFFIXES: .ly .ily .pdf .mid
489 $(LILY_CMD) $< # this line begins with a tab
490 if exist "$*.pdf" move /Y "$*.pdf" PDF/ # begin with tab
491 if exist "$*.mid" move /Y "$*.mid" MIDI/ # begin with tab
503 $(piece)I.pdf: $(piece)I.ly $(notes)
504 $(piece)II.pdf: $(piece)II.ly $(notes)
505 $(piece)III.pdf: $(piece)III.ly $(notes)
506 $(piece)IV.pdf: $(piece)IV.ly $(notes)
508 $(piece).pdf: $(piece).ly $(notes)
510 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
511 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
512 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
513 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
514 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
515 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
521 parts: $(piece)-cello.pdf \
522 $(piece)-violinOne.pdf \
523 $(piece)-violinTwo.pdf \
529 movements: $(piece)I.pdf \
534 all: score parts movements
538 The next Makefile is for a @command{lilypond-book} document done in
539 LaTeX. This project has an index, which requires that the
540 @command{latex} command be run twice to update links. Output files are
541 all stored in the @code{out} directory for .pdf output and in the
542 @code{htmlout} directory for the html output.
551 LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
552 LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
553 PDF=cd $(OUTDIR) && pdflatex $(FILE)
554 HTML=cd $(WEBDIR) && latex2html $(FILE)
555 INDEX=cd $(OUTDIR) && makeindex $(FILE)
556 PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &
561 $(LILYBOOK_PDF) # begin with tab
562 $(PDF) # begin with tab
563 $(INDEX) # begin with tab
564 $(PDF) # begin with tab
565 $(PREVIEW) # begin with tab
568 $(LILYBOOK_HTML) # begin with tab
569 $(HTML) # begin with tab
570 cp -R $(WEBDIR)/$(FILE)/ ./ # begin with tab
571 $(BROWSER) $(FILE)/$(FILE).html & # begin with tab
574 cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf # begin with tab
577 rm -rf $(OUTDIR) # begin with tab
580 rm -rf $(WEBDIR) # begin with tab
583 tar -cvvf myproject.tar \ # begin this line with tab
585 --exclude=htmlout/* \
586 --exclude=myproject/* \
593 TODO: make this thing work on Windows
595 The previous makefile does not work on Windows. An alternative
596 for Windows users would be to create a simple batch file
597 containing the build commands. This will not
598 keep track of dependencies the way a makefile does, but it at
599 least reduces the build process to a single command. Save the
600 following code as @command{build.bat} or @command{build.cmd}.
601 The batch file can be run at the DOS prompt or by simply
602 double-clicking its icon.
605 lilypond-book --output=out --pdf myproject.lytex
611 copy out\myproject.pdf MyProject.pdf
618 @c @rprogram{Setup for MacOS X},
619 @rprogram{Command-line usage},
620 @rprogram{lilypond-book}