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::
18 @node Invoking lilypond
19 @section Invoking lilypond
20 @cindex Invoking LilyPond
21 @cindex command line options
22 @cindex options, command line
26 The @code{lilypond} executable may be called as follows from the command line.
29 lilypond [@var{option}]@dots{} @var{file}@dots{}
33 When invoked with a filename that has no extension, the @file{.ly}
34 extension is tried first. To read input from stdin, use a
35 dash (@code{-}) for @var{file}.
37 When @file{filename.ly} is processed it will produce
38 @file{filename.tex} as output (or @file{filename.ps} for PostScript
39 output). If @file{filename.ly} contains more than one @code{\score}
40 block, then the rest of the scores will be output in numbered files,
41 starting with @file{filename-1.tex}. Several files can be specified;
42 they will each be processed independently. @footnote{The status of
43 GUILE is not reset after processing a @code{.ly} file, so be careful
44 not to change any system defaults from within Scheme.}
47 @section Command line options
49 The following options are supported:
53 @item -e,--evaluate=@var{expr}
54 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
55 Multiple @code{-e} options may be given, they will be evaluated
58 The expression will be evaluated in the @code{guile-user} module, so
59 if you want to use definitions in @var{expr}, use
62 lilypond -e '(define-public a 42)'
66 on the command-line, and include
69 #(use-modules (guile-user))
73 at the top of the @code{.ly} file.
75 @item -f,--format=@var{format}
76 which formats should be written. Choices are @code{svg}, @code{ps},
77 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
79 @item -b,--backend=@var{format}
80 the output format to use for the back-end. Choices are
83 for @TeX{} output, to be processed with La@TeX{}. If present, the file
84 @file{file.textmetrics} is read to determine text extents.
86 dump text strings to @file{.texstr} file, which can be run through
87 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
88 extents of strings of text.
91 @cindex PostScript output
93 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
94 these fonts is done. When using oriental character sets, this can
98 for encapsulated PostScript. This dumps every page (system) as a separate
99 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
100 all pages (systems) including fonts.
102 This mode is used by default by lilypond-book.
105 for SVG (Scalable Vector Graphics). This dumps every page as a separate
106 @file{SVG} file, with embedded fonts.
107 @cindex SVG (Scalable Vector Graphics)
108 You need a SVG viewer which supports embedded fonts, or a SVG
109 viewer which is able to replace the embedded fonts with OTF fonts.
110 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
111 (version 0.42 or later), after copying the OTF fonts in directory
112 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
114 for a dump of the raw, internal Scheme-based drawing commands.
118 @cindex output format, setting
120 @item -d,--define-default=@var{var}=@var{val}
121 This sets the internal program option @var{var} to the Scheme value
122 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
123 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
125 @cindex point and click, command line
134 -dpoint-and-click='#f'
137 Another notable option is
140 -dpaper-size=\"letter\"
144 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
146 Setting the @code{-dhelp} option will print a summary of the options
150 Show a summary of usage.
152 @item -H,--header=FIELD
153 Dump a header field to file BASENAME.FIELD
155 @item --include, -I=@var{directory}
156 Add @var{directory} to the search path for input files.
157 @cindex file searching
160 @item -i,--init=@var{file}
161 Set init file to @var{file} (default: @file{init.ly}).
163 @item -o,--output=@var{FILE}
164 Set the default output file to @var{FILE}. The appropriate
165 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
172 Generate DVI files. In this case, the @TeX{} backend should be
173 specified, i.e., @code{-b tex}.
176 Generate pictures of each page, in PNG format. This implies
177 @code{--ps}. The resolution in DPI of the image may be set with
183 Generate PDF. This implies @code{--ps}.
186 Generate an output file containing the titles and the first system
189 Do not generate the full pages. Useful in combination with
193 Do not trust the @code{.ly} input.
195 When LilyPond formatting is available through a web server, either the
196 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
197 @code{--safe} option will prevent inline Scheme code from wreaking
200 When LilyPond formatting is available through a web server, the
201 @code{--safe} @b{MUST} be passed. This will prevent inline Scheme
202 code from wreaking havoc, for example
208 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
213 The @code{--safe} option works by evaluating in-line Scheme
214 expressions in a special safe module. This safe module is derived from
215 GUILE @file{safe-r5rs} module, but adds a number of functions of the
216 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
218 In addition, @code{--safe} disallows @code{\include} directives and
219 disables the use of backslashes in @TeX{} strings.
221 In @code{--safe} mode, it is not possible to import LilyPond variables
224 @code{--safe} does @emph{not} detect resource overuse. It is still
225 possible to make the program hang indefinitely, for example by feeding
226 cyclic data structures into the backend. Therefore, if using LilyPond
227 on a publicly accessible webserver, the process should be limited in
228 both CPU and memory usage.
230 Note that @code{--safe} will prevent many useful LilyPond snippets from
231 being compiled. For a softer but secure alternative you can use the
232 @code{--jail} option.
235 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
236 Run LilyPond in a chroot jail.
238 The @code{--jail} option provides a more flexible alternative to
239 @code{--safe} when LilyPond formatting is available through a web
240 server or whenever LilyPond executes externally provided
243 The @code{--jail} option works by changing the root of LilyPond to
244 @var{jail} just before starting the actual compilation process. The user
245 and group are then changed to match those provided, and the current
246 directory is changed to @var{dir}. This setup guarantees that it is not
247 possible (at least in theory) to escape from the jail. Note that for
248 @code{--jail} to work LilyPond must be run as root, which is usually
249 accomplished in a safe way using @command{sudo}.
251 Setting up a jail is a slightly delicate matter, as we must be sure that
252 LilyPond is able to find whatever it needs to compile the source
253 @emph{inside the jail}. A typical setup comprises the following items:
256 @item Setting up a separate filesystem
257 A separate filesystem should be created for LilyPond, so that it can be
258 mounted with safe options such as @code{noexec}, @code{nodev}, and
259 @code{nosuid}. In this way, it is impossible to run executables or to
260 write directly to a device from LilyPond. If you do not want to create a
261 separate partition, just create a file of reasonable size and use it to
262 mount a loop device. A separate filesystem also guarantees that LilyPond
263 cannot write more space than it is allowed.
265 @item Setting up a separate user
266 A separate user and group (say, @samp{lily}/@samp{lily}) with low
267 privileges should be used to run LilyPond inside the jail. There should
268 be a single directory writable by this user, which should be passed in
271 @item Preparing the jail
272 LilyPond needs to read a number of files while running. All these files
273 are to be copied into the jail, under the same path they appear in the
274 real root filesystem. The entire content of the LilyPond installation
275 (e.g., @file{/usr/share/lilypond})
278 If problems arise, the simplest way to trace them down is to run
279 LilyPond using @command{strace}, which will allow you to determine which
282 @item Running LilyPond
283 In a jail mounted with @code{noexec} it is impossible to execute any external
284 program. Therefore LilyPond must be run with a backend that does not
285 require any such program. As we already mentioned, it must be also run
286 with superuser privileges (which, of course, it will lose immediately),
287 possibly using @command{sudo}. It is a good idea to limit the number of
288 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
289 -t}), and, if your operating system supports it, the amount of memory
290 that can be allocated.
295 Show version information.
298 Be verbose: show full paths of all files read, and give timing
302 Show the warranty with which GNU LilyPond comes. (It comes with
303 @strong{NO WARRANTY}!)
307 @section Environment variables
311 @cindex LILYPONDPREFIX
313 @code{Lilypond} recognizes the following environment variables:
316 This specifies a directory where locale messages and
317 data files will be looked up by default. The directory should contain
318 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
321 This selects the language for the warning messages.
323 @item LILYPOND_GC_YIELD
324 With this variable the memory footprint and performance can be
325 adjusted. It is a percentage tunes memory management behavior. With
326 higher values, the program uses more memory, with smaller values, it
327 uses more CPU time. The default value is @code{70}.
332 @node Notes for the MacOS X app
333 @section Notes for the MacOS X app
335 The scripts (such as lilypond-book, convert-ly, abc2ly, etc.) are also
336 included inside MacOS X .app. They can be run from the command line by
337 invoking them directly, e.g.
340 @var{path/to}/LilyPond.app/Contents/Resources/bin/convert-ly
343 Alternatively, you may add this directory to your path. Modify (or create)
344 a file called @code{.profile} in your home directory such that it contains
347 export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin
351 This file should end with a blank line.
353 Note that @var{path/to} will generally be @code{/Applications/}.
357 @section Error messages
359 @cindex error messages
360 Different error messages can appear while compiling a file:
366 Something looks suspect. If you are requesting something out of the
367 ordinary then you will understand the message, and can ignore it.
368 However, warnings usually indicate that something is wrong with the
372 Something is definitely wrong. The current processing step (parsing,
373 interpreting, or formatting) will be finished, but the next step will
379 Something is definitely wrong, and LilyPond cannot continue. This
380 happens rarely. The most usual cause is misinstalled fonts.
382 @cindex trace, Scheme
386 Errors that occur while executing Scheme code are caught by the Scheme
387 interpreter. If running with the verbose option (@code{-V} or
388 @code{--verbose}) then a call trace of the offending
389 function call is printed.
391 @cindex Programming error
392 @item Programming error
393 There was some internal inconsistency. These error messages are
394 intended to help the programmers and debuggers. Usually, they can be
395 ignored. Sometimes, they come in such big quantities that they obscure
396 other output. In this case, file a bug-report.
398 @item Aborted (core dumped)
399 This signals a serious programming error that caused the program to
400 crash. Such errors are considered critical. If you stumble on one,
406 @cindex errors, message format
407 If warnings and errors can
408 be linked to some part of the input file, then error messages have the
412 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
413 @var{offending input line}
416 A line-break is inserted in the offending line to indicate the column
417 where the error was found. For example,
420 test.ly:2:19: error: not a duration: 5:
425 These locations are LilyPond's best guess about where the warning or
426 error occurred, but (by their very nature) warnings and errors occur
427 when something unexpected happens. If you can't see an error in the
428 indicated line of your input file, try checking one or two lines
429 above the indicated position.
433 @section Editor support
438 @cindex modes, editor
439 @cindex syntax coloring
440 @cindex coloring, syntax
442 There is support from different editors for LilyPond.
446 Emacs has a @file{lilypond-mode}, which provides keyword
447 autocompletion, indentation, LilyPond specific parenthesis matching
448 and syntax coloring, handy compile short-cuts and reading LilyPond
449 manuals using Info. If @file{lilypond-mode} is not installed on your
450 platform, then read the
452 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
455 installation instructions.
460 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
461 with syntax coloring tools. For more information, refer to the
463 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
466 installation instructions.
472 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
473 This plugin includes a DVI viewer, integrated help and viewing via
474 GhostScript. It can be installed by doing @key{Plugins > Plugin
475 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
479 All these editors can be made to jump into the input file to the source
480 of a symbol in the graphical output. See @ref{Point and click}.
483 @node Point and click
484 @section Point and click
485 @cindex point and click
488 Point and click lets you find notes in the input by clicking on them
489 in the PDF viewer. This makes it easier to find input that causes
490 some error in the sheet music.
492 When this functionality is active, LilyPond adds hyperlinks to the PDF
493 file. These hyperlinks are sent to the web-browser, which opens a
494 text-editor with the cursor in the right place.
496 To make this chain work, you should configure your PDF viewer to
497 follow hyperlinks using the @file{lilypond-invoke-editor} script
498 supplied with LilyPond.
500 For Xpdf on Unix, the following should be present in
501 @file{xpdfrc}@footnote{On unix, this file is found either in
502 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
505 urlCommand "lilypond-invoke-editor %s"
508 The program @file{lilypond-invoke-editor} is a small helper
509 program. It will invoke an editor for the special @code{textedit}
510 URIs, and run a web browser for others. It tests the environment
511 variable @code{EDITOR} for the following patterns,
517 emacsclient --no-wait +@var{line}:@var{column} @var{file}
522 gvim --remote +:@var{line}:norm@var{char} @var{file}
528 nc -noask +@var{line} @var{file}'
532 The environment variable @code{LYEDITOR} is used to override this. It
533 contains the command line to start the editor, where @code{%(file)s},
534 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
535 and line respectively. The setting
538 emacsclient --no-wait +%(line)s:%(column)s %(file)s
542 for @code{LYEDITOR} is equivalent to the standard emacsclient
546 @cindex file size, output
548 The point and click links enlarge the output files significantly. For
549 reducing the size of PDF and PS files, point and click may be switched
553 #(ly:set-option 'point-and-click #f)
557 in a @file{.ly} file. Alternately, you may pass this as an command-line
561 lilypond -dno-point-and-click file.ly