1 @c -*- coding: latin-1; mode: texinfo; -*-
3 @chapter Running LilyPond
5 This chapter details the technicalities of running LilyPond.
11 * Updating files with convert-ly::
15 * Including LilyPond files::
18 @node Invoking lilypond
19 @section Invoking lilypond
20 @cindex Invoking LilyPond
21 @cindex command line options
22 @cindex options, command line
26 The @code{lilypond} executable may be called as follows from the command line.
29 lilypond [@var{option}]@dots{} @var{file}@dots{}
33 When invoked with a filename that has no extension, the @file{.ly}
34 extension is tried first. To read input from stdin, use a
35 dash (@code{-}) for @var{file}.
37 When @file{filename.ly} is processed it will produce
38 @file{filename.tex} as output (or @file{filename.ps} for PostScript
39 output). If @file{filename.ly} contains more than one @code{\score}
40 block, then the rest of the scores will be output in numbered files,
41 starting with @file{filename-1.tex}. Several files can be specified;
42 they will each be processed independently. @footnote{The status of
43 GUILE is not reset after processing a @code{.ly} file, so be careful
44 not to change any system defaults from within Scheme.}
47 @section Command line options
49 The following options are supported:
53 @item -e,--evaluate=@var{expr}
54 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
55 Multiple @code{-e} options may be given, they will be evaluated
58 @item -f,--format=@var{format}
59 which formats should be written. Choices are @code{svg}, @code{ps},
60 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
62 @item -b,--backend=@var{format}
63 the output format to use for the back-end. Choices are
66 for @TeX{} output, to be processed with La@TeX{}. If present, the file
67 @file{file.textmetrics} is read to determine text extents.
69 dump text strings to @file{.texstr} file, which can be run through
70 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
71 extents of strings of text.
74 @cindex PostScript output
76 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
77 these fonts is done. When using oriental character sets, this can
81 for encapsulated PostScript. This dumps every page (system) as a separate
82 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
83 all pages (systems) including fonts.
85 This mode is used by default by lilypond-book.
88 for SVG (Scalable Vector Graphics)
89 @cindex SVG (Scalable Vector Graphics)
91 for a dump of the raw, internal Scheme-based drawing commands.
95 @cindex output format, setting
97 @item -d,--define-default=@var{var}=@var{val}
98 This sets the internal program option @var{var} to the Scheme value
99 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
100 switch off an option, @code{no-} may be prefixed to @var{var}, eg.
108 -dpoint-and-click='#f'
111 @cindex point and click
113 Setting the @code{help} option will print a summary of the options
117 Show a summary of usage.
119 @item --include, -I=@var{directory}
120 Add @var{directory} to the search path for input files.
121 @cindex file searching
124 @item -i,--init=@var{file}
125 Set init file to @var{file} (default: @file{init.ly}).
127 @item -o,--output=@var{FILE}
128 Set the default output file to @var{FILE}. The appropriate
129 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
136 Generate DVI files. In this case, the @TeX{} backend should be
137 specified, i.e., @code{-f tex}.
140 Generate pictures of each page, in PNG format. This implies
141 @code{--ps}. The resolution in DPI of the image may be set with
147 Generate PDF. This implies @code{--ps}.
150 Generate an output file containing the titles and the first system
153 Do not generate the full pages. Useful in combination with
157 Do not trust the @code{.ly} input.
159 When LilyPond formatting is available through a web server, either the
160 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
161 @code{--safe} option will prevent inline Scheme code from wreaking
164 When LilyPond formatting is available through a web server, the
165 @code{--safe} @b{MUST} be passed. This will prevent inline Scheme
166 code from wreaking havoc, for example
172 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
177 The @code{--safe} option works by evaluating in-line Scheme
178 expressions in a special safe module. This safe module is derived from
179 GUILE @file{safe-r5rs} module, but adds a number of functions of the
180 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
182 In addition, @code{--safe} disallows @code{\include} directives and
183 disables the use of backslashes in @TeX{} strings.
185 In @code{--safe} mode, it is not possible to import LilyPond variables
188 @code{--safe} does @emph{not} detect resource overuse. It is still
189 possible to make the program hang indefinitely, for example by feeding
190 cyclic data structures into the backend. Therefore, if using LilyPond
191 on a publicly accessible webserver, the process should be limited in
192 both CPU and memory usage.
194 Note that @code{--safe} will prevent many useful LilyPond snippets from
195 being compiled. For a softer but secure alternative you can use the
196 @code{--jail} option.
199 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
200 Run LilyPond in a chroot jail.
202 The @code{--jail} option provides a more flexible alternative to
203 @code{--safe} when LilyPond formatting is available through a web
204 server or whenever LilyPond executes externally provided
207 The @code{--jail} option works by changing the root of LilyPond to
208 @var{jail} just before starting the actual compilation process. The user
209 and group are then changed to match those provided, and the current
210 directory is changed to @var{dir}. This setup guarantees that it is not
211 possible (at least in theory) to escape from the jail. Note that for
212 @code{--jail} to work LilyPond must be run as root, which is usually
213 accomplished in a safe way using @command{sudo}.
215 Setting up a jail is a slightly delicate matter, as we must be sure that
216 LilyPond is able to find whatever it needs to compile the source
217 @emph{inside the jail}. A typical setup comprises the following items:
220 @item Setting up a separate filesystem
221 A separate filesystem should be created for LilyPond, so that it can be
222 mounted with safe options such as @code{noexec}, @code{nodev}, and
223 @code{nosuid}. In this way, it is impossible to run executables or to
224 write directly to a device from LilyPond. If you do not want to create a
225 separate partition, just create a file of reasonable size and use it to
226 mount a loop device. A separate filesystem also guarantees that LilyPond
227 cannot write more space than it is allowed.
229 @item Setting up a separate user
230 A separate user and group (say, @samp{lily}/@samp{lily}) with low
231 privileges should be used to run LilyPond inside the jail. There should
232 be a single directory writable by this user, which should be passed in
235 @item Preparing the jail
236 LilyPond needs to read a number of files while running. All these files
237 are to be copied into the jail, under the same path they apper in the
238 real root filesystem. The entire content of the LilyPond installation
239 (e.g., @file{/usr/share/lilypond})
242 If problems arise, the simplest way to trace them down is to run
243 LilyPond using @command{strace}, which will allow you to determine which
246 @item Running LilyPond
247 In a jail mounted with @code{noexec} it is impossible to execute any external
248 program. Therefore LilyPond must be run with a backend that does not
249 require any such program. As we already mentioned, it must be also run
250 with superuser privileges (which, of course, it will lose immediately),
251 possibly using @command{sudo}. It is a good idea to limit the number of
252 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
253 -t}), and, if your operating system supports it, the amount of memory
254 that can be allocated.
259 Show version information.
262 Be verbose: show full paths of all files read, and give timing
266 Show the warranty with which GNU LilyPond comes. (It comes with
267 @strong{NO WARRANTY}!)
271 @section Environment variables
274 For processing both the @TeX{} and the PostScript output, the
275 appropriate environment variables must be set. The following scripts
279 @item @file{buildscripts/@/out/@/lilypond@/-profile}
281 @item @file{buildscripts/@/out/@/lilypond@/-login} (for C-shells)
284 They should normally be sourced as part of the login process. If these
285 scripts are not run from the system wide login process, then you must
288 @cindex installing LilyPond
290 If you use sh, bash, or a similar shell, then add the following to
291 your @file{.profile}:
293 . @var{/the/path/to/}lilypond-profile
296 If you use csh, tcsh or a similar shell, then add the following to
297 your @file{~/.login}:
299 source @var{/the/path/to/}lilypond-login
302 Of course, in both cases, you should substitute the proper location of
305 These scripts set the following variables:
308 To make sure that @TeX{} and lilypond find data files (among
309 others @file{.tex}, @file{.mf}, and @file{.tfm}),
310 you have to set @code{TEXMF} to point to the lilypond data
311 file tree. A typical setting would be
313 @{/usr/share/lilypond/2.4.0,@{!!/usr/share/texmf@}@}
320 @cindex printing postscript
326 @cindex LILYPONDPREFIX
328 @code{Lilypond} recognizes the following environment variables:
331 This specifies a directory where locale messages and
332 data files will be looked up by default. The directory should contain
333 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
336 This selects the language for the warning messages.
341 @section Error messages
343 @cindex error messages
344 Different error messages can appear while compiling a file:
350 Something looks suspect. If you are requesting something out of the
351 ordinary then you will understand the message, and can ignore it.
352 However, warnings usually indicate that something is wrong with the
356 Something is definitely wrong. The current processing step (parsing,
357 interpreting, or formatting) will be finished, but the next step will
363 Something is definitely wrong, and LilyPond cannot continue. This
364 happens rarely. The most usual cause is misinstalled fonts.
366 @cindex trace, Scheme
370 Errors that occur while executing Scheme code are caught by the Scheme
371 interpreter. If running with the verbose option (@code{-V} or
372 @code{--verbose}) then a call trace of the offending
373 function call is printed.
375 @cindex Programming error
376 @item Programming error
377 There was some internal inconsistency. These error messages are
378 intended to help the programmers and debuggers. Usually, they can be
379 ignored. Sometimes, they come in such big quantities that they obscure
380 other output. In this case, file a bug-report.
382 @item Aborted (core dumped)
383 This signals a serious programming error that caused the program to
384 crash. Such errors are considered critical. If you stumble on one,
390 @cindex errors, message format
391 If warnings and errors can
392 be linked to some part of the input file, then error messages have the
396 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
397 @var{offending input line}
400 A line-break is inserted in the offending line to indicate the column
401 where the error was found. For example,
404 test.ly:2:19: error: not a duration: 5:
409 These locations are LilyPond's best guess about where the warning or
410 error occured, but (by their very nature) warnings and errors occur
411 when something unexpected happens. If you can't see an error in the
412 indicated line of your input file, try checking one or two lines
413 above the indicated position.
416 @node Updating files with convert-ly
417 @section Updating with @command{convert-ly}
419 The LilyPond input syntax is routinely changed to simplify it or improve
420 it in different ways. As a side effect of this, the LilyPond interpreter
421 often is no longer compatible with older input files. To remedy this,
422 the program @command{convert-ly} can be used to deal with most of the
423 syntax changes between LilyPond versions.
425 It uses @code{\version} statements in the input files to detect the old
426 version number. In most cases, to upgrade your input file it is sufficient
430 convert-ly -e myfile.ly
433 If there are no changes to myfile.ly and file called myfile.ly.NEW
434 is created, then myfile.ly is already updated.
436 @command{convert-ly} always converts up to the last syntax change handled by
437 it. This means that the @code{\version} number left in the file is
438 usually lower than the version of @command{convert-ly} itself.
440 To upgrade LilyPond fragments in texinfo files, use
443 convert-ly --from=... --to=... --no-version *.itely
446 To upgrade many files at once, combine @code{convert-ly} with
447 standard unix commands. This example will upgrade all @code{.ly}
448 files in the current directory
451 for f in *.ly; do convert-ly -e $f; done;
454 In general, the program is invoked as follows:
457 convert-ly [@var{option}]@dots{} @var{file}@dots{}
461 The following options can be given:
465 Do an inline edit of the input file. Overrides @code{--output}.
467 @item -f,--from=@var{from-patchlevel}
468 Set the version to convert from. If this is not set, @command{convert-ly}
469 will guess this, on the basis of @code{\version} strings in the file.
471 @item -o,--output=@var{file}
472 Set the output file to write.
474 @item -n,--no-version
475 Normally, @command{convert-ly} adds a @code{\version} indicator
476 to the output. Specifying this option suppresses this.
478 @item -s, --show-rules
479 Show all known conversions and exit.
481 @item --to=@var{to-patchlevel}
482 Set the goal version of the conversion. It defaults to the latest
492 Not all language changes are handled. Only one output option can be
496 @c We might want to make this a completely new section, along with more
497 @c info about how to upgrade old input files. -gp
500 Copy and paste from CVS, last updated
503 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
507 There are a few things that the convert-ly cannot handle. Here's a list of limitations
508 that the community has complained about.
510 This bug report structure has been chosen because convert-ly has a structure that doesn't
511 allow to smoothly implement all needed changes. Thus this is just a wishlist, placed
515 Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
516 To be able to run convert-ly
517 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
518 and similarly I replaced '>}' with '&}'. After the conversion, I could
519 then change back from '{ #' to '{ <' and from '& }' to '> }'.
520 Doesn't convert all text markup correctly. In the old markup syntax,
521 it was possible to group a number of markup commands together within parentheses, e.g.
522 -#'((bold italic) "string")
523 This will incorrectly be converted into
524 -\markup{{\bold italic} "string"}
525 instead of the correct
526 -\markup{\bold \italic "string"}
528 Doesn't handle \partcombine
529 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
531 \magnify isn't changed to \fontsize.
532 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
533 remove-tag isn't changed.
534 - \applymusic #(remove-tag '. . .) => \keepWithTag #'. . .
535 firstpagenumber isn't changed.
536 - firstpagenumber no => printfirstpagenumber = ##f
537 Line breaks in header strings aren't converted.
538 - \\\\ as line break in \header strings => \markup \center-align <
539 "First Line" "Second Line" >
540 Crescendo and decrescendo terminators aren't converted.
544 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
546 \markup{ \center-align <{ ... }> } should be converted to:
547 \markup{ \center-align {\line { ... }} }
548 but now, \line is missing.
554 @section Reporting bugs
557 @cindex reporting bugs
559 If you have input that results in a crash or an erroneous output, then
560 that is a bug. We try to respond to bug-reports promptly, and fix them as
561 soon as possible. Help us by sending a defective input file, so we can
562 reproduce the problem. Make it small, so we can easily debug the
563 problem. Don't forget to tell which version of LilyPond you use! Send
564 the report to @email{bug-lilypond@@gnu.org}.
567 @c the bug database is not up to date enough.
569 When you've found a bug, have a look at our
570 @uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if
571 it has already been reported. You could also try to do a few searches
572 on the mailing list for the bug. Sometimes the bug will have already
573 been reported and a fix or workaround is already known.
576 Here is an example of a good bug report:
579 It seems that placement of accidentals is broken. In the
580 following example, the accidental touches the note head.
582 Using Mac OSX 10.3.7, fink package lilypond-devel
593 \override Accidental #'extra-offset = #'(1.0 . 0)
599 @section Editor support
604 @cindex modes, editor
605 @cindex syntax coloring
606 @cindex coloring, syntax
608 There is support from different editors for LilyPond.
612 Emacs has a @file{lilypond-mode}, which provides keyword
613 autocompletion, indentation, LilyPond specific parenthesis matching
614 and syntax coloring, handy compile short-cuts and reading LilyPond
615 manuals using Info. If @file{lilypond-mode} is not installed on your
616 platform, then read the
618 @uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}.
621 installation instructions.
626 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
627 with syntax coloring tools. For more information, refer to the
629 @uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}.
632 installation instructions.
638 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
639 This plugin includes a DVI viewer, integrated help and viewing via
640 GhostScript. It can be installed by doing @key{Plugins > Plugin
641 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
645 All these editors can be made to jump into the input file to the source
646 of a symbol in the graphical output. See @ref{Point and click}.
650 @section File structure
652 The major part of this manual is concerned with entering various
653 forms of music in LilyPond. However, many music expressions are not
654 valid input on their own, for example, a @code{.ly} file containing
661 will result in a parsing error. Instead, music should be inside other
662 expressions, which may be put in a file by themselves. Such
663 expressions are called toplevel expressions. This section enumerates
666 A @code{.ly} file contains any number of toplevel expressions, where a
667 toplevel expression is one of the following
671 An output definition, such as @code{\paper}, @code{\midi}, and
672 @code{\layout}. Such a definition at the toplevel changes the default
673 settings for the block entered.
676 A @code{\header} block. This sets the global header block. This
677 is the block containing the definitions for book-wide settings, like
678 composer, title, etc.
681 An @code{\addquote} statement. See @ref{Quoting other voices}
682 for more information.
685 A @code{\score} block. This score will be collected with other
686 toplevel scores, and combined as a single @code{\book}.
688 This behavior can be changed by setting the variable
689 @code{toplevel-score-handler} at toplevel. The default handler is
690 defined in the init file @file{scm/@/lily@/.scm}.
693 A @code{\book} block logically combines multiple movements
694 (i.e., multiple @code{\score} blocks) in one document. A number of
695 @code{\scores} creates a single output file, where all movement are
698 This behavior can be changed by setting the variable
699 @code{toplevel-book-handler} at toplevel. The default handler is
700 defined in the init file @file{scm/@/lily@/.scm}.
703 A compound music expression, such as
708 This will add the piece in a @code{\score} and format it in a
709 single book together with all other toplevel @code{\score}s and music
712 This behavior can be changed by setting the variable
713 @code{toplevel-music-handler} at toplevel. The default handler is
714 defined in the init file @file{scm/@/lily@/.scm}.
717 A markup text, a verse for example
720 2. The first line verse two.
724 Markup texts are rendered above, between or below the scores or music
725 expressions, wherever they appear.
728 An indentifier, such as
733 This can be used later on in the file by entering @code{\foo}. The
734 name of an identifier should have alphabetic characters only; no
735 numbers, underscores or dashes.
739 The following example shows three things that may be entered at
744 % movements are non-justified by default
756 At any point in a file, any of the following lexical instructions can
760 @item @code{\version}
761 @item @code{\include}
762 @item @code{\renameinput}
766 @node Including LilyPond files
767 @section Including LilyPond files
769 @cindex @code{\include}
770 @cindex including files
772 A large project may be split up into separate files. To refer to another
776 \include "otherfile.ly"
779 For example, you may write separate files for each instrument part and
780 create a ``full score'' file which brings together the individual