1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
13 @node Running LilyPond
14 @chapter Running LilyPond
16 This chapter details the technicalities of running LilyPond.
20 * Command-line usage::
22 * Updating files with convert-ly::
30 Most users run LilyPond through a GUI; see
32 @c @rlearning{First steps} if
33 you have not read this already.
36 @node Command-line usage
37 @section Command-line usage
39 This section contains extra information about using LilyPond on the
40 command-line. This may be desirable to pass extra options to the
41 program. In addition, there are certain extra @q{helper} programs (such
42 as @code{midi2ly}) which are only available on the command-line.
44 By @q{command-line}, we mean the command line in the operating system.
45 Windows users might be more familiar with the terms @q{DOS shell} or
46 @q{command shell}; MacOS@tie{}X users might be more familiar with the terms
47 @q{terminal} or @q{console}. They should also consult @ref{Setup
50 Describing how to use this part of an operating system is outside the
51 scope of this manual; please consult other documentation on this topic
52 if you are unfamiliar with the command-line.
56 * Command line options for lilypond::
57 * Environment variables::
60 @node Invoking lilypond
61 @subsection Invoking @command{lilypond}
63 @cindex Invoking @command{lilypond}
64 @cindex command line options for @command{lilypond}
65 @cindex options, command line
69 The @command{lilypond} executable may be called as follows from the command line.
72 lilypond [@var{option}]@dots{} @var{file}@dots{}
76 When invoked with a filename that has no extension, the @file{.ly}
77 extension is tried first. To read input from stdin, use a
78 dash (@code{-}) for @var{file}.
80 When @file{filename.ly} is processed it will produce @file{filename.ps}
81 and @file{filename.pdf} as output. Several files can be specified;
82 they will each be processed independently. @footnote{The status of
83 GUILE is not reset after processing a @code{.ly} file, so be careful
84 not to change any system defaults from within Scheme.}
86 If @file{filename.ly} contains more than one @code{\score}
87 block, then the rest of the scores will be output in numbered files,
88 starting with @file{filename-1.pdf}. In addition, the value of
89 @code{output-suffix} will be inserted between the basename and the
90 number. An input file containing
93 #(define output-suffix "violin")
95 #(define output-suffix "cello")
100 will output @var{base}@file{-violin.pdf} and
101 @var{base}@file{-cello-1.pdf}.
104 @node Command line options for lilypond
105 @subsection Command line options for @command{lilypond}
107 The following options are supported:
111 @item -e,--evaluate=@var{expr}
112 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
113 Multiple @code{-e} options may be given, they will be evaluated
116 The expression will be evaluated in the @code{guile-user} module, so
117 if you want to use definitions in @var{expr}, use
120 lilypond -e '(define-public a 42)'
124 on the command-line, and include
127 #(use-modules (guile-user))
131 at the top of the @code{.ly} file.
133 @item -f,--format=@var{format}
134 which formats should be written. Choices for @code{format} are
135 @code{svg}, @code{ps}, @code{pdf}, and @code{png}.
137 Example: @code{lilypond -fpng @var{filename}.ly}
141 @item -d,--define-default=@var{var}=@var{val}
142 This sets the internal program option @var{var} to the Scheme value
143 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
144 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
146 @cindex point and click, command line
155 -dpoint-and-click='#f'
158 Here are a few interesting options.
162 Running @code{lilypond -dhelp} will print all of the @code{-d} options
166 This option sets the default paper-size,
168 -dpaper-size=\"letter\"
172 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
173 @c Match " in previous line to help context-sensitive editors
176 Do not trust the @code{.ly} input.
178 When LilyPond formatting is available through a web server, either the
179 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
180 @code{--safe} option will prevent inline Scheme code from wreaking
187 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
192 The @code{-dsafe} option works by evaluating in-line Scheme
193 expressions in a special safe module. This safe module is derived from
194 GUILE @file{safe-r5rs} module, but adds a number of functions of the
195 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
197 In addition, safe mode disallows @code{\include} directives and
198 disables the use of backslashes in @TeX{} strings.
200 In safe mode, it is not possible to import LilyPond variables
203 @code{-dsafe} does @emph{not} detect resource overuse. It is still possible to
204 make the program hang indefinitely, for example by feeding cyclic data
205 structures into the backend. Therefore, if using LilyPond on a
206 publicly accessible webserver, the process should be limited in both
207 CPU and memory usage.
209 The safe mode will prevent many useful LilyPond snippets from being
210 compiled. The @code{--jail} is a more secure alternative, but
211 requires more work to set up.
213 @cindex output format, setting
215 the output format to use for the back-end. Choices for @code{format} are
218 @cindex PostScript output
221 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
222 these fonts is done. When using oriental character sets, this can
226 for encapsulated PostScript. This dumps every page (system) as a separate
227 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
228 all pages (systems) including fonts.
230 This mode is used by default by @command{lilypond-book}.
233 @cindex SVG (Scalable Vector Graphics)
234 for SVG (Scalable Vector Graphics).
236 This creates a single SVG file containing the entire music
237 output, with embedded fonts. You need an SVG viewer that
238 supports embedded fonts, or an SVG viewer that can replace the
239 embedded fonts with OTF fonts. Under UNIX, you may use
240 @uref{http://www.inkscape.org,Inkscape} (version 0.42 or later),
241 after copying the OTF fonts from the LilyPond directory
242 (typically @file{/usr/share/lilypond/VERSION/fonts/otf/}) to
247 for a dump of the raw, internal Scheme-based drawing commands.
250 do not output a printed score; has the same effect as @code{-dno-print-pages}.
253 Example: @code{lilypond -dbackend=svg @var{filename}.ly}
256 Generate an output file containing the titles and the first system
259 Generate the full pages, the default. @code{-dno-print-pages} is
260 useful in combination with @code{-dpreview}.
267 Show a summary of usage.
269 @item -H,--header=@var{FIELD}
270 Dump a header field to file @file{BASENAME.@var{FIELD}}.
272 @item --include, -I=@var{directory}
273 Add @var{directory} to the search path for input files.
274 @cindex file searching
277 @item -i,--init=@var{file}
278 Set init file to @var{file} (default: @file{init.ly}).
280 @item -o,--output=@var{FILE}
281 Set the default output file to @var{FILE}. The appropriate
282 suffix will be added (e.g. @code{.pdf} for pdf)
288 Generate pictures of each page, in PNG format. This implies
289 @code{--ps}. The resolution in DPI of the image may be set with
295 Generate PDF. This implies @code{--ps}.
299 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
300 Run @command{lilypond} in a chroot jail.
302 The @code{--jail} option provides a more flexible alternative to
303 @code{--safe} when LilyPond formatting is available through a web
304 server or whenever LilyPond executes externally provided
307 The @code{--jail} option works by changing the root of @command{lilypond} to
308 @var{jail} just before starting the actual compilation process. The user
309 and group are then changed to match those provided, and the current
310 directory is changed to @var{dir}. This setup guarantees that it is not
311 possible (at least in theory) to escape from the jail. Note that for
312 @code{--jail} to work @command{lilypond} must be run as root, which is usually
313 accomplished in a safe way using @command{sudo}.
315 Setting up a jail is a slightly delicate matter, as we must be sure that
316 LilyPond is able to find whatever it needs to compile the source
317 @emph{inside the jail}. A typical setup comprises the following items:
320 @item Setting up a separate filesystem
321 A separate filesystem should be created for LilyPond, so that it can be
322 mounted with safe options such as @code{noexec}, @code{nodev}, and
323 @code{nosuid}. In this way, it is impossible to run executables or to
324 write directly to a device from LilyPond. If you do not want to create a
325 separate partition, just create a file of reasonable size and use it to
326 mount a loop device. A separate filesystem also guarantees that LilyPond
327 cannot write more space than it is allowed.
329 @item Setting up a separate user
330 A separate user and group (say, @code{lily}/@code{lily}) with low
331 privileges should be used to run LilyPond inside the jail. There should
332 be a single directory writable by this user, which should be passed in
335 @item Preparing the jail
336 LilyPond needs to read a number of files while running. All these files
337 are to be copied into the jail, under the same path they appear in the
338 real root filesystem. The entire content of the LilyPond installation
339 (e.g., @file{/usr/share/lilypond})
342 If problems arise, the simplest way to trace them down is to run
343 LilyPond using @command{strace}, which will allow you to determine which
346 @item Running LilyPond
347 In a jail mounted with @code{noexec} it is impossible to execute any external
348 program. Therefore LilyPond must be run with a backend that does not
349 require any such program. As we already mentioned, it must be also run
350 with superuser privileges (which, of course, it will lose immediately),
351 possibly using @command{sudo}. It is a good idea to limit the number of
352 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
353 -t}), and, if your operating system supports it, the amount of memory
354 that can be allocated.
359 Show version information.
362 Be verbose: show full paths of all files read, and give timing
366 Show the warranty with which GNU LilyPond comes. (It comes with
367 @strong{NO WARRANTY}!)
370 @node Environment variables
371 @subsection Environment variables
375 @cindex LILYPOND_DATADIR
377 @command{lilypond} recognizes the following environment variables:
379 @item LILYPOND_DATADIR
380 This specifies a directory where locale messages and
381 data files will be looked up by default. The directory should contain
382 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
385 This selects the language for the warning messages.
387 @item LILYPOND_GC_YIELD
388 With this variable the memory footprint and performance can be
389 adjusted. It is a percentage tunes memory management behavior. With
390 higher values, the program uses more memory, with smaller values, it
391 uses more CPU time. The default value is @code{70}.
397 @section Error messages
399 @cindex error messages
400 Different error messages can appear while compiling a file:
406 Something looks suspect. If you are requesting something out of the
407 ordinary then you will understand the message, and can ignore it.
408 However, warnings usually indicate that something is wrong with the
412 Something is definitely wrong. The current processing step (parsing,
413 interpreting, or formatting) will be finished, but the next step will
419 Something is definitely wrong, and LilyPond cannot continue. This
420 happens rarely. The most usual cause is misinstalled fonts.
423 @cindex trace, Scheme
426 Errors that occur while executing Scheme code are caught by the Scheme
427 interpreter. If running with the verbose option (@code{-V} or
428 @code{--verbose}) then a call trace of the offending
429 function call is printed.
431 @item Programming error
432 @cindex Programming error
433 There was some internal inconsistency. These error messages are
434 intended to help the programmers and debuggers. Usually, they can be
435 ignored. Sometimes, they come in such big quantities that they obscure
438 @item Aborted (core dumped)
439 This signals a serious programming error that caused the program to
440 crash. Such errors are considered critical. If you stumble on one,
444 @cindex errors, message format
445 If warnings and errors can
446 be linked to some part of the input file, then error messages have the
450 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
451 @var{offending input line}
454 A line-break is inserted in the offending line to indicate the column
455 where the error was found. For example,
458 test.ly:2:19: error: not a duration: 5
463 These locations are LilyPond's best guess about where the warning or
464 error occurred, but (by their very nature) warnings and errors occur
465 when something unexpected happens. If you can't see an error in the
466 indicated line of your input file, try checking one or two lines
467 above the indicated position.
470 @node Updating files with convert-ly
471 @section Updating files with @command{convert-ly}
473 @cindex Updating a LilyPond file
476 The LilyPond input syntax is routinely changed to simplify it or improve
477 it in different ways. As a side effect of this, the LilyPond interpreter
478 often is no longer compatible with older input files. To remedy this,
479 the program @command{convert-ly} can be used to deal with most of the
480 syntax changes between LilyPond versions.
483 * Invoking convert-ly::
484 * Command line options for convert-ly::
485 * Problems with convert-ly::
488 @node Invoking convert-ly
489 @subsection Invoking @command{convert-ly}
491 @command{convert-ly} uses @code{\version} statements in the input
492 file to detect the old version number. In most cases, to upgrade
493 your input file it is sufficient to run
496 convert-ly -e myfile.ly
500 in the directory containing the file. This will upgrade
501 @code{myfile.ly} in-place and preserve the original file in
504 To convert all the input files in a directory together use
510 Alternatively, if you want to specify a different name for the
511 upgraded file, preserving the original file and name unchanged,
515 convert-ly myfile.ly > mynewfile.ly
518 @command{convert-ly} always converts up to the last syntax change
519 handled by it. This means that the @code{\version} number left in
520 the file is usually lower than the version of @command{convert-ly}
523 The program will list the version numbers for which conversions
524 have been made. If no version numbers are listed the file is
528 MacOS@tie{}X users may execute these commands under the menu entry
529 @code{Compile > Update syntax}.
531 Windows users should enter these commands in a Command Prompt window,
532 which is usually found under
533 @code{Start > Accessories > Command Prompt}.
535 @node Command line options for convert-ly
536 @subsection Command line options for @command{convert-ly}
538 In general, the program is invoked as follows:
541 convert-ly [@var{option}]@dots{} @var{filename}@dots{}
545 The following options can be given:
549 Apply the conversions direct to the input file, modifying it
552 @item -f,--from=@var{from-patchlevel}
553 Set the version to convert from. If this is not set, @command{convert-ly}
554 will guess this, on the basis of @code{\version} strings in the file.
555 E.g. @code{--from=2.10.25}
557 @item -n,--no-version
558 Normally, @command{convert-ly} adds a @code{\version} indicator
559 to the output. Specifying this option suppresses this.
561 @item -s, --show-rules
562 Show all known conversions and exit.
564 @item --to=@var{to-patchlevel}
565 Set the goal version of the conversion. It defaults to the latest
566 available version. E.g. @code{--to=2.12.2}
572 To upgrade LilyPond fragments in texinfo files, use
575 convert-ly --from=... --to=... --no-version *.itely
578 To see the changes in the LilyPond syntax between two versions, use
581 convert-ly --from=... --to=... -s
585 @node Problems with convert-ly
586 @subsection Problems with @code{convert-ly}
588 When running convert-ly in a Command Prompt window under Windows
589 on a file which has spaces in the filename or in the path to it,
590 it is necessary to surround the entire input file name with three
591 (!) sets of double quotes:
594 convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
597 If the simple @command{convert-ly -e *.ly} command fails because the
598 expanded command line becomes too long, the @command{convert-ly}
599 command may be placed in a loop instead. This example for UNIX
600 will upgrade all @code{.ly} files in the current directory
603 for f in *.ly; do convert-ly -e $f; done;
606 In the Windows Command Prompt window the corresponding command is
609 for %x in (*.ly) do convert-ly -e """%x"""
612 Not all language changes are handled. Only one output option can be
613 specified. Automatically updating scheme and LilyPond scheme
614 interfaces is quite unlikely; be prepared to tweak scheme code
618 There are a few things that the convert-ly cannot handle. Here's a list
619 of limitations that the community has complained about.
621 This bug report structure has been chosen because convert-ly has a
622 structure that doesn't allow to smoothly implement all needed changes.
623 Thus this is just a wishlist, placed here for reference.
626 Doesn't always convert figured bass correctly, specifically things like {<
627 >}. Mats' comment on working around this:
628 To be able to run convert-ly
629 on it, I first replaced all occurrences of '{<' to some dummy like '{#'
630 and similarly I replaced '>}' with '&}'. After the conversion, I could
631 then change back from '{ #' to '{ <' and from '& }' to '> }'.
632 Doesn't convert all text markup correctly. In the old markup syntax,
633 it was possible to group a number of markup commands together within
635 -#'((bold italic) "string")
636 This will incorrectly be converted into
637 -\markup{{\bold italic} "string"}
638 instead of the correct
639 -\markup{\bold \italic "string"}
641 Doesn't handle \partcombine
642 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
645 \magnify isn't changed to \fontsize.
646 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
647 remove-tag isn't changed.
648 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
649 first-page-number isn't changed.
650 - first-page-number no => print-first-page-number = ##f
651 Line breaks in header strings aren't converted.
652 - \\\\ as line break in \header strings => \markup \center-align <
653 "First Line" "Second Line" >
654 Crescendo and decrescendo terminators aren't converted.
658 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
661 \markup{ \center-align <{ ... }> } should be converted to:
662 \markup{ \center-align {\line { ... }} }
663 but now, \line is missing.
665 Special LaTeX characters such as $~$ in text are not converted to UTF8.
667 \score{} must now begin with a music expression. Anything else
668 (particularly \header{}) must come after the music.
673 @section Reporting bugs
676 @cindex reporting bugs
678 If you have input that results in a crash or an erroneous output, then
679 that is a bug. There is a list of current bugs on our Google bug tracker,
681 @uref{http://code.google.com/p/lilypond/issues/list}
683 If you have discovered a bug which is not listed, please report the
684 bug by following the directions on
686 @uref{http://lilypond.org/web/devel/participating/bugs}
688 Please construct and submit minimal examples of bugs in reports. We do not
689 have the resources to investigate reports which are not as small as possible.