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 @item -f,--format=@var{format}
58 which formats should be written. Choices are @code{svg}, @code{ps},
59 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
61 @item -b,--backend=@var{format}
62 the output format to use for the back-end. Choices are
65 for @TeX{} output, to be processed with La@TeX{}. If present, the file
66 @file{file.textmetrics} is read to determine text extents.
68 dump text strings to @file{.texstr} file, which can be run through
69 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
70 extents of strings of text.
73 @cindex PostScript output
75 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
76 these fonts is done. When using oriental character sets, this can
80 for encapsulated PostScript. This dumps every page (system) as a separate
81 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
82 all pages (systems) including fonts.
84 This mode is used by default by lilypond-book.
87 for SVG (Scalable Vector Graphics). This dumps every page as a separate
88 @file{SVG} file, with embedded fonts.
89 @cindex SVG (Scalable Vector Graphics)
90 You need a SVG viewer which supports embedded fonts, or a SVG
91 viewer which is able to replace the embedded fonts with OTF fonts.
92 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
93 (version 0.42 or later), after copying the OTF fonts in directory
94 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
96 for a dump of the raw, internal Scheme-based drawing commands.
100 @cindex output format, setting
102 @item -d,--define-default=@var{var}=@var{val}
103 This sets the internal program option @var{var} to the Scheme value
104 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
105 switch off an option, @code{no-} may be prefixed to @var{var}, eg.
113 -dpoint-and-click='#f'
116 @cindex point and click
118 Setting the @code{help} option will print a summary of the options
122 Show a summary of usage.
124 @item -H,--header=FIELD
125 Dump a header field to file BASENAME.FIELD
127 @item --include, -I=@var{directory}
128 Add @var{directory} to the search path for input files.
129 @cindex file searching
132 @item -i,--init=@var{file}
133 Set init file to @var{file} (default: @file{init.ly}).
135 @item -o,--output=@var{FILE}
136 Set the default output file to @var{FILE}. The appropriate
137 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
144 Generate DVI files. In this case, the @TeX{} backend should be
145 specified, i.e., @code{-b tex}.
148 Generate pictures of each page, in PNG format. This implies
149 @code{--ps}. The resolution in DPI of the image may be set with
155 Generate PDF. This implies @code{--ps}.
158 Generate an output file containing the titles and the first system
161 Do not generate the full pages. Useful in combination with
165 Do not trust the @code{.ly} input.
167 When LilyPond formatting is available through a web server, either the
168 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
169 @code{--safe} option will prevent inline Scheme code from wreaking
172 When LilyPond formatting is available through a web server, the
173 @code{--safe} @b{MUST} be passed. This will prevent inline Scheme
174 code from wreaking havoc, for example
180 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
185 The @code{--safe} option works by evaluating in-line Scheme
186 expressions in a special safe module. This safe module is derived from
187 GUILE @file{safe-r5rs} module, but adds a number of functions of the
188 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
190 In addition, @code{--safe} disallows @code{\include} directives and
191 disables the use of backslashes in @TeX{} strings.
193 In @code{--safe} mode, it is not possible to import LilyPond variables
196 @code{--safe} does @emph{not} detect resource overuse. It is still
197 possible to make the program hang indefinitely, for example by feeding
198 cyclic data structures into the backend. Therefore, if using LilyPond
199 on a publicly accessible webserver, the process should be limited in
200 both CPU and memory usage.
202 Note that @code{--safe} will prevent many useful LilyPond snippets from
203 being compiled. For a softer but secure alternative you can use the
204 @code{--jail} option.
207 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
208 Run LilyPond in a chroot jail.
210 The @code{--jail} option provides a more flexible alternative to
211 @code{--safe} when LilyPond formatting is available through a web
212 server or whenever LilyPond executes externally provided
215 The @code{--jail} option works by changing the root of LilyPond to
216 @var{jail} just before starting the actual compilation process. The user
217 and group are then changed to match those provided, and the current
218 directory is changed to @var{dir}. This setup guarantees that it is not
219 possible (at least in theory) to escape from the jail. Note that for
220 @code{--jail} to work LilyPond must be run as root, which is usually
221 accomplished in a safe way using @command{sudo}.
223 Setting up a jail is a slightly delicate matter, as we must be sure that
224 LilyPond is able to find whatever it needs to compile the source
225 @emph{inside the jail}. A typical setup comprises the following items:
228 @item Setting up a separate filesystem
229 A separate filesystem should be created for LilyPond, so that it can be
230 mounted with safe options such as @code{noexec}, @code{nodev}, and
231 @code{nosuid}. In this way, it is impossible to run executables or to
232 write directly to a device from LilyPond. If you do not want to create a
233 separate partition, just create a file of reasonable size and use it to
234 mount a loop device. A separate filesystem also guarantees that LilyPond
235 cannot write more space than it is allowed.
237 @item Setting up a separate user
238 A separate user and group (say, @samp{lily}/@samp{lily}) with low
239 privileges should be used to run LilyPond inside the jail. There should
240 be a single directory writable by this user, which should be passed in
243 @item Preparing the jail
244 LilyPond needs to read a number of files while running. All these files
245 are to be copied into the jail, under the same path they apper in the
246 real root filesystem. The entire content of the LilyPond installation
247 (e.g., @file{/usr/share/lilypond})
250 If problems arise, the simplest way to trace them down is to run
251 LilyPond using @command{strace}, which will allow you to determine which
254 @item Running LilyPond
255 In a jail mounted with @code{noexec} it is impossible to execute any external
256 program. Therefore LilyPond must be run with a backend that does not
257 require any such program. As we already mentioned, it must be also run
258 with superuser privileges (which, of course, it will lose immediately),
259 possibly using @command{sudo}. It is a good idea to limit the number of
260 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
261 -t}), and, if your operating system supports it, the amount of memory
262 that can be allocated.
267 Show version information.
270 Be verbose: show full paths of all files read, and give timing
274 Show the warranty with which GNU LilyPond comes. (It comes with
275 @strong{NO WARRANTY}!)
279 @section Environment variables
283 @cindex LILYPONDPREFIX
285 @code{Lilypond} recognizes the following environment variables:
288 This specifies a directory where locale messages and
289 data files will be looked up by default. The directory should contain
290 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
293 This selects the language for the warning messages.
295 @item LILYPOND_GC_YIELD
296 With this variable the memory footprint and performance can be
297 adjusted. It is a percentage tunes memory management behavior. With
298 higher values, the program uses more memory, with smaller values, it
299 uses more CPU time. The default value is @code{70}.
304 @node Notes for the MacOS X app
305 @section Notes for the MacOS X app
307 The scripts (such as lilypond-book, convert-ly, abc2ly, etc.) are also
308 included inside MacOS X .app. They can be run from the command line by
309 invoking them directly, e.g.
312 @var{path/to}/LilyPond.app/Contents/Resources/bin/convert-ly
316 @section Error messages
318 @cindex error messages
319 Different error messages can appear while compiling a file:
325 Something looks suspect. If you are requesting something out of the
326 ordinary then you will understand the message, and can ignore it.
327 However, warnings usually indicate that something is wrong with the
331 Something is definitely wrong. The current processing step (parsing,
332 interpreting, or formatting) will be finished, but the next step will
338 Something is definitely wrong, and LilyPond cannot continue. This
339 happens rarely. The most usual cause is misinstalled fonts.
341 @cindex trace, Scheme
345 Errors that occur while executing Scheme code are caught by the Scheme
346 interpreter. If running with the verbose option (@code{-V} or
347 @code{--verbose}) then a call trace of the offending
348 function call is printed.
350 @cindex Programming error
351 @item Programming error
352 There was some internal inconsistency. These error messages are
353 intended to help the programmers and debuggers. Usually, they can be
354 ignored. Sometimes, they come in such big quantities that they obscure
355 other output. In this case, file a bug-report.
357 @item Aborted (core dumped)
358 This signals a serious programming error that caused the program to
359 crash. Such errors are considered critical. If you stumble on one,
365 @cindex errors, message format
366 If warnings and errors can
367 be linked to some part of the input file, then error messages have the
371 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
372 @var{offending input line}
375 A line-break is inserted in the offending line to indicate the column
376 where the error was found. For example,
379 test.ly:2:19: error: not a duration: 5:
384 These locations are LilyPond's best guess about where the warning or
385 error occured, but (by their very nature) warnings and errors occur
386 when something unexpected happens. If you can't see an error in the
387 indicated line of your input file, try checking one or two lines
388 above the indicated position.
391 @node Updating files with convert-ly
392 @section Updating with @command{convert-ly}
394 @cindex Updating a LilyPond file
395 @cindex @code{convert-ly}
397 The LilyPond input syntax is routinely changed to simplify it or improve
398 it in different ways. As a side effect of this, the LilyPond interpreter
399 often is no longer compatible with older input files. To remedy this,
400 the program @command{convert-ly} can be used to deal with most of the
401 syntax changes between LilyPond versions.
403 It uses @code{\version} statements in the input files to detect the
404 old version number. In most cases, to upgrade your input file it is
405 sufficient to run@footnote{MacOS X users may execute this command
406 under the menu entry @samp{Compile > Update syntax}.}
409 convert-ly -e myfile.ly
412 If there are no changes to myfile.ly and file called myfile.ly.NEW
413 is created, then myfile.ly is already updated.
415 @command{convert-ly} always converts up to the last syntax change handled by
416 it. This means that the @code{\version} number left in the file is
417 usually lower than the version of @command{convert-ly} itself.
419 To upgrade LilyPond fragments in texinfo files, use
422 convert-ly --from=... --to=... --no-version *.itely
425 To upgrade many files at once, combine @code{convert-ly} with
426 standard unix commands. This example will upgrade all @code{.ly}
427 files in the current directory
430 for f in *.ly; do convert-ly -e $f; done;
433 In general, the program is invoked as follows:
436 convert-ly [@var{option}]@dots{} @var{file}@dots{}
440 The following options can be given:
444 Do an inline edit of the input file. Overrides @code{--output}.
446 @item -f,--from=@var{from-patchlevel}
447 Set the version to convert from. If this is not set, @command{convert-ly}
448 will guess this, on the basis of @code{\version} strings in the file.
450 @item -n,--no-version
451 Normally, @command{convert-ly} adds a @code{\version} indicator
452 to the output. Specifying this option suppresses this.
454 @item -s, --show-rules
455 Show all known conversions and exit.
457 @item --to=@var{to-patchlevel}
458 Set the goal version of the conversion. It defaults to the latest
468 Not all language changes are handled. Only one output option can be
472 @c We might want to make this a completely new section, along with more
473 @c info about how to upgrade old input files. -gp
476 Copy and paste from CVS, last updated
479 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
483 There are a few things that the convert-ly cannot handle. Here's a list of limitations
484 that the community has complained about.
486 This bug report structure has been chosen because convert-ly has a structure that doesn't
487 allow to smoothly implement all needed changes. Thus this is just a wishlist, placed
491 Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
492 To be able to run convert-ly
493 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
494 and similarly I replaced '>}' with '&}'. After the conversion, I could
495 then change back from '{ #' to '{ <' and from '& }' to '> }'.
496 Doesn't convert all text markup correctly. In the old markup syntax,
497 it was possible to group a number of markup commands together within parentheses, e.g.
498 -#'((bold italic) "string")
499 This will incorrectly be converted into
500 -\markup{{\bold italic} "string"}
501 instead of the correct
502 -\markup{\bold \italic "string"}
504 Doesn't handle \partcombine
505 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
507 \magnify isn't changed to \fontsize.
508 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
509 remove-tag isn't changed.
510 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
511 first-page-number isn't changed.
512 - first-page-number no => printfirst-page-number = ##f
513 Line breaks in header strings aren't converted.
514 - \\\\ as line break in \header strings => \markup \center-align <
515 "First Line" "Second Line" >
516 Crescendo and decrescendo terminators aren't converted.
520 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
522 \markup{ \center-align <{ ... }> } should be converted to:
523 \markup{ \center-align {\line { ... }} }
524 but now, \line is missing.
526 Special LaTeX characters such as $~$ in text are not converted to UTF8.
532 @section Reporting bugs
535 @cindex reporting bugs
537 If you have input that results in a crash or an erroneous output, then
538 that is a bug. We try to respond to bug-reports promptly, and fix them as
539 soon as possible. Help us by sending a defective input file, so we can
540 reproduce the problem. Make it small, so we can easily debug the
541 problem. Don't forget to tell which version of LilyPond you use! Send
545 @uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs}
549 @c the bug database is not up to date enough.
551 When you've found a bug, have a look at our
552 @uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if
553 it has already been reported. You could also try to do a few searches
554 on the mailing list for the bug. Sometimes the bug will have already
555 been reported and a fix or workaround is already known.
558 Here is an example of a good bug report:
561 It seems that placement of accidentals is broken. In the
562 following example, the accidental touches the note head.
564 Using Mac OSX 10.3.7, fink package lilypond-devel
575 \override Accidental #'extra-offset = #'(1.0 . 0)
581 @section Editor support
586 @cindex modes, editor
587 @cindex syntax coloring
588 @cindex coloring, syntax
590 There is support from different editors for LilyPond.
594 Emacs has a @file{lilypond-mode}, which provides keyword
595 autocompletion, indentation, LilyPond specific parenthesis matching
596 and syntax coloring, handy compile short-cuts and reading LilyPond
597 manuals using Info. If @file{lilypond-mode} is not installed on your
598 platform, then read the
600 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
603 installation instructions.
608 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
609 with syntax coloring tools. For more information, refer to the
611 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
614 installation instructions.
620 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
621 This plugin includes a DVI viewer, integrated help and viewing via
622 GhostScript. It can be installed by doing @key{Plugins > Plugin
623 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
627 All these editors can be made to jump into the input file to the source
628 of a symbol in the graphical output. See @ref{Point and click}.