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
32 * Troubleshooting (taking it all apart)::
36 @subsection Common errors
38 The error conditions described below occur often, yet the cause
39 is not obvious or easily found. Once seen and understood, they
44 * Music runs off the page::
45 * An extra staff appears::
46 * Apparent error in ../ly/init.ly::
47 * Error message Unbound variable %::
48 * Error message FT_Get_Glyph_Name::
51 @node Music runs off the page
52 @unnumberedsubsubsec Music runs off the page
54 Music running off the page over the right margin or appearing
55 unduly compressed is almost always due to entering an incorrect
56 duration on a note, causing the final note in a measure to extend
57 over the bar line. It is not invalid if the final note in a
58 measure does not end on the automatically entered bar line, as the
59 note is simply assumed to carry over into the next measure. But
60 if a long sequence of such carry-over measures occurs the music
61 can appear compressed or may flow off the page because automatic
62 line breaks can be inserted only at the end of complete measures,
63 i.e., where all notes end before or at the end of the measure.
65 @warning{An incorrect duration can cause line breaks to be
66 inhibited, leading to a line of highly compressed music or
67 music which flows off the page.}
69 The incorrect duration can be found easily if bar checks are used,
70 see @ruser{Bar and bar number checks}.
72 If you actually intend to have a series of such carry-over measures
73 you will need to insert an invisible bar line where you want the
74 line to break. For details, see @ruser{Bar lines}.
77 @node An extra staff appears
78 @unnumberedsubsubsec An extra staff appears
80 If contexts are not created explicitly with @code{\new} they will be
81 silently created as soon as a command is encountered which cannot
82 be applied to an existing context. In simple scores the automatic
83 creation of contexts is useful, and most of the examples in the
84 LilyPond manuals take advantage of this simplification. But
85 occasionally the silent creation of contexts can give rise to
86 unexpected new staves or scores. For example, it might be expected
87 that the following code would cause all note heads within the
88 following staff to be colored red, but in fact it results in two
89 staves with the note heads remaining the default black in the lower
92 @lilypond[quote,verbatim,relative=2]
93 \override Staff.NoteHead #'color = #red
97 This is because a @code{Staff} context does not exist when the
98 override is processed, so one is implicitly created and the override
99 is applied to it, but then the @code{\new Staff} command creates
100 another, separate, staff into which the notes are placed. The
101 correct code to color all note heads red is
103 @lilypond[quote,verbatim,relative=2]
105 \override Staff.NoteHead #'color = #red
110 As a second example, if a @code{\relative} command is placed inside
111 a @code{\repeat} command two staves result, the second offset from
112 the first, because the @code{\repeat} command generates two
113 @code{\relative} blocks, which each implicitly create @code{Staff}
114 and @code{Voice} blocks.
116 @lilypond[quote,verbatim]
117 \repeat unfold 2 \relative { c d e f }
120 The correct way is to reverse the @code{\repeat} and
121 @code{\relative} commands, like this:
123 @lilypond[quote,verbatim]
125 \repeat unfold 2 { c d e f }
130 @node Apparent error in ../ly/init.ly
131 @unnumberedsubsubsec Apparent error in @code{../ly/init.ly}
133 Various obscure error messages may appear about syntax errors in
134 @code{../ly/init.ly} if the input file is not correctly formed,
135 for example, if it does not contain correctly
136 matched braces or quote signs.
138 The most common error is a missing brace, (@code{@}}), at the end of
139 a @code{score} block. Here the solution is obvious: check the
140 @code{score} block is correctly terminated. The correct structure
141 of an input file is described in @rlearning{How LilyPond input files work}.
142 Using an editor which automatically highlights matching brackets and
143 braces is helpful to avoid such errors.
145 A second common cause is no white space between the last syllable
146 of a lyrics block and the terminating brace, (@code{@}}). Without
147 this separation the brace is taken to be part of the syllable. It
148 is always advisable to ensure there is white space before and after
149 @emph{every} brace. For the importance of this when using lyrics,
150 see @ruser{Lyrics explained}.
152 This error message can also appear if a terminating quote sign,
153 (@code{"}), is omitted. In this case an accompanying error message
154 @c keep "-matching straight in fancy editors
155 should give a line number close to the line in error. The
156 mismatched quote will usually be on the line one or two above.
158 @node Error message Unbound variable %
159 @unnumberedsubsubsec Error message Unbound variable %
161 This error message will appear at the bottom of the console
162 output or log file together with a @qq{GUILE signalled an error ...}
163 message every time a Scheme routine is called which (invalidly)
164 contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
166 LilyPond comments begin with a percent sign, (@code{%}), and must
167 not be used within Scheme routines. Scheme comments begin with a
168 semi-colon, (@code{;}).
170 @node Error message FT_Get_Glyph_Name
171 @unnumberedsubsubsec Error message FT_Get_Glyph_Name
173 This error messages appears in the console output or log file if
174 an input file contains a non-ASCII character and was not saved in
175 UTF-8 encoding. For details, see @ruser{Text encoding}.
177 @node Troubleshooting (taking it all apart)
178 @subsection Troubleshooting (taking it all apart)
180 Sooner or later, you will write a file that LilyPond cannot
181 compile. The messages that LilyPond gives may help
182 you find the error, but in many cases you need to do some
183 investigation to determine the source of the problem.
185 The most powerful tools for this purpose are the
186 single line comment (indicated by @code{%}) and the block
187 comment (indicated by @code{%@{ ... %@}}). If you don't
188 know where a problem is, start commenting out huge portions
189 of your input file. After you comment out a section, try
190 compiling the file again. If it works, then the problem
191 must exist in the portion you just commented. If it doesn't
192 work, then keep on commenting out material until you have
193 something that works.
195 In an extreme case, you might end up with only
209 (in other words, a file without any music)
211 If that happens, don't give up. Uncomment a bit -- say,
212 the bass part -- and see if it works. If it doesn't work,
213 then comment out all of the bass music (but leave
214 @code{\bass} in the @code{\score} uncommented.
217 bass = \relative c' @{
225 Now start slowly uncommenting more and more of the
226 @code{bass} part until you find the problem line.
228 Another very useful debugging technique is constructing
229 @rgeneral{Tiny examples}.
232 @node Make and Makefiles
233 @section Make and Makefiles
238 Pretty well all the platforms Lilypond can run on support a software
239 facility called @code{make}. This software reads a special file called a
240 @code{Makefile} that defines what files depend on what others and what
241 commands you need to give the operating system to produce one file from
242 another. For example the makefile would spell out how to produce
243 @code{ballad.pdf} and @code{ballad.midi} from @code{ballad.ly} by
246 There are times when it is a good idea to create a @code{Makefile}
247 for your project, either for your own convenience or
248 as a courtesy to others who might have access to your source files.
249 This is true for very large projects with many included files and
250 different output options (e.g. full score, parts, conductor's
251 score, piano reduction, etc.), or for projects that
252 require difficult commands to build them (such as
253 @code{lilypond-book} projects). Makefiles vary greatly in
254 complexity and flexibility, according to the needs and skills of
255 the authors. The program GNU Make comes installed on GNU/Linux
256 distributions and on MacOS X, and it is also available for Windows.
258 See the @strong{GNU Make Manual} for full details on using
259 @code{make}, as what follows here gives only a glimpse of what it
262 The commands to define rules in a makefile differ
263 according to platform; for instance the various forms of Linux and
264 MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on
265 MacOS X, you need to configure the system to use the command-line
266 intepreter. Here are some example makefiles, with versions for both
267 Linux/MacOS and Windows.
269 The first example is for an orchestral work in four
270 movements with a directory structure as follows:
287 | |-- symphony-cello.ly
288 | |-- symphony-horn.ly
289 | |-- symphony-oboes.ly
290 | |-- symphony-viola.ly
291 | |-- symphony-violinOne.ly
292 | `-- symphony-violinTwo.ly
302 The @code{.ly} files in the @code{Scores} and
303 @code{Parts} directories get their notes from @code{.ily}
304 files in the @code{Notes} directory:
307 %%% top of file "symphony-cello.ly"
308 \include ../definitions.ily
309 \include ../Notes/cello.ily
312 The makefile will have targets of @code{score} (entire piece in
313 full score), @code{movements} (individual movements in full score),
314 and @code{parts} (individual parts for performers). There
315 is also a target @code{archive} that will create a tarball of
316 the source files, suitable for sharing via web or email. Here is
317 the makefile for GNU/Linux or MacOS X. It should be saved with the
318 name @code{Makefile} in the top directory of the project:
320 @warning{When a target or pattern rule is defined, the
321 subsequent lines must begin with tabs, not spaces.}
324 # the name stem of the output files
326 # determine how many processors are present
327 CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
328 # The command to run lilypond
329 LILY_CMD = lilypond -ddelete-intermediate-files \
330 -dno-point-and-click -djob-count=$(CPU_CORES)
332 # The suffixes used in this Makefile.
333 .SUFFIXES: .ly .ily .pdf .midi
335 # Input and output files are searched in the directories listed in
336 # the VPATH variable. All of them are subdirectories of the current
337 # directory (given by the GNU make variable `CURDIR').
344 # The pattern rule to create PDF and MIDI files from a LY input file.
345 # The .pdf output files are put into the `PDF' subdirectory, and the
346 # .midi files go into the `MIDI' subdirectory.
348 $(LILY_CMD) $<; \ # this line begins with a tab
349 if test -f "$*.pdf"; then \
352 if test -f "$*.midi"; then \
353 mv "$*.midi" MIDI/; \
364 # The dependencies of the movements.
365 $(piece)I.pdf: $(piece)I.ly $(notes)
366 $(piece)II.pdf: $(piece)II.ly $(notes)
367 $(piece)III.pdf: $(piece)III.ly $(notes)
368 $(piece)IV.pdf: $(piece)IV.ly $(notes)
370 # The dependencies of the full score.
371 $(piece).pdf: $(piece).ly $(notes)
373 # The dependencies of the parts.
374 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
375 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
376 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
377 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
378 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
379 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
381 # Type `make score' to generate the full score of all four
382 # movements as one file.
386 # Type `make parts' to generate all parts.
387 # Type `make foo.pdf' to generate the part for instrument `foo'.
388 # Example: `make symphony-cello.pdf'.
390 parts: $(piece)-cello.pdf \
391 $(piece)-violinOne.pdf \
392 $(piece)-violinTwo.pdf \
397 # Type `make movements' to generate files for the
398 # four movements separately.
400 movements: $(piece)I.pdf \
405 all: score parts movements
408 tar -cvvf stamitz.tar \ # this line begins with a tab
409 --exclude=*pdf --exclude=*~ \
410 --exclude=*midi --exclude=*.tar \
415 There are special complications on the Windows platform. After
416 downloading and installing GNU Make for Windows, you must set the
417 correct path in the system's environment variables so that the
418 DOS shell can find the Make program. To do this, right-click on
419 "My Computer," then choose @code{Properties} and
420 @code{Advanced}. Click @code{Environment Variables}, and then
421 in the @code{System Variables} pane, highlight @code{Path}, click
422 @code{edit}, and add the path to the GNU Make executable file, which
423 will look something like this:
426 C:\Program Files\GnuWin32\bin
429 The makefile itself has to be altered to handle different shell
430 commands and to deal with spaces that are present
431 in some default system directories. The @code{archive} target
432 is eliminated since Windows does not have the @code{tar} command,
433 and Windows also has a different default extension for midi files.
440 LILY_CMD = lilypond -ddelete-intermediate-files \
441 -dno-point-and-click \
442 -djob-count=$(NUMBER_OF_PROCESSORS)
444 #get the 8.3 name of CURDIR (workaround for spaces in PATH)
445 workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
448 .SUFFIXES: .ly .ily .pdf .mid
457 $(LILY_CMD) $< # this line begins with a tab
458 if exist "$*.pdf" move /Y "$*.pdf" PDF/ # begin with tab
459 if exist "$*.mid" move /Y "$*.mid" MIDI/ # begin with tab
471 $(piece)I.pdf: $(piece)I.ly $(notes)
472 $(piece)II.pdf: $(piece)II.ly $(notes)
473 $(piece)III.pdf: $(piece)III.ly $(notes)
474 $(piece)IV.pdf: $(piece)IV.ly $(notes)
476 $(piece).pdf: $(piece).ly $(notes)
478 $(piece)-cello.pdf: $(piece)-cello.ly cello.ily
479 $(piece)-horn.pdf: $(piece)-horn.ly horn.ily
480 $(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
481 $(piece)-viola.pdf: $(piece)-viola.ly viola.ily
482 $(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
483 $(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
489 parts: $(piece)-cello.pdf \
490 $(piece)-violinOne.pdf \
491 $(piece)-violinTwo.pdf \
497 movements: $(piece)I.pdf \
502 all: score parts movements
506 The next Makefile is for a @command{lilypond-book} document done in
507 LaTeX. This project has an index, which requires that the
508 @command{latex} command be run twice to update links. Output files are
509 all stored in the @code{out} directory for .pdf output and in the
510 @code{htmlout} directory for the html output.
519 LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
520 LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
521 PDF=cd $(OUTDIR) && pdflatex $(FILE)
522 HTML=cd $(WEBDIR) && latex2html $(FILE)
523 INDEX=cd $(OUTDIR) && makeindex $(FILE)
524 PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &
529 $(LILYBOOK_PDF) # begin with tab
530 $(PDF) # begin with tab
531 $(INDEX) # begin with tab
532 $(PDF) # begin with tab
533 $(PREVIEW) # begin with tab
536 $(LILYBOOK_HTML) # begin with tab
537 $(HTML) # begin with tab
538 cp -R $(WEBDIR)/$(FILE)/ ./ # begin with tab
539 $(BROWSER) $(FILE)/$(FILE).html & # begin with tab
542 cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf # begin with tab
545 rm -rf $(OUTDIR) # begin with tab
548 rm -rf $(WEBDIR) # begin with tab
551 tar -cvvf myproject.tar \ # begin this line with tab
553 --exclude=htmlout/* \
554 --exclude=myproject/* \
561 TODO: make this thing work on Windows
563 The previous makefile does not work on Windows. An alternative
564 for Windows users would be to create a simple batch file
565 containing the build commands. This will not
566 keep track of dependencies the way a makefile does, but it at
567 least reduces the build process to a single command. Save the
568 following code as @command{build.bat} or @command{build.cmd}.
569 The batch file can be run at the DOS prompt or by simply
570 double-clicking its icon.
573 lilypond-book --output=out --pdf myproject.lytex
579 copy out\myproject.pdf MyProject.pdf
586 @c @rprogram{Setup for MacOS X},
587 @rprogram{Command-line usage},
588 @rprogram{lilypond-book}