1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
5 @chapter Running LilyPond
7 This chapter details the technicalities of running LilyPond.
12 * Notes for the MacOS X app::
13 * Updating files with convert-ly::
20 @node Invoking lilypond
21 @section Invoking lilypond
22 @cindex Invoking LilyPond
23 @cindex command line options
24 @cindex options, command line
28 The @code{lilypond} executable may be called as follows from the command line.
31 lilypond [@var{option}]@dots{} @var{file}@dots{}
35 When invoked with a filename that has no extension, the @file{.ly}
36 extension is tried first. To read input from stdin, use a
37 dash (@code{-}) for @var{file}.
39 When @file{filename.ly} is processed it will produce
40 @file{filename.tex} as output (or @file{filename.ps} for PostScript
41 output). If @file{filename.ly} contains more than one @code{\score}
42 block, then the rest of the scores will be output in numbered files,
43 starting with @file{filename-1.tex}. Several files can be specified;
44 they will each be processed independently. @footnote{The status of
45 GUILE is not reset after processing a @code{.ly} file, so be careful
46 not to change any system defaults from within Scheme.}
49 @section Command line options
51 The following options are supported:
55 @item -e,--evaluate=@var{expr}
56 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
57 Multiple @code{-e} options may be given, they will be evaluated
60 The expression will be evaluated in the @code{guile-user} module, so
61 if you want to use definitions in @var{expr}, use
64 lilypond -e '(define-public a 42)'
68 on the command-line, and include
71 #(use-modules (guile-user))
75 at the top of the @code{.ly} file.
77 @item -f,--format=@var{format}
78 which formats should be written. Choices are @code{svg}, @code{ps},
79 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
81 @item -b,--backend=@var{format}
82 the output format to use for the back-end. Choices are
85 for @TeX{} output, to be processed with La@TeX{}. If present, the file
86 @file{file.textmetrics} is read to determine text extents.
88 dump text strings to @file{.texstr} file, which can be run through
89 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
90 extents of strings of text.
93 @cindex PostScript output
95 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
96 these fonts is done. When using oriental character sets, this can
100 for encapsulated PostScript. This dumps every page (system) as a separate
101 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
102 all pages (systems) including fonts.
104 This mode is used by default by lilypond-book.
107 for SVG (Scalable Vector Graphics). This dumps every page as a separate
108 @file{SVG} file, with embedded fonts.
109 @cindex SVG (Scalable Vector Graphics)
110 You need a SVG viewer which supports embedded fonts, or a SVG
111 viewer which is able to replace the embedded fonts with OTF fonts.
112 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
113 (version 0.42 or later), after copying the OTF fonts in directory
114 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
116 for a dump of the raw, internal Scheme-based drawing commands.
120 @cindex output format, setting
122 @item -d,--define-default=@var{var}=@var{val}
123 This sets the internal program option @var{var} to the Scheme value
124 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
125 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
127 @cindex point and click, command line
136 -dpoint-and-click='#f'
139 Another notable option is
142 -dpaper-size=\"letter\"
146 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
148 Setting the @code{-dhelp} option will print a summary of the options
152 Show a summary of usage.
154 @item -H,--header=FIELD
155 Dump a header field to file BASENAME.FIELD
157 @item --include, -I=@var{directory}
158 Add @var{directory} to the search path for input files.
159 @cindex file searching
162 @item -i,--init=@var{file}
163 Set init file to @var{file} (default: @file{init.ly}).
165 @item -o,--output=@var{FILE}
166 Set the default output file to @var{FILE}. The appropriate
167 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
174 Generate DVI files. In this case, the @TeX{} backend should be
175 specified, i.e., @code{-b tex}.
178 Generate pictures of each page, in PNG format. This implies
179 @code{--ps}. The resolution in DPI of the image may be set with
185 Generate PDF. This implies @code{--ps}.
188 Generate an output file containing the titles and the first system
191 Do not generate the full pages. Useful in combination with
195 Do not trust the @code{.ly} input.
197 When LilyPond formatting is available through a web server, either the
198 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
199 @code{--safe} option will prevent inline Scheme code from wreaking
202 When LilyPond formatting is available through a web server, the
203 @code{--safe} @b{MUST} be passed. This will prevent inline Scheme
204 code from wreaking havoc, for example
210 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
215 The @code{--safe} option works by evaluating in-line Scheme
216 expressions in a special safe module. This safe module is derived from
217 GUILE @file{safe-r5rs} module, but adds a number of functions of the
218 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
220 In addition, @code{--safe} disallows @code{\include} directives and
221 disables the use of backslashes in @TeX{} strings.
223 In @code{--safe} mode, it is not possible to import LilyPond variables
226 @code{--safe} does @emph{not} detect resource overuse. It is still
227 possible to make the program hang indefinitely, for example by feeding
228 cyclic data structures into the backend. Therefore, if using LilyPond
229 on a publicly accessible webserver, the process should be limited in
230 both CPU and memory usage.
232 Note that @code{--safe} will prevent many useful LilyPond snippets from
233 being compiled. For a softer but secure alternative you can use the
234 @code{--jail} option.
237 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
238 Run LilyPond in a chroot jail.
240 The @code{--jail} option provides a more flexible alternative to
241 @code{--safe} when LilyPond formatting is available through a web
242 server or whenever LilyPond executes externally provided
245 The @code{--jail} option works by changing the root of LilyPond to
246 @var{jail} just before starting the actual compilation process. The user
247 and group are then changed to match those provided, and the current
248 directory is changed to @var{dir}. This setup guarantees that it is not
249 possible (at least in theory) to escape from the jail. Note that for
250 @code{--jail} to work LilyPond must be run as root, which is usually
251 accomplished in a safe way using @command{sudo}.
253 Setting up a jail is a slightly delicate matter, as we must be sure that
254 LilyPond is able to find whatever it needs to compile the source
255 @emph{inside the jail}. A typical setup comprises the following items:
258 @item Setting up a separate filesystem
259 A separate filesystem should be created for LilyPond, so that it can be
260 mounted with safe options such as @code{noexec}, @code{nodev}, and
261 @code{nosuid}. In this way, it is impossible to run executables or to
262 write directly to a device from LilyPond. If you do not want to create a
263 separate partition, just create a file of reasonable size and use it to
264 mount a loop device. A separate filesystem also guarantees that LilyPond
265 cannot write more space than it is allowed.
267 @item Setting up a separate user
268 A separate user and group (say, @samp{lily}/@samp{lily}) with low
269 privileges should be used to run LilyPond inside the jail. There should
270 be a single directory writable by this user, which should be passed in
273 @item Preparing the jail
274 LilyPond needs to read a number of files while running. All these files
275 are to be copied into the jail, under the same path they appear in the
276 real root filesystem. The entire content of the LilyPond installation
277 (e.g., @file{/usr/share/lilypond})
280 If problems arise, the simplest way to trace them down is to run
281 LilyPond using @command{strace}, which will allow you to determine which
284 @item Running LilyPond
285 In a jail mounted with @code{noexec} it is impossible to execute any external
286 program. Therefore LilyPond must be run with a backend that does not
287 require any such program. As we already mentioned, it must be also run
288 with superuser privileges (which, of course, it will lose immediately),
289 possibly using @command{sudo}. It is a good idea to limit the number of
290 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
291 -t}), and, if your operating system supports it, the amount of memory
292 that can be allocated.
297 Show version information.
300 Be verbose: show full paths of all files read, and give timing
304 Show the warranty with which GNU LilyPond comes. (It comes with
305 @strong{NO WARRANTY}!)
309 @section Environment variables
313 @cindex LILYPONDPREFIX
315 @code{Lilypond} recognizes the following environment variables:
318 This specifies a directory where locale messages and
319 data files will be looked up by default. The directory should contain
320 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
323 This selects the language for the warning messages.
325 @item LILYPOND_GC_YIELD
326 With this variable the memory footprint and performance can be
327 adjusted. It is a percentage tunes memory management behavior. With
328 higher values, the program uses more memory, with smaller values, it
329 uses more CPU time. The default value is @code{70}.
334 @node Notes for the MacOS X app
335 @section Notes for the MacOS X app
337 The scripts (such as lilypond-book, convert-ly, abc2ly, etc.) are also
338 included inside MacOS X .app. They can be run from the command line by
339 invoking them directly, e.g.
342 @var{path/to}/LilyPond.app/Contents/Resources/bin/convert-ly
345 Alternatively, you may add this directory to your path. Modify (or create)
346 a file called @code{.profile} in your home directory such that it contains
349 export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin
353 This file should end with a blank line.
355 Note that @var{path/to} will generally be @code{/Applications/}.
358 @node Updating files with convert-ly
359 @section Updating with @command{convert-ly}
361 @cindex Updating a LilyPond file
362 @cindex @code{convert-ly}
364 The LilyPond input syntax is routinely changed to simplify it or improve
365 it in different ways. As a side effect of this, the LilyPond interpreter
366 often is no longer compatible with older input files. To remedy this,
367 the program @command{convert-ly} can be used to deal with most of the
368 syntax changes between LilyPond versions.
370 It uses @code{\version} statements in the input files to detect the
371 old version number. In most cases, to upgrade your input file it is
372 sufficient to run@footnote{MacOS X users may execute this command
373 under the menu entry @samp{Compile > Update syntax}.}
376 convert-ly -e myfile.ly
379 If there are no changes to myfile.ly and file called myfile.ly.NEW
380 is created, then myfile.ly is already updated.
382 @command{convert-ly} always converts up to the last syntax change handled by
383 it. This means that the @code{\version} number left in the file is
384 usually lower than the version of @command{convert-ly} itself.
386 To upgrade LilyPond fragments in texinfo files, use
389 convert-ly --from=... --to=... --no-version *.itely
392 To upgrade many files at once, combine @code{convert-ly} with
393 standard unix commands. This example will upgrade all @code{.ly}
394 files in the current directory
397 for f in *.ly; do convert-ly -e $f; done;
400 In general, the program is invoked as follows:
403 convert-ly [@var{option}]@dots{} @var{file}@dots{}
407 The following options can be given:
411 Do an inline edit of the input file. Overrides @code{--output}.
413 @item -f,--from=@var{from-patchlevel}
414 Set the version to convert from. If this is not set, @command{convert-ly}
415 will guess this, on the basis of @code{\version} strings in the file.
417 @item -n,--no-version
418 Normally, @command{convert-ly} adds a @code{\version} indicator
419 to the output. Specifying this option suppresses this.
421 @item -s, --show-rules
422 Show all known conversions and exit.
424 @item --to=@var{to-patchlevel}
425 Set the goal version of the conversion. It defaults to the latest
435 Not all language changes are handled. Only one output option can be
439 @c We might want to make this a completely new section, along with more
440 @c info about how to upgrade old input files. -gp
443 Copy and paste from CVS, last updated
446 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
450 There are a few things that the convert-ly cannot handle. Here's a list of limitations
451 that the community has complained about.
453 This bug report structure has been chosen because convert-ly has a structure that doesn't
454 allow to smoothly implement all needed changes. Thus this is just a wishlist, placed
458 Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
459 To be able to run convert-ly
460 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
461 and similarly I replaced '>}' with '&}'. After the conversion, I could
462 then change back from '{ #' to '{ <' and from '& }' to '> }'.
463 Doesn't convert all text markup correctly. In the old markup syntax,
464 it was possible to group a number of markup commands together within parentheses, e.g.
465 -#'((bold italic) "string")
466 This will incorrectly be converted into
467 -\markup{{\bold italic} "string"}
468 instead of the correct
469 -\markup{\bold \italic "string"}
471 Doesn't handle \partcombine
472 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
474 \magnify isn't changed to \fontsize.
475 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
476 remove-tag isn't changed.
477 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
478 first-page-number isn't changed.
479 - first-page-number no => printfirst-page-number = ##f
480 Line breaks in header strings aren't converted.
481 - \\\\ as line break in \header strings => \markup \center-align <
482 "First Line" "Second Line" >
483 Crescendo and decrescendo terminators aren't converted.
487 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
489 \markup{ \center-align <{ ... }> } should be converted to:
490 \markup{ \center-align {\line { ... }} }
491 but now, \line is missing.
493 Special LaTeX characters such as $~$ in text are not converted to UTF8.
499 @section Reporting bugs
502 @cindex reporting bugs
504 If you have input that results in a crash or an erroneous output, then
505 that is a bug. We try to respond to bug-reports promptly, and fix them as
506 soon as possible. Help us by sending a defective input file, so we can
507 reproduce the problem. Send the report via:
510 @uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs}
516 @item Try to produce a very small input file which demonstrates the problem;
517 one or two bars is often sufficient to reproduce a bug. The smaller the
518 input file is, the easier it is for us to debug the problem.
520 @item Don't forget to tell which version of LilyPond you use!
522 @item If possible, use @code{ragged-right} in your example. This makes sure
523 that the bug can be reproduced in all paper sizes.
527 @c the bug database is not up to date enough.
529 When you've found a bug, have a look at our
530 @uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if
531 it has already been reported. You could also try to do a few searches
532 on the mailing list for the bug. Sometimes the bug will have already
533 been reported and a fix or workaround is already known.
536 Here is an example of a good bug report:
539 It seems that placement of accidentals is broken. In the
540 following example, the accidental touches the note head.
542 Using Mac OSX 10.3.7, lilypond 2.7.32
545 \layout { ragged-right = ##t }
552 \layout { ragged-right = ##t }
554 \override Accidental #'extra-offset = #'(1.0 . 0)
560 @section Error messages
562 @cindex error messages
563 Different error messages can appear while compiling a file:
569 Something looks suspect. If you are requesting something out of the
570 ordinary then you will understand the message, and can ignore it.
571 However, warnings usually indicate that something is wrong with the
575 Something is definitely wrong. The current processing step (parsing,
576 interpreting, or formatting) will be finished, but the next step will
582 Something is definitely wrong, and LilyPond cannot continue. This
583 happens rarely. The most usual cause is misinstalled fonts.
585 @cindex trace, Scheme
589 Errors that occur while executing Scheme code are caught by the Scheme
590 interpreter. If running with the verbose option (@code{-V} or
591 @code{--verbose}) then a call trace of the offending
592 function call is printed.
594 @cindex Programming error
595 @item Programming error
596 There was some internal inconsistency. These error messages are
597 intended to help the programmers and debuggers. Usually, they can be
598 ignored. Sometimes, they come in such big quantities that they obscure
599 other output. In this case, file a bug-report.
601 @item Aborted (core dumped)
602 This signals a serious programming error that caused the program to
603 crash. Such errors are considered critical. If you stumble on one,
609 @cindex errors, message format
610 If warnings and errors can
611 be linked to some part of the input file, then error messages have the
615 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
616 @var{offending input line}
619 A line-break is inserted in the offending line to indicate the column
620 where the error was found. For example,
623 test.ly:2:19: error: not a duration: 5:
628 These locations are LilyPond's best guess about where the warning or
629 error occurred, but (by their very nature) warnings and errors occur
630 when something unexpected happens. If you can't see an error in the
631 indicated line of your input file, try checking one or two lines
632 above the indicated position.
636 @section Editor support
641 @cindex modes, editor
642 @cindex syntax coloring
643 @cindex coloring, syntax
645 There is support from different editors for LilyPond.
649 Emacs has a @file{lilypond-mode}, which provides keyword
650 autocompletion, indentation, LilyPond specific parenthesis matching
651 and syntax coloring, handy compile short-cuts and reading LilyPond
652 manuals using Info. If @file{lilypond-mode} is not installed on your
653 platform, then read the
655 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
658 installation instructions.
663 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
664 with syntax coloring tools. For more information, refer to the
666 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
669 installation instructions.
675 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
676 This plugin includes a DVI viewer, integrated help and viewing via
677 GhostScript. It can be installed by doing @key{Plugins > Plugin
678 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
682 All these editors can be made to jump into the input file to the source
683 of a symbol in the graphical output. See @ref{Point and click}.
686 @node Point and click
687 @section Point and click
688 @cindex point and click
691 Point and click lets you find notes in the input by clicking on them
692 in the PDF viewer. This makes it easier to find input that causes
693 some error in the sheet music.
695 When this functionality is active, LilyPond adds hyperlinks to the PDF
696 file. These hyperlinks are sent to the web-browser, which opens a
697 text-editor with the cursor in the right place.
699 To make this chain work, you should configure your PDF viewer to
700 follow hyperlinks using the @file{lilypond-invoke-editor} script
701 supplied with LilyPond.
703 For Xpdf on Unix, the following should be present in
704 @file{xpdfrc}@footnote{On unix, this file is found either in
705 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
708 urlCommand "lilypond-invoke-editor %s"
711 The program @file{lilypond-invoke-editor} is a small helper
712 program. It will invoke an editor for the special @code{textedit}
713 URIs, and run a web browser for others. It tests the environment
714 variable @code{EDITOR} for the following patterns,
720 emacsclient --no-wait +@var{line}:@var{column} @var{file}
725 gvim --remote +:@var{line}:norm@var{char} @var{file}
731 nc -noask +@var{line} @var{file}'
735 The environment variable @code{LYEDITOR} is used to override this. It
736 contains the command line to start the editor, where @code{%(file)s},
737 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
738 and line respectively. The setting
741 emacsclient --no-wait +%(line)s:%(column)s %(file)s
745 for @code{LYEDITOR} is equivalent to the standard emacsclient
749 @cindex file size, output
751 The point and click links enlarge the output files significantly. For
752 reducing the size of PDF and PS files, point and click may be switched
756 #(ly:set-option 'point-and-click #f)
760 in a @file{.ly} file. Alternately, you may pass this as an command-line
764 lilypond -dno-point-and-click file.ly