1 @c -*- coding: utf-8; mode: texinfo; -*-
3 @chapter Running LilyPond
5 This chapter details the technicalities of running LilyPond.
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 @item -f,--format=@var{format}
57 which formats should be written. Choices are @code{svg}, @code{ps},
58 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
60 @item -b,--backend=@var{format}
61 the output format to use for the back-end. Choices are
64 for @TeX{} output, to be processed with La@TeX{}. If present, the file
65 @file{file.textmetrics} is read to determine text extents.
67 dump text strings to @file{.texstr} file, which can be run through
68 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
69 extents of strings of text.
72 @cindex PostScript output
74 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
75 these fonts is done. When using oriental character sets, this can
79 for encapsulated PostScript. This dumps every page (system) as a separate
80 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
81 all pages (systems) including fonts.
83 This mode is used by default by lilypond-book.
86 for SVG (Scalable Vector Graphics). This dumps every page as a separate
87 @file{SVG} file, with embedded fonts.
88 @cindex SVG (Scalable Vector Graphics)
89 You need a SVG viewer which supports embedded fonts, or a SVG
90 viewer which is able to replace the embedded fonts with OTF fonts.
91 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
92 (version 0.42 or later), after copying the OTF fonts in directory
93 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
95 for a dump of the raw, internal Scheme-based drawing commands.
99 @cindex output format, setting
101 @item -d,--define-default=@var{var}=@var{val}
102 This sets the internal program option @var{var} to the Scheme value
103 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
104 switch off an option, @code{no-} may be prefixed to @var{var}, eg.
112 -dpoint-and-click='#f'
115 @cindex point and click
117 Setting the @code{help} option will print a summary of the options
121 Show a summary of usage.
123 @item -H,--header=FIELD
124 Dump a header field to file BASENAME.FIELD
126 @item --include, -I=@var{directory}
127 Add @var{directory} to the search path for input files.
128 @cindex file searching
131 @item -i,--init=@var{file}
132 Set init file to @var{file} (default: @file{init.ly}).
134 @item -o,--output=@var{FILE}
135 Set the default output file to @var{FILE}. The appropriate
136 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
143 Generate DVI files. In this case, the @TeX{} backend should be
144 specified, i.e., @code{-b tex}.
147 Generate pictures of each page, in PNG format. This implies
148 @code{--ps}. The resolution in DPI of the image may be set with
154 Generate PDF. This implies @code{--ps}.
157 Generate an output file containing the titles and the first system
160 Do not generate the full pages. Useful in combination with
164 Do not trust the @code{.ly} input.
166 When LilyPond formatting is available through a web server, either the
167 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
168 @code{--safe} option will prevent inline Scheme code from wreaking
171 When LilyPond formatting is available through a web server, the
172 @code{--safe} @b{MUST} be passed. This will prevent inline Scheme
173 code from wreaking havoc, for example
179 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
184 The @code{--safe} option works by evaluating in-line Scheme
185 expressions in a special safe module. This safe module is derived from
186 GUILE @file{safe-r5rs} module, but adds a number of functions of the
187 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
189 In addition, @code{--safe} disallows @code{\include} directives and
190 disables the use of backslashes in @TeX{} strings.
192 In @code{--safe} mode, it is not possible to import LilyPond variables
195 @code{--safe} does @emph{not} detect resource overuse. It is still
196 possible to make the program hang indefinitely, for example by feeding
197 cyclic data structures into the backend. Therefore, if using LilyPond
198 on a publicly accessible webserver, the process should be limited in
199 both CPU and memory usage.
201 Note that @code{--safe} will prevent many useful LilyPond snippets from
202 being compiled. For a softer but secure alternative you can use the
203 @code{--jail} option.
206 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
207 Run LilyPond in a chroot jail.
209 The @code{--jail} option provides a more flexible alternative to
210 @code{--safe} when LilyPond formatting is available through a web
211 server or whenever LilyPond executes externally provided
214 The @code{--jail} option works by changing the root of LilyPond to
215 @var{jail} just before starting the actual compilation process. The user
216 and group are then changed to match those provided, and the current
217 directory is changed to @var{dir}. This setup guarantees that it is not
218 possible (at least in theory) to escape from the jail. Note that for
219 @code{--jail} to work LilyPond must be run as root, which is usually
220 accomplished in a safe way using @command{sudo}.
222 Setting up a jail is a slightly delicate matter, as we must be sure that
223 LilyPond is able to find whatever it needs to compile the source
224 @emph{inside the jail}. A typical setup comprises the following items:
227 @item Setting up a separate filesystem
228 A separate filesystem should be created for LilyPond, so that it can be
229 mounted with safe options such as @code{noexec}, @code{nodev}, and
230 @code{nosuid}. In this way, it is impossible to run executables or to
231 write directly to a device from LilyPond. If you do not want to create a
232 separate partition, just create a file of reasonable size and use it to
233 mount a loop device. A separate filesystem also guarantees that LilyPond
234 cannot write more space than it is allowed.
236 @item Setting up a separate user
237 A separate user and group (say, @samp{lily}/@samp{lily}) with low
238 privileges should be used to run LilyPond inside the jail. There should
239 be a single directory writable by this user, which should be passed in
242 @item Preparing the jail
243 LilyPond needs to read a number of files while running. All these files
244 are to be copied into the jail, under the same path they apper in the
245 real root filesystem. The entire content of the LilyPond installation
246 (e.g., @file{/usr/share/lilypond})
249 If problems arise, the simplest way to trace them down is to run
250 LilyPond using @command{strace}, which will allow you to determine which
253 @item Running LilyPond
254 In a jail mounted with @code{noexec} it is impossible to execute any external
255 program. Therefore LilyPond must be run with a backend that does not
256 require any such program. As we already mentioned, it must be also run
257 with superuser privileges (which, of course, it will lose immediately),
258 possibly using @command{sudo}. It is a good idea to limit the number of
259 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
260 -t}), and, if your operating system supports it, the amount of memory
261 that can be allocated.
266 Show version information.
269 Be verbose: show full paths of all files read, and give timing
273 Show the warranty with which GNU LilyPond comes. (It comes with
274 @strong{NO WARRANTY}!)
278 @section Environment variables
282 @cindex LILYPONDPREFIX
284 @code{Lilypond} recognizes the following environment variables:
287 This specifies a directory where locale messages and
288 data files will be looked up by default. The directory should contain
289 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
292 This selects the language for the warning messages.
294 @item LILYPOND_GC_YIELD
295 With this variable the memory footprint and performance can be
296 adjusted. It is a percentage tunes memory management behavior. With
297 higher values, the program uses more memory, with smaller values, it
298 uses more CPU time. The default value is @code{70}.
304 @section Error messages
306 @cindex error messages
307 Different error messages can appear while compiling a file:
313 Something looks suspect. If you are requesting something out of the
314 ordinary then you will understand the message, and can ignore it.
315 However, warnings usually indicate that something is wrong with the
319 Something is definitely wrong. The current processing step (parsing,
320 interpreting, or formatting) will be finished, but the next step will
326 Something is definitely wrong, and LilyPond cannot continue. This
327 happens rarely. The most usual cause is misinstalled fonts.
329 @cindex trace, Scheme
333 Errors that occur while executing Scheme code are caught by the Scheme
334 interpreter. If running with the verbose option (@code{-V} or
335 @code{--verbose}) then a call trace of the offending
336 function call is printed.
338 @cindex Programming error
339 @item Programming error
340 There was some internal inconsistency. These error messages are
341 intended to help the programmers and debuggers. Usually, they can be
342 ignored. Sometimes, they come in such big quantities that they obscure
343 other output. In this case, file a bug-report.
345 @item Aborted (core dumped)
346 This signals a serious programming error that caused the program to
347 crash. Such errors are considered critical. If you stumble on one,
353 @cindex errors, message format
354 If warnings and errors can
355 be linked to some part of the input file, then error messages have the
359 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
360 @var{offending input line}
363 A line-break is inserted in the offending line to indicate the column
364 where the error was found. For example,
367 test.ly:2:19: error: not a duration: 5:
372 These locations are LilyPond's best guess about where the warning or
373 error occured, but (by their very nature) warnings and errors occur
374 when something unexpected happens. If you can't see an error in the
375 indicated line of your input file, try checking one or two lines
376 above the indicated position.
379 @node Updating files with convert-ly
380 @section Updating with @command{convert-ly}
382 @cindex Updating a LilyPond file
383 @cindex @code{convert-ly}
385 The LilyPond input syntax is routinely changed to simplify it or improve
386 it in different ways. As a side effect of this, the LilyPond interpreter
387 often is no longer compatible with older input files. To remedy this,
388 the program @command{convert-ly} can be used to deal with most of the
389 syntax changes between LilyPond versions.
391 It uses @code{\version} statements in the input files to detect the
392 old version number. In most cases, to upgrade your input file it is
393 sufficient to run@footnote{MacOS X users may execute this command
394 under the menu entry @samp{Compile > Update syntax}.}
397 convert-ly -e myfile.ly
400 If there are no changes to myfile.ly and file called myfile.ly.NEW
401 is created, then myfile.ly is already updated.
403 @command{convert-ly} always converts up to the last syntax change handled by
404 it. This means that the @code{\version} number left in the file is
405 usually lower than the version of @command{convert-ly} itself.
407 To upgrade LilyPond fragments in texinfo files, use
410 convert-ly --from=... --to=... --no-version *.itely
413 To upgrade many files at once, combine @code{convert-ly} with
414 standard unix commands. This example will upgrade all @code{.ly}
415 files in the current directory
418 for f in *.ly; do convert-ly -e $f; done;
421 In general, the program is invoked as follows:
424 convert-ly [@var{option}]@dots{} @var{file}@dots{}
428 The following options can be given:
432 Do an inline edit of the input file. Overrides @code{--output}.
434 @item -f,--from=@var{from-patchlevel}
435 Set the version to convert from. If this is not set, @command{convert-ly}
436 will guess this, on the basis of @code{\version} strings in the file.
438 @item -n,--no-version
439 Normally, @command{convert-ly} adds a @code{\version} indicator
440 to the output. Specifying this option suppresses this.
442 @item -s, --show-rules
443 Show all known conversions and exit.
445 @item --to=@var{to-patchlevel}
446 Set the goal version of the conversion. It defaults to the latest
456 Not all language changes are handled. Only one output option can be
460 @c We might want to make this a completely new section, along with more
461 @c info about how to upgrade old input files. -gp
464 Copy and paste from CVS, last updated
467 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
471 There are a few things that the convert-ly cannot handle. Here's a list of limitations
472 that the community has complained about.
474 This bug report structure has been chosen because convert-ly has a structure that doesn't
475 allow to smoothly implement all needed changes. Thus this is just a wishlist, placed
479 Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
480 To be able to run convert-ly
481 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
482 and similarly I replaced '>}' with '&}'. After the conversion, I could
483 then change back from '{ #' to '{ <' and from '& }' to '> }'.
484 Doesn't convert all text markup correctly. In the old markup syntax,
485 it was possible to group a number of markup commands together within parentheses, e.g.
486 -#'((bold italic) "string")
487 This will incorrectly be converted into
488 -\markup{{\bold italic} "string"}
489 instead of the correct
490 -\markup{\bold \italic "string"}
492 Doesn't handle \partcombine
493 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
495 \magnify isn't changed to \fontsize.
496 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
497 remove-tag isn't changed.
498 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
499 first-page-number isn't changed.
500 - first-page-number no => printfirst-page-number = ##f
501 Line breaks in header strings aren't converted.
502 - \\\\ as line break in \header strings => \markup \center-align <
503 "First Line" "Second Line" >
504 Crescendo and decrescendo terminators aren't converted.
508 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
510 \markup{ \center-align <{ ... }> } should be converted to:
511 \markup{ \center-align {\line { ... }} }
512 but now, \line is missing.
514 Special LaTeX characters such as $~$ in text are not converted to UTF8.
520 @section Reporting bugs
523 @cindex reporting bugs
525 If you have input that results in a crash or an erroneous output, then
526 that is a bug. We try to respond to bug-reports promptly, and fix them as
527 soon as possible. Help us by sending a defective input file, so we can
528 reproduce the problem. Make it small, so we can easily debug the
529 problem. Don't forget to tell which version of LilyPond you use! Send
533 @uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs}
537 @c the bug database is not up to date enough.
539 When you've found a bug, have a look at our
540 @uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if
541 it has already been reported. You could also try to do a few searches
542 on the mailing list for the bug. Sometimes the bug will have already
543 been reported and a fix or workaround is already known.
546 Here is an example of a good bug report:
549 It seems that placement of accidentals is broken. In the
550 following example, the accidental touches the note head.
552 Using Mac OSX 10.3.7, fink package lilypond-devel
563 \override Accidental #'extra-offset = #'(1.0 . 0)
569 @section Editor support
574 @cindex modes, editor
575 @cindex syntax coloring
576 @cindex coloring, syntax
578 There is support from different editors for LilyPond.
582 Emacs has a @file{lilypond-mode}, which provides keyword
583 autocompletion, indentation, LilyPond specific parenthesis matching
584 and syntax coloring, handy compile short-cuts and reading LilyPond
585 manuals using Info. If @file{lilypond-mode} is not installed on your
586 platform, then read the
588 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
591 installation instructions.
596 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
597 with syntax coloring tools. For more information, refer to the
599 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
602 installation instructions.
608 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
609 This plugin includes a DVI viewer, integrated help and viewing via
610 GhostScript. It can be installed by doing @key{Plugins > Plugin
611 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
615 All these editors can be made to jump into the input file to the source
616 of a symbol in the graphical output. See @ref{Point and click}.