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.
9 Some of these commands are run from the command-line. By
10 ``command-line'', we mean the command
11 line in the operating system. Windows users
12 might be more familiar with the terms ``DOS shell'' or
13 ``command shell''; OSX users might be more familiar with the
14 terms ``terminal'' or ``console''. OSX users should also
15 consult @ref{Notes for the MacOS X app}.
18 this part of an operating system is outside the scope of this
19 manual; please consult other documentation on this topic if
20 you are unfamiliar with the command-line.
24 * Notes for the MacOS X app::
25 * Updating files with convert-ly::
32 @node Invoking lilypond
33 @section Invoking lilypond
34 @cindex Invoking LilyPond
35 @cindex command line options
36 @cindex options, command line
40 The @code{lilypond} executable may be called as follows from the command line.
43 lilypond [@var{option}]@dots{} @var{file}@dots{}
47 When invoked with a filename that has no extension, the @file{.ly}
48 extension is tried first. To read input from stdin, use a
49 dash (@code{-}) for @var{file}.
51 When @file{filename.ly} is processed it will produce
52 @file{filename.tex} as output (or @file{filename.ps} for PostScript
53 output). If @file{filename.ly} contains more than one @code{\score}
54 block, then the rest of the scores will be output in numbered files,
55 starting with @file{filename-1.tex}. Several files can be specified;
56 they will each be processed independently. @footnote{The status of
57 GUILE is not reset after processing a @code{.ly} file, so be careful
58 not to change any system defaults from within Scheme.}
61 @subsection Command line options
63 The following options are supported:
67 @item -e,--evaluate=@var{expr}
68 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
69 Multiple @code{-e} options may be given, they will be evaluated
72 The expression will be evaluated in the @code{guile-user} module, so
73 if you want to use definitions in @var{expr}, use
76 lilypond -e '(define-public a 42)'
80 on the command-line, and include
83 #(use-modules (guile-user))
87 at the top of the @code{.ly} file.
89 @item -f,--format=@var{format}
90 which formats should be written. Choices are @code{svg}, @code{ps},
91 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
93 @item -b,--backend=@var{format}
94 the output format to use for the back-end. Choices are
97 for @TeX{} output, to be processed with La@TeX{}. If present, the file
98 @file{file.textmetrics} is read to determine text extents.
100 dump text strings to @file{.texstr} file, which can be run through
101 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
102 extents of strings of text. @strong{Warning:} this functionality is
103 currently missing due to heavy restructuring of the source code.
106 @cindex PostScript output
108 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
109 these fonts is done. When using oriental character sets, this can
113 for encapsulated PostScript. This dumps every page (system) as a separate
114 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
115 all pages (systems) including fonts.
117 This mode is used by default by lilypond-book.
120 for SVG (Scalable Vector Graphics). This dumps every page as a separate
121 @file{SVG} file, with embedded fonts.
122 @cindex SVG (Scalable Vector Graphics)
123 You need a SVG viewer which supports embedded fonts, or a SVG
124 viewer which is able to replace the embedded fonts with OTF fonts.
125 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
126 (version 0.42 or later), after copying the OTF fonts in directory
127 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
129 for a dump of the raw, internal Scheme-based drawing commands.
133 @cindex output format, setting
135 @item -d,--define-default=@var{var}=@var{val}
136 This sets the internal program option @var{var} to the Scheme value
137 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
138 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
140 @cindex point and click, command line
149 -dpoint-and-click='#f'
152 Another notable option is
155 -dpaper-size=\"letter\"
159 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
161 Setting the @code{-dhelp} option will print a summary of the options
165 Show a summary of usage.
167 @item -H,--header=FIELD
168 Dump a header field to file BASENAME.FIELD
170 @item --include, -I=@var{directory}
171 Add @var{directory} to the search path for input files.
172 @cindex file searching
175 @item -i,--init=@var{file}
176 Set init file to @var{file} (default: @file{init.ly}).
178 @item -o,--output=@var{FILE}
179 Set the default output file to @var{FILE}. The appropriate
180 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
187 Generate DVI files. In this case, the @TeX{} backend should be
188 specified, i.e., @code{-b tex}.
191 Generate pictures of each page, in PNG format. This implies
192 @code{--ps}. The resolution in DPI of the image may be set with
198 Generate PDF. This implies @code{--ps}.
201 Generate an output file containing the titles and the first system
204 Do not generate the full pages. Useful in combination with
208 Do not trust the @code{.ly} input.
210 When LilyPond formatting is available through a web server, either the
211 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
212 @code{--safe} option will prevent inline Scheme code from wreaking
219 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
224 The @code{--safe} option works by evaluating in-line Scheme
225 expressions in a special safe module. This safe module is derived from
226 GUILE @file{safe-r5rs} module, but adds a number of functions of the
227 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
229 In addition, @code{--safe} disallows @code{\include} directives and
230 disables the use of backslashes in @TeX{} strings.
232 In @code{--safe} mode, it is not possible to import LilyPond variables
235 @code{--safe} does @emph{not} detect resource overuse. It is still
236 possible to make the program hang indefinitely, for example by feeding
237 cyclic data structures into the backend. Therefore, if using LilyPond
238 on a publicly accessible webserver, the process should be limited in
239 both CPU and memory usage.
241 Note that @code{--safe} will prevent many useful LilyPond snippets from
242 being compiled. For a softer but secure alternative you can use the
243 @code{--jail} option.
246 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
247 Run LilyPond in a chroot jail.
249 The @code{--jail} option provides a more flexible alternative to
250 @code{--safe} when LilyPond formatting is available through a web
251 server or whenever LilyPond executes externally provided
254 The @code{--jail} option works by changing the root of LilyPond to
255 @var{jail} just before starting the actual compilation process. The user
256 and group are then changed to match those provided, and the current
257 directory is changed to @var{dir}. This setup guarantees that it is not
258 possible (at least in theory) to escape from the jail. Note that for
259 @code{--jail} to work LilyPond must be run as root, which is usually
260 accomplished in a safe way using @command{sudo}.
262 Setting up a jail is a slightly delicate matter, as we must be sure that
263 LilyPond is able to find whatever it needs to compile the source
264 @emph{inside the jail}. A typical setup comprises the following items:
267 @item Setting up a separate filesystem
268 A separate filesystem should be created for LilyPond, so that it can be
269 mounted with safe options such as @code{noexec}, @code{nodev}, and
270 @code{nosuid}. In this way, it is impossible to run executables or to
271 write directly to a device from LilyPond. If you do not want to create a
272 separate partition, just create a file of reasonable size and use it to
273 mount a loop device. A separate filesystem also guarantees that LilyPond
274 cannot write more space than it is allowed.
276 @item Setting up a separate user
277 A separate user and group (say, @samp{lily}/@samp{lily}) with low
278 privileges should be used to run LilyPond inside the jail. There should
279 be a single directory writable by this user, which should be passed in
282 @item Preparing the jail
283 LilyPond needs to read a number of files while running. All these files
284 are to be copied into the jail, under the same path they appear in the
285 real root filesystem. The entire content of the LilyPond installation
286 (e.g., @file{/usr/share/lilypond})
289 If problems arise, the simplest way to trace them down is to run
290 LilyPond using @command{strace}, which will allow you to determine which
293 @item Running LilyPond
294 In a jail mounted with @code{noexec} it is impossible to execute any external
295 program. Therefore LilyPond must be run with a backend that does not
296 require any such program. As we already mentioned, it must be also run
297 with superuser privileges (which, of course, it will lose immediately),
298 possibly using @command{sudo}. It is a good idea to limit the number of
299 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
300 -t}), and, if your operating system supports it, the amount of memory
301 that can be allocated.
306 Show version information.
309 Be verbose: show full paths of all files read, and give timing
313 Show the warranty with which GNU LilyPond comes. (It comes with
314 @strong{NO WARRANTY}!)
318 @subsection Environment variables
322 @cindex LILYPONDPREFIX
324 @code{Lilypond} recognizes the following environment variables:
327 This specifies a directory where locale messages and
328 data files will be looked up by default. The directory should contain
329 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
332 This selects the language for the warning messages.
334 @item LILYPOND_GC_YIELD
335 With this variable the memory footprint and performance can be
336 adjusted. It is a percentage tunes memory management behavior. With
337 higher values, the program uses more memory, with smaller values, it
338 uses more CPU time. The default value is @code{70}.
343 @node Notes for the MacOS X app
344 @section Notes for the MacOS X app
346 The scripts (such as lilypond-book, convert-ly, abc2ly, and even
347 lilypond itself) are also
348 included inside MacOS X .app. They can be run from the command line by
349 invoking them directly, e.g.
352 @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond
356 The same is true of the other scripts in that directory, including
357 lilypond-book, convert-ly, abc2ly, etc.
359 Alternatively, you may add this directory to your path. Modify (or create)
360 a file called @code{.profile} in your home directory such that it contains
363 export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin
367 This file should end with a blank line.
369 Note that @var{path/to} will generally be @code{/Applications/}.
372 @node Updating files with convert-ly
373 @section Updating with @command{convert-ly}
375 @cindex Updating a LilyPond file
378 The LilyPond input syntax is routinely changed to simplify it or improve
379 it in different ways. As a side effect of this, the LilyPond interpreter
380 often is no longer compatible with older input files. To remedy this,
381 the program @command{convert-ly} can be used to deal with most of the
382 syntax changes between LilyPond versions.
384 It uses @code{\version} statements in the input files to detect the
385 old version number. In most cases, to upgrade your input file it is
386 sufficient to run@footnote{MacOS X users may execute this command
387 under the menu entry @samp{Compile > Update syntax}.}
390 convert-ly -e myfile.ly
393 If there are no changes to myfile.ly and file called myfile.ly.NEW
394 is created, then myfile.ly is already updated.
396 @command{convert-ly} always converts up to the last syntax change handled by
397 it. This means that the @code{\version} number left in the file is
398 usually lower than the version of @command{convert-ly} itself.
400 To upgrade LilyPond fragments in texinfo files, use
403 convert-ly --from=... --to=... --no-version *.itely
406 To upgrade many files at once, combine @code{convert-ly} with
407 standard unix commands. This example will upgrade all @code{.ly}
408 files in the current directory
411 for f in *.ly; do convert-ly -e $f; done;
414 In general, the program is invoked as follows:
417 convert-ly [@var{option}]@dots{} @var{file}@dots{}
421 The following options can be given:
425 Do an inline edit of the input file. Overrides @code{--output}.
427 @item -f,--from=@var{from-patchlevel}
428 Set the version to convert from. If this is not set, @command{convert-ly}
429 will guess this, on the basis of @code{\version} strings in the file.
431 @item -n,--no-version
432 Normally, @command{convert-ly} adds a @code{\version} indicator
433 to the output. Specifying this option suppresses this.
435 @item -s, --show-rules
436 Show all known conversions and exit.
438 @item --to=@var{to-patchlevel}
439 Set the goal version of the conversion. It defaults to the latest
449 Not all language changes are handled. Only one output option can be
450 specified. Automatically updating scheme and lilypond scheme
451 interfaces is quite unlikely; be prepared to tweak scheme code
455 @c We might want to make this a completely new section, along with more
456 @c info about how to upgrade old input files. -gp
459 Copy and paste from CVS, last updated
462 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/
463 convert-ly.txt?rev=HEAD&content-type=text/plain
465 NEW: not exactly copied; this list has been modified. Since we're
466 changing the bug system, it doesn't make sense to copy from
467 the bug CVS any more. I'll figure out something else. -gp
471 There are a few things that the convert-ly cannot handle. Here's a list of
473 that the community has complained about.
475 This bug report structure has been chosen because convert-ly has a structure
477 allow to smoothly implement all needed changes. Thus this is just a wishlist,
482 Doesn't always convert figured bass correctly, specifically things like {<
483 >}. Mats' comment on working around this:
484 To be able to run convert-ly
485 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
486 and similarly I replaced '>}' with '&}'. After the conversion, I could
487 then change back from '{ #' to '{ <' and from '& }' to '> }'.
488 Doesn't convert all text markup correctly. In the old markup syntax,
489 it was possible to group a number of markup commands together within
491 -#'((bold italic) "string")
492 This will incorrectly be converted into
493 -\markup{{\bold italic} "string"}
494 instead of the correct
495 -\markup{\bold \italic "string"}
497 Doesn't handle \partcombine
498 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
501 \magnify isn't changed to \fontsize.
502 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
503 remove-tag isn't changed.
504 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
505 first-page-number isn't changed.
506 - first-page-number no => print-first-page-number = ##f
507 Line breaks in header strings aren't converted.
508 - \\\\ as line break in \header strings => \markup \center-align <
509 "First Line" "Second Line" >
510 Crescendo and decrescendo terminators aren't converted.
514 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
517 \markup{ \center-align <{ ... }> } should be converted to:
518 \markup{ \center-align {\line { ... }} }
519 but now, \line is missing.
521 Special LaTeX characters such as $~$ in text are not converted to UTF8.
523 \score{} must now begin with a music expression. Anything else
524 (particularly \header{}) must come after the music.
529 @section Reporting bugs
532 @cindex reporting bugs
534 If you have input that results in a crash or an erroneous output, then
535 that is a bug. There is a list of current bugs on our google bug tracker,
537 @uref{http://code.google.com/p/lilypond/issues/list}
539 If you have discovered a bug which is not listed, please report the
540 bug by following the directions on
542 @uref{http://lilypond.org/web/devel/participating/bugs}
546 @section Error messages
548 @cindex error messages
549 Different error messages can appear while compiling a file:
555 Something looks suspect. If you are requesting something out of the
556 ordinary then you will understand the message, and can ignore it.
557 However, warnings usually indicate that something is wrong with the
561 Something is definitely wrong. The current processing step (parsing,
562 interpreting, or formatting) will be finished, but the next step will
568 Something is definitely wrong, and LilyPond cannot continue. This
569 happens rarely. The most usual cause is misinstalled fonts.
571 @cindex trace, Scheme
575 Errors that occur while executing Scheme code are caught by the Scheme
576 interpreter. If running with the verbose option (@code{-V} or
577 @code{--verbose}) then a call trace of the offending
578 function call is printed.
580 @cindex Programming error
581 @item Programming error
582 There was some internal inconsistency. These error messages are
583 intended to help the programmers and debuggers. Usually, they can be
584 ignored. Sometimes, they come in such big quantities that they obscure
585 other output. In this case, file a bug-report.
587 @item Aborted (core dumped)
588 This signals a serious programming error that caused the program to
589 crash. Such errors are considered critical. If you stumble on one,
595 @cindex errors, message format
596 If warnings and errors can
597 be linked to some part of the input file, then error messages have the
601 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
602 @var{offending input line}
605 A line-break is inserted in the offending line to indicate the column
606 where the error was found. For example,
609 test.ly:2:19: error: not a duration: 5:
614 These locations are LilyPond's best guess about where the warning or
615 error occurred, but (by their very nature) warnings and errors occur
616 when something unexpected happens. If you can't see an error in the
617 indicated line of your input file, try checking one or two lines
618 above the indicated position.
622 @section Editor support
627 @cindex modes, editor
628 @cindex syntax coloring
629 @cindex coloring, syntax
631 There is support from different editors for LilyPond.
635 Emacs has a @file{lilypond-mode}, which provides keyword
636 autocompletion, indentation, LilyPond specific parenthesis matching
637 and syntax coloring, handy compile short-cuts and reading LilyPond
638 manuals using Info. If @file{lilypond-mode} is not installed on your
639 platform, then read the
641 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
644 installation instructions.
649 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
650 with syntax coloring tools. For more information, refer to the
652 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
655 installation instructions.
661 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
662 This plugin includes a DVI viewer, integrated help and viewing via
663 GhostScript. It can be installed by doing @key{Plugins > Plugin
664 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
668 All these editors can be made to jump into the input file to the source
669 of a symbol in the graphical output. See @ref{Point and click}.
672 @node Point and click
673 @section Point and click
674 @cindex point and click
677 Point and click lets you find notes in the input by clicking on them
678 in the PDF viewer. This makes it easier to find input that causes
679 some error in the sheet music.
681 When this functionality is active, LilyPond adds hyperlinks to the PDF
682 file. These hyperlinks are sent to the web-browser, which opens a
683 text-editor with the cursor in the right place.
685 To make this chain work, you should configure your PDF viewer to
686 follow hyperlinks using the @file{lilypond-invoke-editor} script
687 supplied with LilyPond.
689 For Xpdf on Unix, the following should be present in
690 @file{xpdfrc}@footnote{On unix, this file is found either in
691 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
694 urlCommand "lilypond-invoke-editor %s"
697 The program @file{lilypond-invoke-editor} is a small helper
698 program. It will invoke an editor for the special @code{textedit}
699 URIs, and run a web browser for others. It tests the environment
700 variable @code{EDITOR} for the following patterns,
706 emacsclient --no-wait +@var{line}:@var{column} @var{file}
711 gvim --remote +:@var{line}:norm@var{char} @var{file}
717 nc -noask +@var{line} @var{file}'
721 The environment variable @code{LYEDITOR} is used to override this. It
722 contains the command line to start the editor, where @code{%(file)s},
723 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
724 and line respectively. The setting
727 emacsclient --no-wait +%(line)s:%(column)s %(file)s
731 for @code{LYEDITOR} is equivalent to the standard emacsclient
735 @cindex file size, output
737 The point and click links enlarge the output files significantly. For
738 reducing the size of PDF and PS files, point and click may be switched
742 #(ly:set-option 'point-and-click #f)
746 in a @file{.ly} file. Alternately, you may pass this as an command-line
750 lilypond -dno-point-and-click file.ly