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 @ruser{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{MacOS X
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.
53 @subsection Invoking lilypond
55 @cindex Invoking LilyPond
56 @cindex command line options
57 @cindex options, command line
61 The @command{lilypond} executable may be called as follows from the command line.
64 lilypond [@var{option}]@dots{} @var{file}@dots{}
68 When invoked with a filename that has no extension, the @file{.ly}
69 extension is tried first. To read input from stdin, use a
70 dash (@code{-}) for @var{file}.
72 When @file{filename.ly} is processed it will produce
73 @file{filename.tex} as output (or @file{filename.ps} for PostScript
74 output). If @file{filename.ly} contains more than one @code{\score}
75 block, then the rest of the scores will be output in numbered files,
76 starting with @file{filename-1.tex}. Several files can be specified;
77 they will each be processed independently. @footnote{The status of
78 GUILE is not reset after processing a @code{.ly} file, so be careful
79 not to change any system defaults from within Scheme.}
81 In addition, the value of @code{output-suffix} will be inserted between
82 the basename and the number. An input file containing
85 #(define output-suffix "violin")
87 #(define output-suffix "cello")
92 will output @var{base}@file{-violin.ps} and
93 @var{base}@file{-cello-1.ps}.
97 @subsection Command line options
99 The following options are supported:
103 @item -e,--evaluate=@var{expr}
104 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
105 Multiple @code{-e} options may be given, they will be evaluated
108 The expression will be evaluated in the @code{guile-user} module, so
109 if you want to use definitions in @var{expr}, use
112 lilypond -e '(define-public a 42)'
116 on the command-line, and include
119 #(use-modules (guile-user))
123 at the top of the @code{.ly} file.
125 @item -f,--format=@var{format}
126 which formats should be written. Choices for @code{format} are
127 @code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
129 Example: @code{lilypond -fpng filename.ly}
133 @item -d,--define-default=@var{var}=@var{val}
134 This sets the internal program option @var{var} to the Scheme value
135 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
136 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
138 @cindex point and click, command line
147 -dpoint-and-click='#f'
150 Here are a few interesting options.
154 Running @code{lilypond -dhelp} will print all of the @code{-d} options
158 This option sets the default paper-size,
160 -dpaper-size=\"letter\"
164 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
168 Do not trust the @code{.ly} input.
170 When LilyPond formatting is available through a web server, either the
171 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
172 @code{--safe} option will prevent inline Scheme code from wreaking
179 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
184 The @code{-dsafe} option works by evaluating in-line Scheme
185 expressions in a special safe module. This safe module is derived from
186 GUILE @file{safe-r5rs} module, but adds a number of functions of the
187 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
189 In addition, safe mode disallows @code{\include} directives and
190 disables the use of backslashes in @TeX{} strings.
192 In safe mode, it is not possible to import LilyPond variables
195 safe does @emph{not} detect resource overuse. It is still possible to
196 make the program hang indefinitely, for example by feeding cyclic data
197 structures into the backend. Therefore, if using LilyPond on a
198 publicly accessible webserver, the process should be limited in both
199 CPU and memory usage.
201 The safe mode will prevent many useful LilyPond snippets from being
202 compiled. The @code{--jail} is a more secure alternative, but
203 requires more work to set up.
206 the output format to use for the back-end. Choices for @code{format} are
209 for @TeX{} output, to be processed with La@TeX{}. If present, the file
210 @file{file.textmetrics} is read to determine text extents.
212 dump text strings to @file{.texstr} file, which can be run through
213 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
214 extents of strings of text. @strong{Warning:} this functionality is
215 currently missing due to heavy restructuring of the source code.
218 @cindex PostScript output
220 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
221 these fonts is done. When using oriental character sets, this can
225 for encapsulated PostScript. This dumps every page (system) as a separate
226 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
227 all pages (systems) including fonts.
229 This mode is used by default by lilypond-book.
232 for SVG (Scalable Vector Graphics). This dumps every page as a separate
233 @file{SVG} file, with embedded fonts.
234 @cindex SVG (Scalable Vector Graphics)
235 You need a SVG viewer which supports embedded fonts, or a SVG
236 viewer which is able to replace the embedded fonts with OTF fonts.
237 Under UNIX, you may use @uref{http://www.inkscape.org,Inkscape}
238 (version 0.42 or later), after copying the OTF fonts in directory
239 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
241 for a dump of the raw, internal Scheme-based drawing commands.
245 Example: @code{lilypond -dbackend=svg filename.ly}
247 @cindex output format, setting
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=FIELD
264 Dump a header field to file BASENAME.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 (ie @code{.pdf} for pdf, @code{.tex}
283 Generate DVI files. In this case, the @TeX{} backend should be
284 specified, i.e., @code{-dbackend=tex}.
287 Generate pictures of each page, in PNG format. This implies
288 @code{--ps}. The resolution in DPI of the image may be set with
294 Generate PDF. This implies @code{--ps}.
298 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
299 Run @command{lilypond} in a chroot jail.
301 The @code{--jail} option provides a more flexible alternative to
302 @code{--safe} when LilyPond formatting is available through a web
303 server or whenever LilyPond executes externally provided
306 The @code{--jail} option works by changing the root of @command{lilypond} to
307 @var{jail} just before starting the actual compilation process. The user
308 and group are then changed to match those provided, and the current
309 directory is changed to @var{dir}. This setup guarantees that it is not
310 possible (at least in theory) to escape from the jail. Note that for
311 @code{--jail} to work @command{lilypond} must be run as root, which is usually
312 accomplished in a safe way using @command{sudo}.
314 Setting up a jail is a slightly delicate matter, as we must be sure that
315 LilyPond is able to find whatever it needs to compile the source
316 @emph{inside the jail}. A typical setup comprises the following items:
319 @item Setting up a separate filesystem
320 A separate filesystem should be created for LilyPond, so that it can be
321 mounted with safe options such as @code{noexec}, @code{nodev}, and
322 @code{nosuid}. In this way, it is impossible to run executables or to
323 write directly to a device from LilyPond. If you do not want to create a
324 separate partition, just create a file of reasonable size and use it to
325 mount a loop device. A separate filesystem also guarantees that LilyPond
326 cannot write more space than it is allowed.
328 @item Setting up a separate user
329 A separate user and group (say, @code{lily}/@code{lily}) with low
330 privileges should be used to run LilyPond inside the jail. There should
331 be a single directory writable by this user, which should be passed in
334 @item Preparing the jail
335 LilyPond needs to read a number of files while running. All these files
336 are to be copied into the jail, under the same path they appear in the
337 real root filesystem. The entire content of the LilyPond installation
338 (e.g., @file{/usr/share/lilypond})
341 If problems arise, the simplest way to trace them down is to run
342 LilyPond using @command{strace}, which will allow you to determine which
345 @item Running LilyPond
346 In a jail mounted with @code{noexec} it is impossible to execute any external
347 program. Therefore LilyPond must be run with a backend that does not
348 require any such program. As we already mentioned, it must be also run
349 with superuser privileges (which, of course, it will lose immediately),
350 possibly using @command{sudo}. It is a good idea to limit the number of
351 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
352 -t}), and, if your operating system supports it, the amount of memory
353 that can be allocated.
358 Show version information.
361 Be verbose: show full paths of all files read, and give timing
365 Show the warranty with which GNU LilyPond comes. (It comes with
366 @strong{NO WARRANTY}!)
370 @subsection Environment variables
374 @cindex LILYPOND_DATADIR
376 @command{lilypond} recognizes the following environment variables:
378 @item LILYPOND_DATADIR
379 This specifies a directory where locale messages and
380 data files will be looked up by default. The directory should contain
381 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
384 This selects the language for the warning messages.
386 @item LILYPOND_GC_YIELD
387 With this variable the memory footprint and performance can be
388 adjusted. It is a percentage tunes memory management behavior. With
389 higher values, the program uses more memory, with smaller values, it
390 uses more CPU time. The default value is @code{70}.
396 @section Error messages
398 @cindex error messages
399 Different error messages can appear while compiling a file:
405 Something looks suspect. If you are requesting something out of the
406 ordinary then you will understand the message, and can ignore it.
407 However, warnings usually indicate that something is wrong with the
411 Something is definitely wrong. The current processing step (parsing,
412 interpreting, or formatting) will be finished, but the next step will
418 Something is definitely wrong, and LilyPond cannot continue. This
419 happens rarely. The most usual cause is misinstalled fonts.
422 @cindex trace, Scheme
425 Errors that occur while executing Scheme code are caught by the Scheme
426 interpreter. If running with the verbose option (@code{-V} or
427 @code{--verbose}) then a call trace of the offending
428 function call is printed.
430 @item Programming error
431 @cindex Programming error
432 There was some internal inconsistency. These error messages are
433 intended to help the programmers and debuggers. Usually, they can be
434 ignored. Sometimes, they come in such big quantities that they obscure
437 @item Aborted (core dumped)
438 This signals a serious programming error that caused the program to
439 crash. Such errors are considered critical. If you stumble on one,
443 @cindex errors, message format
444 If warnings and errors can
445 be linked to some part of the input file, then error messages have the
449 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
450 @var{offending input line}
453 A line-break is inserted in the offending line to indicate the column
454 where the error was found. For example,
457 test.ly:2:19: error: not a duration: 5:
462 These locations are LilyPond's best guess about where the warning or
463 error occurred, but (by their very nature) warnings and errors occur
464 when something unexpected happens. If you can't see an error in the
465 indicated line of your input file, try checking one or two lines
466 above the indicated position.
469 @node Updating files with convert-ly
470 @section Updating with @command{convert-ly}
472 @cindex Updating a LilyPond file
475 The LilyPond input syntax is routinely changed to simplify it or improve
476 it in different ways. As a side effect of this, the LilyPond interpreter
477 often is no longer compatible with older input files. To remedy this,
478 the program @command{convert-ly} can be used to deal with most of the
479 syntax changes between LilyPond versions.
481 It uses @code{\version} statements in the input files to detect the
482 old version number. In most cases, to upgrade your input file it is
486 convert-ly -e myfile.ly
490 MacOS@tie{}X users may execute this command under the menu entry
491 @code{Compile > Update syntax}.
493 If there are no changes to myfile.ly and file called myfile.ly.NEW
494 is created, then myfile.ly is already updated.
496 @subsection Command line options
498 @command{convert-ly} always converts up to the last syntax change handled by
499 it. This means that the @code{\version} number left in the file is
500 usually lower than the version of @command{convert-ly} itself.
502 To upgrade LilyPond fragments in texinfo files, use
505 convert-ly --from=... --to=... --no-version *.itely
508 To see the changes in the LilyPond syntax between two versions, use
511 convert-ly --from=... --to=... -s
514 To upgrade many files at once, combine @code{convert-ly} with
515 standard UNIX commands. This example will upgrade all @code{.ly}
516 files in the current directory
519 for f in *.ly; do convert-ly -e $f; done;
522 In general, the program is invoked as follows:
525 convert-ly [@var{option}]@dots{} @var{file}@dots{}
529 The following options can be given:
533 Do an inline edit of the input file. Overrides @code{--output}.
535 @item -f,--from=@var{from-patchlevel}
536 Set the version to convert from. If this is not set, @command{convert-ly}
537 will guess this, on the basis of @code{\version} strings in the file.
539 @item -n,--no-version
540 Normally, @command{convert-ly} adds a @code{\version} indicator
541 to the output. Specifying this option suppresses this.
543 @item -s, --show-rules
544 Show all known conversions and exit.
546 @item --to=@var{to-patchlevel}
547 Set the goal version of the conversion. It defaults to the latest
556 * Problems with convert-ly::
560 @node Problems with convert-ly
561 @subsection Problems with @code{convert-ly}
563 Not all language changes are handled. Only one output option can be
564 specified. Automatically updating scheme and LilyPond scheme
565 interfaces is quite unlikely; be prepared to tweak scheme code
569 There are a few things that the convert-ly cannot handle. Here's a list
570 of limitations that the community has complained about.
572 This bug report structure has been chosen because convert-ly has a
573 structure that doesn't allow to smoothly implement all needed changes.
574 Thus this is just a wishlist, placed here for reference.
577 Doesn't always convert figured bass correctly, specifically things like {<
578 >}. Mats' comment on working around this:
579 To be able to run convert-ly
580 on it, I first replaced all occurrences of '{<' to some dummy like '{#'
581 and similarly I replaced '>}' with '&}'. After the conversion, I could
582 then change back from '{ #' to '{ <' and from '& }' to '> }'.
583 Doesn't convert all text markup correctly. In the old markup syntax,
584 it was possible to group a number of markup commands together within
586 -#'((bold italic) "string")
587 This will incorrectly be converted into
588 -\markup{{\bold italic} "string"}
589 instead of the correct
590 -\markup{\bold \italic "string"}
592 Doesn't handle \partcombine
593 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
596 \magnify isn't changed to \fontsize.
597 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
598 remove-tag isn't changed.
599 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
600 first-page-number isn't changed.
601 - first-page-number no => print-first-page-number = ##f
602 Line breaks in header strings aren't converted.
603 - \\\\ as line break in \header strings => \markup \center-align <
604 "First Line" "Second Line" >
605 Crescendo and decrescendo terminators aren't converted.
609 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
612 \markup{ \center-align <{ ... }> } should be converted to:
613 \markup{ \center-align {\line { ... }} }
614 but now, \line is missing.
616 Special LaTeX characters such as $~$ in text are not converted to UTF8.
618 \score{} must now begin with a music expression. Anything else
619 (particularly \header{}) must come after the music.
624 @section Reporting bugs
627 @cindex reporting bugs
629 If you have input that results in a crash or an erroneous output, then
630 that is a bug. There is a list of current bugs on our Google bug tracker,
632 @uref{http://code.google.com/p/lilypond/issues/list}
634 If you have discovered a bug which is not listed, please report the
635 bug by following the directions on
637 @uref{http://lilypond.org/web/devel/participating/bugs}
639 Please construct submit @ruser{Minimal examples}, of bug reports. We do not
640 have the resources to investigate reports which are not as small as possible.