1 @c -*- coding: latin-1; 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
54 sequentially. The function @code{ly:set-option} allows access to
55 some internal variables. Use @code{-e '(ly:option-usage)'} for more
58 @item -f,--format=@var{format}
59 which formats should be written. Choices are @code{svg}, @code{ps},
60 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
62 @item -b,--backend=@var{format}
63 the output format to use for the back-end. Choices are
66 for @TeX{} output, to be processed with La@TeX{}. If present, the file
67 @file{file.textmetrics} is read to determine text extents.
69 dump text strings to @file{.texstr} file, which can be run through
70 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
71 extents of strings of text.
74 @cindex PostScript output
76 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
77 these fonts is done. When using oriental character sets, this can
81 for encapsulated PostScript. This dumps every page (system) as a separate
82 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
83 all pages (systems) including fonts.
85 This mode is used by default by lilypond-book.
88 for SVG (Scalable Vector Graphics)
89 @cindex SVG (Scalable Vector Graphics)
91 for a dump of the raw, internal Scheme-based drawing commands.
95 @cindex output format, setting
97 @item -d,--define-default=@var{var}=@var{val}
98 This defines an internal variable @var{var} as the Scheme value
101 Supported values include:
105 @item preview-include-book-title
106 include book-titles in preview
109 These settings are returned when calling
110 @code{(ly:get-option 'command-line-settings)} from Scheme.
113 Show a summary of usage.
115 @item --include, -I=@var{directory}
116 Add @var{directory} to the search path for input files.
117 @cindex file searching
120 @item -i,--init=@var{file}
121 Set init file to @var{file} (default: @file{init.ly}).
123 @item -o,--output=@var{FILE}
124 Set the default output file to @var{FILE}. The appropriate
125 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
132 Generate DVI files. In this case, the @TeX{} backend should be
133 specified, i.e., @code{-f tex}.
136 Generate pictures of each page, in PNG format. This implies @code{--ps}.
139 Generate PDF. This implies @code{--ps}.
142 Generate an output file containing the titles and the first system
145 Do not generate the full pages. Useful in combination with
149 Do not trust the @code{.ly} input.
151 When LilyPond formatting is available through a web server, either the
152 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
153 @code{--safe} option will prevent inline Scheme code from wreaking
156 When LilyPond formatting is available through a web server, the
157 @code{--safe} @b{MUST} be passed. This will prevent inline Scheme
158 code from wreaking havoc, for example
164 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
169 The @code{--safe} option works by evaluating in-line Scheme
170 expressions in a special safe module. This safe module is derived from
171 GUILE @file{safe-r5rs} module, but adds a number of functions of the
172 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
174 In addition, @code{--safe} disallows @code{\include} directives and
175 disables the use of backslashes in @TeX{} strings.
177 In @code{--safe} mode, it is not possible to import LilyPond variables
180 @code{--safe} does @emph{not} detect resource overuse. It is still
181 possible to make the program hang indefinitely, for example by feeding
182 cyclic data structures into the backend. Therefore, if using LilyPond
183 on a publicly accessible webserver, the process should be limited in
184 both CPU and memory usage.
186 Note that @code{--safe} will prevent many useful LilyPond snippets from
187 being compiled. For a softer but secure alternative you can use the
188 @code{--jail} option.
191 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
192 Run LilyPond in a jail.
194 The @code{--jail} option provides a more flexible alternative to
195 @code{--safe} when LilyPond formatting is available through a web
196 server or whenever LilyPond executes externally provided
199 The @code{--jail} option works by changing the root of LilyPond to
200 @var{jail} just before starting the actual compilation process. The user
201 and group are then changed to match those provided, and the current
202 directory is changed to @var{dir}. This setup guarantees that it is not
203 possible (at least in theory) to escape from the jail. Note that for
204 @code{--jail} to work LilyPond must be run as root, which is usually
205 accomplished in a safe way using @command{sudo}.
207 Setting up a jail is a slightly delicate matter, as we must be sure that
208 LilyPond is able to find whatever it needs to compile the source
209 @emph{inside the jail}. A typical setup comprises the following items:
212 @item Setting up a separate filesystem
213 A separate filesystem should be created for LilyPond, so that it can be
214 mounted with safe options such as @code{noexec}, @code{nodev}, and
215 @code{nosuid}. In this way, it is impossible to run executables or to
216 write directly to a device from LilyPond. If you do not want to create a
217 separate partition, just create a file of reasonable size and use it to
218 mount a loop device. A separate filesystem also guarantees that LilyPond
219 cannot write more space than it is allowed.
221 @item Setting up a separate user
222 A separate user and group (say, @samp{lily}/@samp{lily}) with low
223 privileges should be used to run LilyPond inside the jail. There should
224 be a single directory writable by this user, which should be passed in
227 @item Preparing the jail
228 LilyPond needs to read a number of files while running. All these files
229 are to be copied into the jail, under the same path they apper in the
230 real root filesystem. The entire content of the LilyPond installation
231 (e.g., @file{/usr/share/lilypond})
234 If problems arise, the simplest way to trace them down is to run
235 LilyPond using @command{strace}, which will allow you to determine which
238 @item Running LilyPond
239 In a jail mounted with @code{noexec} it is impossible to execute any external
240 program. Therefore LilyPond must be run with a backend that does not
241 require any such program. As we already mentioned, it must be also run
242 with superuser privileges (which, of course, it will lose immediately),
243 possibly using @command{sudo}. It is a good idea to limit the number of
244 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
245 -t}), and, if your operating system supports it, the amount of memory
246 that can be allocated.
251 Show version information.
254 Be verbose: show full paths of all files read, and give timing
258 Show the warranty with which GNU LilyPond comes. (It comes with
259 @strong{NO WARRANTY}!)
263 @section Environment variables
266 For processing both the @TeX{} and the PostScript output, the
267 appropriate environment variables must be set. The following scripts
271 @item @file{buildscripts/@/out/@/lilypond@/-profile}
273 @item @file{buildscripts/@/out/@/lilypond@/-login} (for C-shells)
276 They should normally be sourced as part of the login process. If these
277 scripts are not run from the system wide login process, then you must
280 @cindex installing LilyPond
282 If you use sh, bash, or a similar shell, then add the following to
283 your @file{.profile}:
285 . @var{/the/path/to/}lilypond-profile
288 If you use csh, tcsh or a similar shell, then add the following to
289 your @file{~/.login}:
291 source @var{/the/path/to/}lilypond-login
294 Of course, in both cases, you should substitute the proper location of
297 These scripts set the following variables:
300 To make sure that @TeX{} and lilypond find data files (among
301 others @file{.tex}, @file{.mf}, and @file{.tfm}),
302 you have to set @code{TEXMF} to point to the lilypond data
303 file tree. A typical setting would be
305 @{/usr/share/lilypond/2.4.0,@{!!/usr/share/texmf@}@}
312 @cindex printing postscript
318 @cindex LILYPONDPREFIX
320 @code{Lilypond} recognizes the following environment variables:
323 This specifies a directory where locale messages and
324 data files will be looked up by default. The directory should contain
325 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
328 This selects the language for the warning messages.
333 @section Error messages
335 @cindex error messages
336 Different error messages can appear while compiling a file:
342 Something looks suspect. If you are requesting something out of the
343 ordinary then you will understand the message, and can ignore it.
344 However, warnings usually indicate that something is wrong with the
348 Something is definitely wrong. The current processing step (parsing,
349 interpreting, or formatting) will be finished, but the next step will
355 Something is definitely wrong, and LilyPond cannot continue. This
356 happens rarely. The most usual cause is misinstalled fonts.
358 @cindex trace, Scheme
362 Errors that occur while executing Scheme code are caught by the Scheme
363 interpreter. If running with the verbose option (@code{-V} or
364 @code{--verbose}) then a call trace of the offending
365 function call is printed.
367 @cindex Programming error
368 @item Programming error
369 There was some internal inconsistency. These error messages are
370 intended to help the programmers and debuggers. Usually, they can be
371 ignored. Sometimes, they come in such big quantities that they obscure
372 other output. In this case, file a bug-report.
374 @item Aborted (core dumped)
375 This signals a serious programming error that caused the program to
376 crash. Such errors are considered critical. If you stumble on one,
382 @cindex errors, message format
383 If warnings and errors can
384 be linked to some part of the input file, then error messages have the
388 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
389 @var{offending input line}
392 A line-break is inserted in the offending line to indicate the column
393 where the error was found. For example,
396 test.ly:2:19: error: not a duration: 5:
401 These locations are LilyPond's best guess about where the warning or
402 error occured, but (by their very nature) warnings and errors occur
403 when something unexpected happens. If you can't see an error in the
404 indicated line of your input file, try checking one or two lines
405 above the indicated position.
408 @node Updating files with convert-ly
409 @section Updating with @command{convert-ly}
411 The LilyPond input syntax is routinely changed to simplify it or improve
412 it in different ways. As a side effect of this, the LilyPond interpreter
413 often is no longer compatible with older input files. To remedy this,
414 the program @command{convert-ly} can be used to deal with most of the
415 syntax changes between LilyPond versions.
417 It uses @code{\version} statements in the input files to detect the old
418 version number. In most cases, to upgrade your input file it is sufficient
422 convert-ly -e myfile.ly
425 If there are no changes to myfile.ly and file called myfile.ly.NEW
426 is created, then myfile.ly is already updated.
428 To upgrade LilyPond fragments in texinfo files, use
431 convert-ly --from=... --to=... --no-version *.itely
434 To upgrade many files at once, combine @code{convert-ly} with
435 standard unix commands. This example will upgrade all @code{.ly}
436 files in the current directory
439 for f in *.ly; do convert-ly -e $f; done;
442 In general, the program is invoked as follows:
445 convert-ly [@var{option}]@dots{} @var{file}@dots{}
449 The following options can be given:
453 Do an inline edit of the input file. Overrides @code{--output}.
455 @item -f,--from=@var{from-patchlevel}
456 Set the version to convert from. If this is not set, @command{convert-ly}
457 will guess this, on the basis of @code{\version} strings in the file.
459 @item -o,--output=@var{file}
460 Set the output file to write.
462 @item -n,--no-version
463 Normally, @command{convert-ly} adds a @code{\version} indicator
464 to the output. Specifying this option suppresses this.
466 @item -s, --show-rules
467 Show all known conversions and exit.
469 @item --to=@var{to-patchlevel}
470 Set the goal version of the conversion. It defaults to the latest
477 @command{convert-ly} always converts up to the last syntax change handled by
478 it. This means that the @code{\version} number left in the file is
479 usually lower than the version of @command{convert-ly} itself.
483 Not all language changes are handled. Only one output option can be
487 @c We might want to make this a completely new section, along with more
488 @c info about how to upgrade old input files. -gp
491 Copy and paste from CVS, last updated
494 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
498 There are a few things that the convert-ly cannot handle. Here's a
499 list of limitations that the community has complained about.
501 This bug report structure has been chosen because convert-ly has a
502 structure that doesn't allow to smoothly implement all needed changes.
503 Thus this is just a wishlist, placed here for reference.
506 Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
507 To be able to run convert-ly
508 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
509 and similarly I replaced '>}' with '&}'. After the conversion, I could
510 then change back from '{ #' to '{ <' and from '& }' to '> }'.
511 Doesn't convert all text markup correctly. Only very simple cases are fixed.
513 Doesn't handle \partcombine
514 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
516 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
518 \markup{ \center-align <{ ... }> } should be converted to:
519 \markup{ \center-align {\line { ... }} }
520 but now, \line is missing.
525 @section Reporting bugs
528 @cindex reporting bugs
530 If you have input that results in a crash or an erroneous output, then
531 that is a bug. We try to respond to bug-reports promptly, and fix them as
532 soon as possible. Help us by sending a defective input file, so we can
533 reproduce the problem. Make it small, so we can easily debug the
534 problem. Don't forget to tell which version of LilyPond you use! Send
535 the report to @email{bug-lilypond@@gnu.org}.
538 @c the bug database is not up to date enough.
540 When you've found a bug, have a look at our
541 @uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if
542 it has already been reported. You could also try to do a few searches
543 on the mailing list for the bug. Sometimes the bug will have already
544 been reported and a fix or workaround is already known.
547 Here is an example of a good bug report:
550 It seems that placement of accidentals is broken. In the
551 following example, the accidental touches the note head.
553 Using Mac OSX 10.3.5, fink package lilypond-unstable
564 \override Accidental #'extra-offset = #'(1.0 . 0)
570 @section Editor support
575 @cindex modes, editor
576 @cindex syntax coloring
577 @cindex coloring, syntax
579 There is support from different editors for LilyPond.
583 Emacs has a @file{lilypond-mode}, which provides keyword
584 autocompletion, indentation, LilyPond specific parenthesis matching
585 and syntax coloring, handy compile short-cuts and reading LilyPond
586 manuals using Info. If @file{lilypond-mode} is not installed on your
587 platform, then read the
589 @uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}.
592 installation instructions.
597 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
598 with syntax coloring tools. For more information, refer to the
600 @uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}.
603 installation instructions.
609 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
610 This plugin includes a DVI viewer, integrated help and viewing via
611 GhostScript. It can be installed by doing @key{Plugins > Plugin
612 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
616 All these editors can be made to jump into the input file to the source
617 of a symbol in the graphical output. See @ref{Point and click}.