1 @c -*- coding: utf-8; mode: texinfo; -*-
3 @chapter Running LilyPond
5 This chapter details the technicalities of running LilyPond.
10 * Notes for the MacOS X app::
12 * Updating files with convert-ly::
17 @node Invoking lilypond
18 @section Invoking lilypond
19 @cindex Invoking LilyPond
20 @cindex command line options
21 @cindex options, command line
25 The @code{lilypond} executable may be called as follows from the command line.
28 lilypond [@var{option}]@dots{} @var{file}@dots{}
32 When invoked with a filename that has no extension, the @file{.ly}
33 extension is tried first. To read input from stdin, use a
34 dash (@code{-}) for @var{file}.
36 When @file{filename.ly} is processed it will produce
37 @file{filename.tex} as output (or @file{filename.ps} for PostScript
38 output). If @file{filename.ly} contains more than one @code{\score}
39 block, then the rest of the scores will be output in numbered files,
40 starting with @file{filename-1.tex}. Several files can be specified;
41 they will each be processed independently. @footnote{The status of
42 GUILE is not reset after processing a @code{.ly} file, so be careful
43 not to change any system defaults from within Scheme.}
46 @section Command line options
48 The following options are supported:
52 @item -e,--evaluate=@var{expr}
53 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
54 Multiple @code{-e} options may be given, they will be evaluated
57 The expression will be evaluated in the @code{guile-user} module, so
58 if you want to use definitions in @var{expr}, use
61 lilypond -e '(define-public a 42)'
65 on the command-line, and include
68 #(use-modules (guile-user))
72 at the top of the @code{.ly} file.
74 @item -f,--format=@var{format}
75 which formats should be written. Choices are @code{svg}, @code{ps},
76 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
78 @item -b,--backend=@var{format}
79 the output format to use for the back-end. Choices are
82 for @TeX{} output, to be processed with La@TeX{}. If present, the file
83 @file{file.textmetrics} is read to determine text extents.
85 dump text strings to @file{.texstr} file, which can be run through
86 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
87 extents of strings of text.
90 @cindex PostScript output
92 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
93 these fonts is done. When using oriental character sets, this can
97 for encapsulated PostScript. This dumps every page (system) as a separate
98 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
99 all pages (systems) including fonts.
101 This mode is used by default by lilypond-book.
104 for SVG (Scalable Vector Graphics). This dumps every page as a separate
105 @file{SVG} file, with embedded fonts.
106 @cindex SVG (Scalable Vector Graphics)
107 You need a SVG viewer which supports embedded fonts, or a SVG
108 viewer which is able to replace the embedded fonts with OTF fonts.
109 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
110 (version 0.42 or later), after copying the OTF fonts in directory
111 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
113 for a dump of the raw, internal Scheme-based drawing commands.
117 @cindex output format, setting
119 @item -d,--define-default=@var{var}=@var{val}
120 This sets the internal program option @var{var} to the Scheme value
121 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
122 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
131 -dpoint-and-click='#f'
134 @cindex point and click
136 Setting the @code{help} option will print a summary of the options
140 Show a summary of usage.
142 @item -H,--header=FIELD
143 Dump a header field to file BASENAME.FIELD
145 @item --include, -I=@var{directory}
146 Add @var{directory} to the search path for input files.
147 @cindex file searching
150 @item -i,--init=@var{file}
151 Set init file to @var{file} (default: @file{init.ly}).
153 @item -o,--output=@var{FILE}
154 Set the default output file to @var{FILE}. The appropriate
155 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
162 Generate DVI files. In this case, the @TeX{} backend should be
163 specified, i.e., @code{-b tex}.
166 Generate pictures of each page, in PNG format. This implies
167 @code{--ps}. The resolution in DPI of the image may be set with
173 Generate PDF. This implies @code{--ps}.
176 Generate an output file containing the titles and the first system
179 Do not generate the full pages. Useful in combination with
183 Do not trust the @code{.ly} input.
185 When LilyPond formatting is available through a web server, either the
186 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
187 @code{--safe} option will prevent inline Scheme code from wreaking
190 When LilyPond formatting is available through a web server, the
191 @code{--safe} @b{MUST} be passed. This will prevent inline Scheme
192 code from wreaking havoc, for example
198 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
203 The @code{--safe} option works by evaluating in-line Scheme
204 expressions in a special safe module. This safe module is derived from
205 GUILE @file{safe-r5rs} module, but adds a number of functions of the
206 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
208 In addition, @code{--safe} disallows @code{\include} directives and
209 disables the use of backslashes in @TeX{} strings.
211 In @code{--safe} mode, it is not possible to import LilyPond variables
214 @code{--safe} does @emph{not} detect resource overuse. It is still
215 possible to make the program hang indefinitely, for example by feeding
216 cyclic data structures into the backend. Therefore, if using LilyPond
217 on a publicly accessible webserver, the process should be limited in
218 both CPU and memory usage.
220 Note that @code{--safe} will prevent many useful LilyPond snippets from
221 being compiled. For a softer but secure alternative you can use the
222 @code{--jail} option.
225 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
226 Run LilyPond in a chroot jail.
228 The @code{--jail} option provides a more flexible alternative to
229 @code{--safe} when LilyPond formatting is available through a web
230 server or whenever LilyPond executes externally provided
233 The @code{--jail} option works by changing the root of LilyPond to
234 @var{jail} just before starting the actual compilation process. The user
235 and group are then changed to match those provided, and the current
236 directory is changed to @var{dir}. This setup guarantees that it is not
237 possible (at least in theory) to escape from the jail. Note that for
238 @code{--jail} to work LilyPond must be run as root, which is usually
239 accomplished in a safe way using @command{sudo}.
241 Setting up a jail is a slightly delicate matter, as we must be sure that
242 LilyPond is able to find whatever it needs to compile the source
243 @emph{inside the jail}. A typical setup comprises the following items:
246 @item Setting up a separate filesystem
247 A separate filesystem should be created for LilyPond, so that it can be
248 mounted with safe options such as @code{noexec}, @code{nodev}, and
249 @code{nosuid}. In this way, it is impossible to run executables or to
250 write directly to a device from LilyPond. If you do not want to create a
251 separate partition, just create a file of reasonable size and use it to
252 mount a loop device. A separate filesystem also guarantees that LilyPond
253 cannot write more space than it is allowed.
255 @item Setting up a separate user
256 A separate user and group (say, @samp{lily}/@samp{lily}) with low
257 privileges should be used to run LilyPond inside the jail. There should
258 be a single directory writable by this user, which should be passed in
261 @item Preparing the jail
262 LilyPond needs to read a number of files while running. All these files
263 are to be copied into the jail, under the same path they appear in the
264 real root filesystem. The entire content of the LilyPond installation
265 (e.g., @file{/usr/share/lilypond})
268 If problems arise, the simplest way to trace them down is to run
269 LilyPond using @command{strace}, which will allow you to determine which
272 @item Running LilyPond
273 In a jail mounted with @code{noexec} it is impossible to execute any external
274 program. Therefore LilyPond must be run with a backend that does not
275 require any such program. As we already mentioned, it must be also run
276 with superuser privileges (which, of course, it will lose immediately),
277 possibly using @command{sudo}. It is a good idea to limit the number of
278 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
279 -t}), and, if your operating system supports it, the amount of memory
280 that can be allocated.
285 Show version information.
288 Be verbose: show full paths of all files read, and give timing
292 Show the warranty with which GNU LilyPond comes. (It comes with
293 @strong{NO WARRANTY}!)
297 @section Environment variables
301 @cindex LILYPONDPREFIX
303 @code{Lilypond} recognizes the following environment variables:
306 This specifies a directory where locale messages and
307 data files will be looked up by default. The directory should contain
308 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
311 This selects the language for the warning messages.
313 @item LILYPOND_GC_YIELD
314 With this variable the memory footprint and performance can be
315 adjusted. It is a percentage tunes memory management behavior. With
316 higher values, the program uses more memory, with smaller values, it
317 uses more CPU time. The default value is @code{70}.
322 @node Notes for the MacOS X app
323 @section Notes for the MacOS X app
325 The scripts (such as lilypond-book, convert-ly, abc2ly, etc.) are also
326 included inside MacOS X .app. They can be run from the command line by
327 invoking them directly, e.g.
330 @var{path/to}/LilyPond.app/Contents/Resources/bin/convert-ly
333 Alternatively, you may add this directory to your path. Modify (or create)
334 a file called @code{.profile} in your home directory such that it contains
337 export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin
341 This file should end with a blank line.
343 Note that @var{path/to} will generally be @code{/Applications/}.
347 @section Error messages
349 @cindex error messages
350 Different error messages can appear while compiling a file:
356 Something looks suspect. If you are requesting something out of the
357 ordinary then you will understand the message, and can ignore it.
358 However, warnings usually indicate that something is wrong with the
362 Something is definitely wrong. The current processing step (parsing,
363 interpreting, or formatting) will be finished, but the next step will
369 Something is definitely wrong, and LilyPond cannot continue. This
370 happens rarely. The most usual cause is misinstalled fonts.
372 @cindex trace, Scheme
376 Errors that occur while executing Scheme code are caught by the Scheme
377 interpreter. If running with the verbose option (@code{-V} or
378 @code{--verbose}) then a call trace of the offending
379 function call is printed.
381 @cindex Programming error
382 @item Programming error
383 There was some internal inconsistency. These error messages are
384 intended to help the programmers and debuggers. Usually, they can be
385 ignored. Sometimes, they come in such big quantities that they obscure
386 other output. In this case, file a bug-report.
388 @item Aborted (core dumped)
389 This signals a serious programming error that caused the program to
390 crash. Such errors are considered critical. If you stumble on one,
396 @cindex errors, message format
397 If warnings and errors can
398 be linked to some part of the input file, then error messages have the
402 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
403 @var{offending input line}
406 A line-break is inserted in the offending line to indicate the column
407 where the error was found. For example,
410 test.ly:2:19: error: not a duration: 5:
415 These locations are LilyPond's best guess about where the warning or
416 error occurred, but (by their very nature) warnings and errors occur
417 when something unexpected happens. If you can't see an error in the
418 indicated line of your input file, try checking one or two lines
419 above the indicated position.
422 @node Updating files with convert-ly
423 @section Updating with @command{convert-ly}
425 @cindex Updating a LilyPond file
426 @cindex @code{convert-ly}
428 The LilyPond input syntax is routinely changed to simplify it or improve
429 it in different ways. As a side effect of this, the LilyPond interpreter
430 often is no longer compatible with older input files. To remedy this,
431 the program @command{convert-ly} can be used to deal with most of the
432 syntax changes between LilyPond versions.
434 It uses @code{\version} statements in the input files to detect the
435 old version number. In most cases, to upgrade your input file it is
436 sufficient to run@footnote{MacOS X users may execute this command
437 under the menu entry @samp{Compile > Update syntax}.}
440 convert-ly -e myfile.ly
443 If there are no changes to myfile.ly and file called myfile.ly.NEW
444 is created, then myfile.ly is already updated.
446 @command{convert-ly} always converts up to the last syntax change handled by
447 it. This means that the @code{\version} number left in the file is
448 usually lower than the version of @command{convert-ly} itself.
450 To upgrade LilyPond fragments in texinfo files, use
453 convert-ly --from=... --to=... --no-version *.itely
456 To upgrade many files at once, combine @code{convert-ly} with
457 standard unix commands. This example will upgrade all @code{.ly}
458 files in the current directory
461 for f in *.ly; do convert-ly -e $f; done;
464 In general, the program is invoked as follows:
467 convert-ly [@var{option}]@dots{} @var{file}@dots{}
471 The following options can be given:
475 Do an inline edit of the input file. Overrides @code{--output}.
477 @item -f,--from=@var{from-patchlevel}
478 Set the version to convert from. If this is not set, @command{convert-ly}
479 will guess this, on the basis of @code{\version} strings in the file.
481 @item -n,--no-version
482 Normally, @command{convert-ly} adds a @code{\version} indicator
483 to the output. Specifying this option suppresses this.
485 @item -s, --show-rules
486 Show all known conversions and exit.
488 @item --to=@var{to-patchlevel}
489 Set the goal version of the conversion. It defaults to the latest
499 Not all language changes are handled. Only one output option can be
503 @c We might want to make this a completely new section, along with more
504 @c info about how to upgrade old input files. -gp
507 Copy and paste from CVS, last updated
510 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
514 There are a few things that the convert-ly cannot handle. Here's a list of limitations
515 that the community has complained about.
517 This bug report structure has been chosen because convert-ly has a structure that doesn't
518 allow to smoothly implement all needed changes. Thus this is just a wishlist, placed
522 Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
523 To be able to run convert-ly
524 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
525 and similarly I replaced '>}' with '&}'. After the conversion, I could
526 then change back from '{ #' to '{ <' and from '& }' to '> }'.
527 Doesn't convert all text markup correctly. In the old markup syntax,
528 it was possible to group a number of markup commands together within parentheses, e.g.
529 -#'((bold italic) "string")
530 This will incorrectly be converted into
531 -\markup{{\bold italic} "string"}
532 instead of the correct
533 -\markup{\bold \italic "string"}
535 Doesn't handle \partcombine
536 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
538 \magnify isn't changed to \fontsize.
539 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
540 remove-tag isn't changed.
541 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
542 first-page-number isn't changed.
543 - first-page-number no => printfirst-page-number = ##f
544 Line breaks in header strings aren't converted.
545 - \\\\ as line break in \header strings => \markup \center-align <
546 "First Line" "Second Line" >
547 Crescendo and decrescendo terminators aren't converted.
551 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
553 \markup{ \center-align <{ ... }> } should be converted to:
554 \markup{ \center-align {\line { ... }} }
555 but now, \line is missing.
557 Special LaTeX characters such as $~$ in text are not converted to UTF8.
563 @section Reporting bugs
566 @cindex reporting bugs
568 If you have input that results in a crash or an erroneous output, then
569 that is a bug. We try to respond to bug-reports promptly, and fix them as
570 soon as possible. Help us by sending a defective input file, so we can
571 reproduce the problem. Send the report via:
574 @uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs}
580 @item Try to produce a very small input file which demonstrates the problem;
581 one or two bars is often sufficient to reproduce a bug. The smaller the
582 input file is, the easier it is for us to debug the problem.
584 @item Don't forget to tell which version of LilyPond you use!
586 @item If possible, use @code{ragged-right} in your example. This makes sure
587 that the bug can be reproduced in all paper sizes.
591 @c the bug database is not up to date enough.
593 When you've found a bug, have a look at our
594 @uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if
595 it has already been reported. You could also try to do a few searches
596 on the mailing list for the bug. Sometimes the bug will have already
597 been reported and a fix or workaround is already known.
600 Here is an example of a good bug report:
603 It seems that placement of accidentals is broken. In the
604 following example, the accidental touches the note head.
606 Using Mac OSX 10.3.7, fink package lilypond-devel
609 \layout { ragged-right = ##t }
616 \layout { ragged-right = ##t }
618 \override Accidental #'extra-offset = #'(1.0 . 0)
624 @section Editor support
629 @cindex modes, editor
630 @cindex syntax coloring
631 @cindex coloring, syntax
633 There is support from different editors for LilyPond.
637 Emacs has a @file{lilypond-mode}, which provides keyword
638 autocompletion, indentation, LilyPond specific parenthesis matching
639 and syntax coloring, handy compile short-cuts and reading LilyPond
640 manuals using Info. If @file{lilypond-mode} is not installed on your
641 platform, then read the
643 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
646 installation instructions.
651 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
652 with syntax coloring tools. For more information, refer to the
654 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
657 installation instructions.
663 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
664 This plugin includes a DVI viewer, integrated help and viewing via
665 GhostScript. It can be installed by doing @key{Plugins > Plugin
666 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
670 All these editors can be made to jump into the input file to the source
671 of a symbol in the graphical output. See @ref{Point and click}.