1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-program.tely
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 @rlearning{First steps} if
31 you have not read this already.
34 @node Command-line usage
35 @section Command-line usage
37 This section contains extra information about using LilyPond on the
38 command-line. This may be desirable to pass extra options to the
39 program. In addition, there are certain extra @q{helper} programs (such
40 as @code{midi2ly}) which are only available on the command-line.
42 By @q{command-line}, we mean the command line in the operating system.
43 Windows users might be more familiar with the terms @q{DOS shell} or
44 @q{command shell}; MacOS@tie{}X users might be more familiar with the terms
45 @q{terminal} or @q{console}. They should also consult @ref{Setup
48 Describing how to use this part of an operating system is outside the
49 scope of this manual; please consult other documentation on this topic
50 if you are unfamiliar with the command-line.
54 * Command line options for lilypond::
55 * Environment variables::
58 @node Invoking lilypond
59 @subsection Invoking @command{lilypond}
61 @cindex Invoking @command{lilypond}
62 @cindex command line options for @command{lilypond}
63 @cindex options, command line
67 The @command{lilypond} executable may be called as follows from the command line.
70 lilypond [@var{option}]@dots{} @var{file}@dots{}
74 When invoked with a filename that has no extension, the @file{.ly}
75 extension is tried first. To read input from stdin, use a
76 dash (@code{-}) for @var{file}.
78 When @file{filename.ly} is processed it will produce @file{filename.ps}
79 and @file{filename.pdf} as output. Several files can be specified;
80 they will each be processed independently. @footnote{The status of
81 GUILE is not reset after processing a @code{.ly} file, so be careful
82 not to change any system defaults from within Scheme.}
84 If @file{filename.ly} contains more than one @code{\score}
85 block, then the rest of the scores will be output in numbered files,
86 starting with @file{filename-1.pdf}. In addition, the value of
87 @code{output-suffix} will be inserted between the basename and the
88 number. An input file containing
91 #(define output-suffix "violin")
93 #(define output-suffix "cello")
98 will output @var{base}@file{-violin.pdf} and
99 @var{base}@file{-cello-1.pdf}.
102 @node Command line options for lilypond
103 @subsection Command line options for @command{lilypond}
105 The following options are supported:
109 @item -e,--evaluate=@var{expr}
110 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
111 Multiple @code{-e} options may be given, they will be evaluated
114 The expression will be evaluated in the @code{guile-user} module, so
115 if you want to use definitions in @var{expr}, use
118 lilypond -e '(define-public a 42)'
122 on the command-line, and include
125 #(use-modules (guile-user))
129 at the top of the @code{.ly} file.
131 @item -f,--format=@var{format}
132 which formats should be written. Choices for @code{format} are
133 @code{svg}, @code{ps}, @code{pdf}, and @code{png}.
135 Example: @code{lilypond -fpng @var{filename}.ly}
139 @item -d,--define-default=@var{var}=@var{val}
140 This sets the internal program option @var{var} to the Scheme value
141 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
142 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
144 @cindex point and click, command line
153 -dpoint-and-click='#f'
156 Here are a few interesting options.
160 Running @code{lilypond -dhelp} will print all of the @code{-d} options
164 This option sets the default paper-size,
166 -dpaper-size=\"letter\"
170 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
171 @c Match " in previous line to help context-sensitive editors
174 Do not trust the @code{.ly} input.
176 When LilyPond formatting is available through a web server, either the
177 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
178 @code{--safe} option will prevent inline Scheme code from wreaking
185 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
190 The @code{-dsafe} option works by evaluating in-line Scheme
191 expressions in a special safe module. This safe module is derived from
192 GUILE @file{safe-r5rs} module, but adds a number of functions of the
193 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
195 In addition, safe mode disallows @code{\include} directives and
196 disables the use of backslashes in @TeX{} strings.
198 In safe mode, it is not possible to import LilyPond variables
201 @code{-dsafe} does @emph{not} detect resource overuse. It is still possible to
202 make the program hang indefinitely, for example by feeding cyclic data
203 structures into the backend. Therefore, if using LilyPond on a
204 publicly accessible webserver, the process should be limited in both
205 CPU and memory usage.
207 The safe mode will prevent many useful LilyPond snippets from being
208 compiled. The @code{--jail} is a more secure alternative, but
209 requires more work to set up.
211 @cindex output format, setting
213 the output format to use for the back-end. Choices for @code{format} are
216 @cindex PostScript output
219 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
220 these fonts is done. When using oriental character sets, this can
224 for encapsulated PostScript. This dumps every page (system) as a separate
225 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
226 all pages (systems) including fonts.
228 This mode is used by default by @command{lilypond-book}.
231 @cindex SVG (Scalable Vector Graphics)
232 for SVG (Scalable Vector Graphics). This dumps every page as a separate
233 @file{SVG} file, with embedded fonts.
234 You need a SVG viewer which supports embedded fonts, or a SVG
235 viewer which is able to replace the embedded fonts with OTF fonts.
236 Under UNIX, you may use @uref{http://www.inkscape.org,Inkscape}
237 (version 0.42 or later), after copying the OTF fonts from the LilyPond directory
238 (typically @file{/usr/share/lilypond/VERSION/fonts/otf/}) to @file{~/.fonts/}.
241 for a dump of the raw, internal Scheme-based drawing commands.
244 do not output a printed score; has the same effect as @code{-dno-print-pages}.
247 Example: @code{lilypond -dbackend=svg @var{filename}.ly}
250 Generate an output file containing the titles and the first system
253 Generate the full pages, the default. @code{-dno-print-pages} is
254 useful in combination with @code{-dpreview}.
261 Show a summary of usage.
263 @item -H,--header=@var{FIELD}
264 Dump a header field to file @file{BASENAME.@var{FIELD}}.
266 @item --include, -I=@var{directory}
267 Add @var{directory} to the search path for input files.
268 @cindex file searching
271 @item -i,--init=@var{file}
272 Set init file to @var{file} (default: @file{init.ly}).
274 @item -o,--output=@var{FILE}
275 Set the default output file to @var{FILE}. The appropriate
276 suffix will be added (e.g. @code{.pdf} for pdf)
282 Generate pictures of each page, in PNG format. This implies
283 @code{--ps}. The resolution in DPI of the image may be set with
289 Generate PDF. This implies @code{--ps}.
293 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
294 Run @command{lilypond} in a chroot jail.
296 The @code{--jail} option provides a more flexible alternative to
297 @code{--safe} when LilyPond formatting is available through a web
298 server or whenever LilyPond executes externally provided
301 The @code{--jail} option works by changing the root of @command{lilypond} to
302 @var{jail} just before starting the actual compilation process. The user
303 and group are then changed to match those provided, and the current
304 directory is changed to @var{dir}. This setup guarantees that it is not
305 possible (at least in theory) to escape from the jail. Note that for
306 @code{--jail} to work @command{lilypond} must be run as root, which is usually
307 accomplished in a safe way using @command{sudo}.
309 Setting up a jail is a slightly delicate matter, as we must be sure that
310 LilyPond is able to find whatever it needs to compile the source
311 @emph{inside the jail}. A typical setup comprises the following items:
314 @item Setting up a separate filesystem
315 A separate filesystem should be created for LilyPond, so that it can be
316 mounted with safe options such as @code{noexec}, @code{nodev}, and
317 @code{nosuid}. In this way, it is impossible to run executables or to
318 write directly to a device from LilyPond. If you do not want to create a
319 separate partition, just create a file of reasonable size and use it to
320 mount a loop device. A separate filesystem also guarantees that LilyPond
321 cannot write more space than it is allowed.
323 @item Setting up a separate user
324 A separate user and group (say, @code{lily}/@code{lily}) with low
325 privileges should be used to run LilyPond inside the jail. There should
326 be a single directory writable by this user, which should be passed in
329 @item Preparing the jail
330 LilyPond needs to read a number of files while running. All these files
331 are to be copied into the jail, under the same path they appear in the
332 real root filesystem. The entire content of the LilyPond installation
333 (e.g., @file{/usr/share/lilypond})
336 If problems arise, the simplest way to trace them down is to run
337 LilyPond using @command{strace}, which will allow you to determine which
340 @item Running LilyPond
341 In a jail mounted with @code{noexec} it is impossible to execute any external
342 program. Therefore LilyPond must be run with a backend that does not
343 require any such program. As we already mentioned, it must be also run
344 with superuser privileges (which, of course, it will lose immediately),
345 possibly using @command{sudo}. It is a good idea to limit the number of
346 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
347 -t}), and, if your operating system supports it, the amount of memory
348 that can be allocated.
353 Show version information.
356 Be verbose: show full paths of all files read, and give timing
360 Show the warranty with which GNU LilyPond comes. (It comes with
361 @strong{NO WARRANTY}!)
364 @node Environment variables
365 @subsection Environment variables
369 @cindex LILYPOND_DATADIR
371 @command{lilypond} recognizes the following environment variables:
373 @item LILYPOND_DATADIR
374 This specifies a directory where locale messages and
375 data files will be looked up by default. The directory should contain
376 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
379 This selects the language for the warning messages.
381 @item LILYPOND_GC_YIELD
382 With this variable the memory footprint and performance can be
383 adjusted. It is a percentage tunes memory management behavior. With
384 higher values, the program uses more memory, with smaller values, it
385 uses more CPU time. The default value is @code{70}.
391 @section Error messages
393 @cindex error messages
394 Different error messages can appear while compiling a file:
400 Something looks suspect. If you are requesting something out of the
401 ordinary then you will understand the message, and can ignore it.
402 However, warnings usually indicate that something is wrong with the
406 Something is definitely wrong. The current processing step (parsing,
407 interpreting, or formatting) will be finished, but the next step will
413 Something is definitely wrong, and LilyPond cannot continue. This
414 happens rarely. The most usual cause is misinstalled fonts.
417 @cindex trace, Scheme
420 Errors that occur while executing Scheme code are caught by the Scheme
421 interpreter. If running with the verbose option (@code{-V} or
422 @code{--verbose}) then a call trace of the offending
423 function call is printed.
425 @item Programming error
426 @cindex Programming error
427 There was some internal inconsistency. These error messages are
428 intended to help the programmers and debuggers. Usually, they can be
429 ignored. Sometimes, they come in such big quantities that they obscure
432 @item Aborted (core dumped)
433 This signals a serious programming error that caused the program to
434 crash. Such errors are considered critical. If you stumble on one,
438 @cindex errors, message format
439 If warnings and errors can
440 be linked to some part of the input file, then error messages have the
444 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
445 @var{offending input line}
448 A line-break is inserted in the offending line to indicate the column
449 where the error was found. For example,
452 test.ly:2:19: error: not a duration: 5
457 These locations are LilyPond's best guess about where the warning or
458 error occurred, but (by their very nature) warnings and errors occur
459 when something unexpected happens. If you can't see an error in the
460 indicated line of your input file, try checking one or two lines
461 above the indicated position.
464 @node Updating files with convert-ly
465 @section Updating files with @command{convert-ly}
467 @cindex Updating a LilyPond file
470 The LilyPond input syntax is routinely changed to simplify it or improve
471 it in different ways. As a side effect of this, the LilyPond interpreter
472 often is no longer compatible with older input files. To remedy this,
473 the program @command{convert-ly} can be used to deal with most of the
474 syntax changes between LilyPond versions.
477 * Invoking convert-ly::
478 * Command line options for convert-ly::
479 * Problems with convert-ly::
482 @node Invoking convert-ly
483 @subsection Invoking @command{convert-ly}
485 @command{convert-ly} uses @code{\version} statements in the input
486 file to detect the old version number. In most cases, to upgrade
487 your input file it is sufficient to run
490 convert-ly -e myfile.ly
494 in the directory containing the file. This will upgrade
495 @code{myfile.ly} in-place and preserve the original file in
498 To convert all the input files in a directory together use
504 Alternatively, if you want to specify a different name for the
505 upgraded file, preserving the original file and name unchanged,
509 convert-ly myfile.ly > mynewfile.ly
512 @command{convert-ly} always converts up to the last syntax change
513 handled by it. This means that the @code{\version} number left in
514 the file is usually lower than the version of @command{convert-ly}
517 The program will list the version numbers for which conversions
518 have been made. If no version numbers are listed the file is
522 MacOS@tie{}X users may execute these commands under the menu entry
523 @code{Compile > Update syntax}.
525 Windows users should enter these commands in a Command Prompt window,
526 which is usually found under
527 @code{Start > Accessories > Command Prompt}.
529 @node Command line options for convert-ly
530 @subsection Command line options for @command{convert-ly}
532 In general, the program is invoked as follows:
535 convert-ly [@var{option}]@dots{} @var{filename}@dots{}
539 The following options can be given:
543 Apply the conversions direct to the input file, modifying it
546 @item -f,--from=@var{from-patchlevel}
547 Set the version to convert from. If this is not set, @command{convert-ly}
548 will guess this, on the basis of @code{\version} strings in the file.
549 E.g. @code{--from=2.10.25}
551 @item -n,--no-version
552 Normally, @command{convert-ly} adds a @code{\version} indicator
553 to the output. Specifying this option suppresses this.
555 @item -s, --show-rules
556 Show all known conversions and exit.
558 @item --to=@var{to-patchlevel}
559 Set the goal version of the conversion. It defaults to the latest
560 available version. E.g. @code{--to=2.12.2}
566 To upgrade LilyPond fragments in texinfo files, use
569 convert-ly --from=... --to=... --no-version *.itely
572 To see the changes in the LilyPond syntax between two versions, use
575 convert-ly --from=... --to=... -s
579 @node Problems with convert-ly
580 @subsection Problems with @code{convert-ly}
582 When running convert-ly in a Command Prompt window under Windows
583 on a file which has spaces in the filename or in the path to it,
584 it is necessary to surround the entire file name with three (!)
585 sets of double quotes:
588 convert-ly """D:/My Scores/Ode.ly""" > """D:/My Scores/new Ode.ly"""
591 If the simple @command{convert-ly -e *.ly} command fails because the
592 expanded command line becomes too long, the @command{convert-ly}
593 command may be placed in a loop instead. This example for UNIX
594 will upgrade all @code{.ly} files in the current directory
597 for f in *.ly; do convert-ly -e $f; done;
600 In the Windows Command Prompt window the corresponding command is
603 for %x in (*.ly) do convert-ly -e """%x"""
606 Not all language changes are handled. Only one output option can be
607 specified. Automatically updating scheme and LilyPond scheme
608 interfaces is quite unlikely; be prepared to tweak scheme code
612 There are a few things that the convert-ly cannot handle. Here's a list
613 of limitations that the community has complained about.
615 This bug report structure has been chosen because convert-ly has a
616 structure that doesn't allow to smoothly implement all needed changes.
617 Thus this is just a wishlist, placed here for reference.
620 Doesn't always convert figured bass correctly, specifically things like {<
621 >}. Mats' comment on working around this:
622 To be able to run convert-ly
623 on it, I first replaced all occurrences of '{<' to some dummy like '{#'
624 and similarly I replaced '>}' with '&}'. After the conversion, I could
625 then change back from '{ #' to '{ <' and from '& }' to '> }'.
626 Doesn't convert all text markup correctly. In the old markup syntax,
627 it was possible to group a number of markup commands together within
629 -#'((bold italic) "string")
630 This will incorrectly be converted into
631 -\markup{{\bold italic} "string"}
632 instead of the correct
633 -\markup{\bold \italic "string"}
635 Doesn't handle \partcombine
636 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
639 \magnify isn't changed to \fontsize.
640 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
641 remove-tag isn't changed.
642 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
643 first-page-number isn't changed.
644 - first-page-number no => print-first-page-number = ##f
645 Line breaks in header strings aren't converted.
646 - \\\\ as line break in \header strings => \markup \center-align <
647 "First Line" "Second Line" >
648 Crescendo and decrescendo terminators aren't converted.
652 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
655 \markup{ \center-align <{ ... }> } should be converted to:
656 \markup{ \center-align {\line { ... }} }
657 but now, \line is missing.
659 Special LaTeX characters such as $~$ in text are not converted to UTF8.
661 \score{} must now begin with a music expression. Anything else
662 (particularly \header{}) must come after the music.
667 @section Reporting bugs
670 @cindex reporting bugs
672 If you have input that results in a crash or an erroneous output, then
673 that is a bug. There is a list of current bugs on our Google bug tracker,
675 @uref{http://code.google.com/p/lilypond/issues/list}
677 If you have discovered a bug which is not listed, please report the
678 bug by following the directions on
680 @uref{http://lilypond.org/web/devel/participating/bugs}
682 Please construct and submit minimal examples of bugs in reports. We do not
683 have the resources to investigate reports which are not as small as possible.