2 @chapter Running LilyPond
4 This chapter details the technicalities of running LilyPond.
9 * Notes for the MacOS X app::
11 * Updating files with convert-ly::
16 @node Invoking lilypond
17 @section Invoking lilypond
18 @cindex Invoking LilyPond
19 @cindex command line options
20 @cindex options, command line
24 The @code{lilypond} executable may be called as follows from the command line.
27 lilypond [@var{option}]@dots{} @var{file}@dots{}
31 When invoked with a filename that has no extension, the @file{.ly}
32 extension is tried first. To read input from stdin, use a
33 dash (@code{-}) for @var{file}.
35 When @file{filename.ly} is processed it will produce
36 @file{filename.tex} as output (or @file{filename.ps} for PostScript
37 output). If @file{filename.ly} contains more than one @code{\score}
38 block, then the rest of the scores will be output in numbered files,
39 starting with @file{filename-1.tex}. Several files can be specified;
40 they will each be processed independently. @footnote{The status of
41 GUILE is not reset after processing a @code{.ly} file, so be careful
42 not to change any system defaults from within Scheme.}
45 @section Command line options
47 The following options are supported:
51 @item -e,--evaluate=@var{expr}
52 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
53 Multiple @code{-e} options may be given, they will be evaluated
56 The expression will be evaluated in the @code{guile-user} module, so
57 if you want to use definitions in @var{expr}, use
60 lilypond -e '(define-public a 42)'
64 on the command-line, and include
67 #(use-modules (guile-user))
71 at the top of the @code{.ly} file.
73 @item -f,--format=@var{format}
74 which formats should be written. Choices are @code{svg}, @code{ps},
75 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
77 @item -b,--backend=@var{format}
78 the output format to use for the back-end. Choices are
81 for @TeX{} output, to be processed with La@TeX{}. If present, the file
82 @file{file.textmetrics} is read to determine text extents.
84 dump text strings to @file{.texstr} file, which can be run through
85 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
86 extents of strings of text.
89 @cindex PostScript output
91 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
92 these fonts is done. When using oriental character sets, this can
96 for encapsulated PostScript. This dumps every page (system) as a separate
97 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
98 all pages (systems) including fonts.
100 This mode is used by default by lilypond-book.
103 for SVG (Scalable Vector Graphics). This dumps every page as a separate
104 @file{SVG} file, with embedded fonts.
105 @cindex SVG (Scalable Vector Graphics)
106 You need a SVG viewer which supports embedded fonts, or a SVG
107 viewer which is able to replace the embedded fonts with OTF fonts.
108 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
109 (version 0.42 or later), after copying the OTF fonts in directory
110 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
112 for a dump of the raw, internal Scheme-based drawing commands.
116 @cindex output format, setting
118 @item -d,--define-default=@var{var}=@var{val}
119 This sets the internal program option @var{var} to the Scheme value
120 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
121 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
123 @cindex point and click, command line
132 -dpoint-and-click='#f'
135 Another notable option is
138 -dpaper-size=\"letter\"
142 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
144 Setting the @code{-dhelp} option will print a summary of the options
148 Show a summary of usage.
150 @item -H,--header=FIELD
151 Dump a header field to file BASENAME.FIELD
153 @item --include, -I=@var{directory}
154 Add @var{directory} to the search path for input files.
155 @cindex file searching
158 @item -i,--init=@var{file}
159 Set init file to @var{file} (default: @file{init.ly}).
161 @item -o,--output=@var{FILE}
162 Set the default output file to @var{FILE}. The appropriate
163 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
170 Generate DVI files. In this case, the @TeX{} backend should be
171 specified, i.e., @code{-b tex}.
174 Generate pictures of each page, in PNG format. This implies
175 @code{--ps}. The resolution in DPI of the image may be set with
181 Generate PDF. This implies @code{--ps}.
184 Generate an output file containing the titles and the first system
187 Do not generate the full pages. Useful in combination with
191 Do not trust the @code{.ly} input.
193 When LilyPond formatting is available through a web server, either the
194 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
195 @code{--safe} option will prevent inline Scheme code from wreaking
198 When LilyPond formatting is available through a web server, the
199 @code{--safe} @b{MUST} be passed. This will prevent inline Scheme
200 code from wreaking havoc, for example
206 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
211 The @code{--safe} option works by evaluating in-line Scheme
212 expressions in a special safe module. This safe module is derived from
213 GUILE @file{safe-r5rs} module, but adds a number of functions of the
214 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
216 In addition, @code{--safe} disallows @code{\include} directives and
217 disables the use of backslashes in @TeX{} strings.
219 In @code{--safe} mode, it is not possible to import LilyPond variables
222 @code{--safe} does @emph{not} detect resource overuse. It is still
223 possible to make the program hang indefinitely, for example by feeding
224 cyclic data structures into the backend. Therefore, if using LilyPond
225 on a publicly accessible webserver, the process should be limited in
226 both CPU and memory usage.
228 Note that @code{--safe} will prevent many useful LilyPond snippets from
229 being compiled. For a softer but secure alternative you can use the
230 @code{--jail} option.
233 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
234 Run LilyPond in a chroot jail.
236 The @code{--jail} option provides a more flexible alternative to
237 @code{--safe} when LilyPond formatting is available through a web
238 server or whenever LilyPond executes externally provided
241 The @code{--jail} option works by changing the root of LilyPond to
242 @var{jail} just before starting the actual compilation process. The user
243 and group are then changed to match those provided, and the current
244 directory is changed to @var{dir}. This setup guarantees that it is not
245 possible (at least in theory) to escape from the jail. Note that for
246 @code{--jail} to work LilyPond must be run as root, which is usually
247 accomplished in a safe way using @command{sudo}.
249 Setting up a jail is a slightly delicate matter, as we must be sure that
250 LilyPond is able to find whatever it needs to compile the source
251 @emph{inside the jail}. A typical setup comprises the following items:
254 @item Setting up a separate filesystem
255 A separate filesystem should be created for LilyPond, so that it can be
256 mounted with safe options such as @code{noexec}, @code{nodev}, and
257 @code{nosuid}. In this way, it is impossible to run executables or to
258 write directly to a device from LilyPond. If you do not want to create a
259 separate partition, just create a file of reasonable size and use it to
260 mount a loop device. A separate filesystem also guarantees that LilyPond
261 cannot write more space than it is allowed.
263 @item Setting up a separate user
264 A separate user and group (say, @samp{lily}/@samp{lily}) with low
265 privileges should be used to run LilyPond inside the jail. There should
266 be a single directory writable by this user, which should be passed in
269 @item Preparing the jail
270 LilyPond needs to read a number of files while running. All these files
271 are to be copied into the jail, under the same path they appear in the
272 real root filesystem. The entire content of the LilyPond installation
273 (e.g., @file{/usr/share/lilypond})
276 If problems arise, the simplest way to trace them down is to run
277 LilyPond using @command{strace}, which will allow you to determine which
280 @item Running LilyPond
281 In a jail mounted with @code{noexec} it is impossible to execute any external
282 program. Therefore LilyPond must be run with a backend that does not
283 require any such program. As we already mentioned, it must be also run
284 with superuser privileges (which, of course, it will lose immediately),
285 possibly using @command{sudo}. It is a good idea to limit the number of
286 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
287 -t}), and, if your operating system supports it, the amount of memory
288 that can be allocated.
293 Show version information.
296 Be verbose: show full paths of all files read, and give timing
300 Show the warranty with which GNU LilyPond comes. (It comes with
301 @strong{NO WARRANTY}!)
305 @section Environment variables
309 @cindex LILYPONDPREFIX
311 @code{Lilypond} recognizes the following environment variables:
314 This specifies a directory where locale messages and
315 data files will be looked up by default. The directory should contain
316 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
319 This selects the language for the warning messages.
321 @item LILYPOND_GC_YIELD
322 With this variable the memory footprint and performance can be
323 adjusted. It is a percentage tunes memory management behavior. With
324 higher values, the program uses more memory, with smaller values, it
325 uses more CPU time. The default value is @code{70}.
330 @node Notes for the MacOS X app
331 @section Notes for the MacOS X app
333 The scripts (such as lilypond-book, convert-ly, abc2ly, etc.) are also
334 included inside MacOS X .app. They can be run from the command line by
335 invoking them directly, e.g.
338 @var{path/to}/LilyPond.app/Contents/Resources/bin/convert-ly
341 Alternatively, you may add this directory to your path. Modify (or create)
342 a file called @code{.profile} in your home directory such that it contains
345 export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin
349 This file should end with a blank line.
351 Note that @var{path/to} will generally be @code{/Applications/}.
355 @section Error messages
357 @cindex error messages
358 Different error messages can appear while compiling a file:
364 Something looks suspect. If you are requesting something out of the
365 ordinary then you will understand the message, and can ignore it.
366 However, warnings usually indicate that something is wrong with the
370 Something is definitely wrong. The current processing step (parsing,
371 interpreting, or formatting) will be finished, but the next step will
377 Something is definitely wrong, and LilyPond cannot continue. This
378 happens rarely. The most usual cause is misinstalled fonts.
380 @cindex trace, Scheme
384 Errors that occur while executing Scheme code are caught by the Scheme
385 interpreter. If running with the verbose option (@code{-V} or
386 @code{--verbose}) then a call trace of the offending
387 function call is printed.
389 @cindex Programming error
390 @item Programming error
391 There was some internal inconsistency. These error messages are
392 intended to help the programmers and debuggers. Usually, they can be
393 ignored. Sometimes, they come in such big quantities that they obscure
394 other output. In this case, file a bug-report.
396 @item Aborted (core dumped)
397 This signals a serious programming error that caused the program to
398 crash. Such errors are considered critical. If you stumble on one,
404 @cindex errors, message format
405 If warnings and errors can
406 be linked to some part of the input file, then error messages have the
410 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
411 @var{offending input line}
414 A line-break is inserted in the offending line to indicate the column
415 where the error was found. For example,
418 test.ly:2:19: error: not a duration: 5:
423 These locations are LilyPond's best guess about where the warning or
424 error occurred, but (by their very nature) warnings and errors occur
425 when something unexpected happens. If you can't see an error in the
426 indicated line of your input file, try checking one or two lines
427 above the indicated position.
430 @node Updating files with convert-ly
431 @section Updating with @command{convert-ly}
433 @cindex Updating a LilyPond file
434 @cindex @code{convert-ly}
436 The LilyPond input syntax is routinely changed to simplify it or improve
437 it in different ways. As a side effect of this, the LilyPond interpreter
438 often is no longer compatible with older input files. To remedy this,
439 the program @command{convert-ly} can be used to deal with most of the
440 syntax changes between LilyPond versions.
442 It uses @code{\version} statements in the input files to detect the
443 old version number. In most cases, to upgrade your input file it is
444 sufficient to run@footnote{MacOS X users may execute this command
445 under the menu entry @samp{Compile > Update syntax}.}
448 convert-ly -e myfile.ly
451 If there are no changes to myfile.ly and file called myfile.ly.NEW
452 is created, then myfile.ly is already updated.
454 @command{convert-ly} always converts up to the last syntax change handled by
455 it. This means that the @code{\version} number left in the file is
456 usually lower than the version of @command{convert-ly} itself.
458 To upgrade LilyPond fragments in texinfo files, use
461 convert-ly --from=... --to=... --no-version *.itely
464 To upgrade many files at once, combine @code{convert-ly} with
465 standard unix commands. This example will upgrade all @code{.ly}
466 files in the current directory
469 for f in *.ly; do convert-ly -e $f; done;
472 In general, the program is invoked as follows:
475 convert-ly [@var{option}]@dots{} @var{file}@dots{}
479 The following options can be given:
483 Do an inline edit of the input file. Overrides @code{--output}.
485 @item -f,--from=@var{from-patchlevel}
486 Set the version to convert from. If this is not set, @command{convert-ly}
487 will guess this, on the basis of @code{\version} strings in the file.
489 @item -n,--no-version
490 Normally, @command{convert-ly} adds a @code{\version} indicator
491 to the output. Specifying this option suppresses this.
493 @item -s, --show-rules
494 Show all known conversions and exit.
496 @item --to=@var{to-patchlevel}
497 Set the goal version of the conversion. It defaults to the latest
507 Not all language changes are handled. Only one output option can be
511 @c We might want to make this a completely new section, along with more
512 @c info about how to upgrade old input files. -gp
515 Copy and paste from CVS, last updated
518 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
522 There are a few things that the convert-ly cannot handle. Here's a list of limitations
523 that the community has complained about.
525 This bug report structure has been chosen because convert-ly has a structure that doesn't
526 allow to smoothly implement all needed changes. Thus this is just a wishlist, placed
530 Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
531 To be able to run convert-ly
532 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
533 and similarly I replaced '>}' with '&}'. After the conversion, I could
534 then change back from '{ #' to '{ <' and from '& }' to '> }'.
535 Doesn't convert all text markup correctly. In the old markup syntax,
536 it was possible to group a number of markup commands together within parentheses, e.g.
537 -#'((bold italic) "string")
538 This will incorrectly be converted into
539 -\markup{{\bold italic} "string"}
540 instead of the correct
541 -\markup{\bold \italic "string"}
543 Doesn't handle \partcombine
544 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
546 \magnify isn't changed to \fontsize.
547 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
548 remove-tag isn't changed.
549 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
550 first-page-number isn't changed.
551 - first-page-number no => printfirst-page-number = ##f
552 Line breaks in header strings aren't converted.
553 - \\\\ as line break in \header strings => \markup \center-align <
554 "First Line" "Second Line" >
555 Crescendo and decrescendo terminators aren't converted.
559 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
561 \markup{ \center-align <{ ... }> } should be converted to:
562 \markup{ \center-align {\line { ... }} }
563 but now, \line is missing.
565 Special LaTeX characters such as $~$ in text are not converted to UTF8.
571 @section Reporting bugs
574 @cindex reporting bugs
576 If you have input that results in a crash or an erroneous output, then
577 that is a bug. We try to respond to bug-reports promptly, and fix them as
578 soon as possible. Help us by sending a defective input file, so we can
579 reproduce the problem. Send the report via:
582 @uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs}
588 @item Try to produce a very small input file which demonstrates the problem;
589 one or two bars is often sufficient to reproduce a bug. The smaller the
590 input file is, the easier it is for us to debug the problem.
592 @item Don't forget to tell which version of LilyPond you use!
594 @item If possible, use @code{ragged-right} in your example. This makes sure
595 that the bug can be reproduced in all paper sizes.
599 @c the bug database is not up to date enough.
601 When you've found a bug, have a look at our
602 @uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if
603 it has already been reported. You could also try to do a few searches
604 on the mailing list for the bug. Sometimes the bug will have already
605 been reported and a fix or workaround is already known.
608 Here is an example of a good bug report:
611 It seems that placement of accidentals is broken. In the
612 following example, the accidental touches the note head.
614 Using Mac OSX 10.3.7, lilypond 2.7.32
617 \layout { ragged-right = ##t }
624 \layout { ragged-right = ##t }
626 \override Accidental #'extra-offset = #'(1.0 . 0)
632 @section Editor support
637 @cindex modes, editor
638 @cindex syntax coloring
639 @cindex coloring, syntax
641 There is support from different editors for LilyPond.
645 Emacs has a @file{lilypond-mode}, which provides keyword
646 autocompletion, indentation, LilyPond specific parenthesis matching
647 and syntax coloring, handy compile short-cuts and reading LilyPond
648 manuals using Info. If @file{lilypond-mode} is not installed on your
649 platform, then read the
651 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
654 installation instructions.
659 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
660 with syntax coloring tools. For more information, refer to the
662 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
665 installation instructions.
671 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
672 This plugin includes a DVI viewer, integrated help and viewing via
673 GhostScript. It can be installed by doing @key{Plugins > Plugin
674 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
678 All these editors can be made to jump into the input file to the source
679 of a symbol in the graphical output. See @ref{Point and click}.