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.
11 @node Running LilyPond
12 @chapter Running LilyPond
14 This chapter details the technicalities of running LilyPond.
18 * Command-line usage::
20 * Updating files with convert-ly::
28 Most users run LilyPond through a GUI; see @ruser{First steps} if
29 you have not read this already.
32 @node Command-line usage
33 @section Command-line usage
35 This section contains extra information about using LilyPond on the
36 command-line. This may be desirable to pass extra options to the
37 program. In addition, there are certain extra @q{helper} programs (such
38 as @code{midi2ly}) which are only available on the command-line.
40 By @q{command-line}, we mean the command line in the operating system.
41 Windows users might be more familiar with the terms @q{DOS shell} or
42 @q{command shell}; OSX users might be more familiar with the terms
43 @q{terminal} or @q{console}. OSX users should also consult @ref{MacOS X
46 Describing how to use this part of an operating system is outside the
47 scope of this manual; please consult other documentation on this topic
48 if you are unfamiliar with the command-line.
51 @subsection Invoking lilypond
53 @cindex Invoking LilyPond
54 @cindex command line options
55 @cindex options, command line
59 The @code{lilypond} executable may be called as follows from the command line.
62 lilypond [@var{option}]@dots{} @var{file}@dots{}
66 When invoked with a filename that has no extension, the @file{.ly}
67 extension is tried first. To read input from stdin, use a
68 dash (@code{-}) for @var{file}.
70 When @file{filename.ly} is processed it will produce
71 @file{filename.tex} as output (or @file{filename.ps} for PostScript
72 output). If @file{filename.ly} contains more than one @code{\score}
73 block, then the rest of the scores will be output in numbered files,
74 starting with @file{filename-1.tex}. Several files can be specified;
75 they will each be processed independently. @footnote{The status of
76 GUILE is not reset after processing a @code{.ly} file, so be careful
77 not to change any system defaults from within Scheme.}
79 In addition, the value of @code{output-suffix} will be inserted between
80 the basename and the number. An input file containing
83 #(define output-suffix "violin")
85 #(define output-suffix "cello")
90 will output @var{base}@file{-violin.ps} and
91 @var{base}@file{-cello-1.ps}.
95 @subsection Command line options
97 The following options are supported:
101 @item -e,--evaluate=@var{expr}
102 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
103 Multiple @code{-e} options may be given, they will be evaluated
106 The expression will be evaluated in the @code{guile-user} module, so
107 if you want to use definitions in @var{expr}, use
110 lilypond -e '(define-public a 42)'
114 on the command-line, and include
117 #(use-modules (guile-user))
121 at the top of the @code{.ly} file.
123 @item -f,--format=@var{format}
124 which formats should be written. Choices for @code{format} are
125 @code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
127 Example: @code{lilypond -fpng filename.ly}
131 @item -d,--define-default=@var{var}=@var{val}
132 This sets the internal program option @var{var} to the Scheme value
133 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
134 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
136 @cindex point and click, command line
145 -dpoint-and-click='#f'
148 Here are a few interesting options.
152 Running @code{lilypond -dhelp} will print all of the @code{-d} options
156 This option sets the default paper-size,
158 -dpaper-size=\"letter\"
162 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
166 Do not trust the @code{.ly} input.
168 When LilyPond formatting is available through a web server, either the
169 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
170 @code{--safe} option will prevent inline Scheme code from wreaking
177 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
182 The @code{-dsafe} option works by evaluating in-line Scheme
183 expressions in a special safe module. This safe module is derived from
184 GUILE @file{safe-r5rs} module, but adds a number of functions of the
185 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
187 In addition, safe mode disallows @code{\include} directives and
188 disables the use of backslashes in @TeX{} strings.
190 In safe mode, it is not possible to import LilyPond variables
193 safe does @emph{not} detect resource overuse. It is still possible to
194 make the program hang indefinitely, for example by feeding cyclic data
195 structures into the backend. Therefore, if using LilyPond on a
196 publicly accessible webserver, the process should be limited in both
197 CPU and memory usage.
199 The safe mode will prevent many useful LilyPond snippets from being
200 compiled. The @code{--jail} is a more secure alternative, but
201 requires more work to set up.
204 the output format to use for the back-end. Choices for @code{format} are
207 for @TeX{} output, to be processed with La@TeX{}. If present, the file
208 @file{file.textmetrics} is read to determine text extents.
210 dump text strings to @file{.texstr} file, which can be run through
211 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
212 extents of strings of text. @strong{Warning:} this functionality is
213 currently missing due to heavy restructuring of the source code.
216 @cindex PostScript output
218 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
219 these fonts is done. When using oriental character sets, this can
223 for encapsulated PostScript. This dumps every page (system) as a separate
224 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
225 all pages (systems) including fonts.
227 This mode is used by default by lilypond-book.
230 for SVG (Scalable Vector Graphics). This dumps every page as a separate
231 @file{SVG} file, with embedded fonts.
232 @cindex SVG (Scalable Vector Graphics)
233 You need a SVG viewer which supports embedded fonts, or a SVG
234 viewer which is able to replace the embedded fonts with OTF fonts.
235 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
236 (version 0.42 or later), after copying the OTF fonts in directory
237 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
239 for a dump of the raw, internal Scheme-based drawing commands.
243 Example: @code{lilypond -dbackend=svg filename.ly}
245 @cindex output format, setting
248 Generate an output file containing the titles and the first system
251 Generate the full pages, the default. @code{-dno-print-pages} is
252 useful in combination with @code{-dpreview}.
259 Show a summary of usage.
261 @item -H,--header=FIELD
262 Dump a header field to file BASENAME.FIELD
264 @item --include, -I=@var{directory}
265 Add @var{directory} to the search path for input files.
266 @cindex file searching
269 @item -i,--init=@var{file}
270 Set init file to @var{file} (default: @file{init.ly}).
272 @item -o,--output=@var{FILE}
273 Set the default output file to @var{FILE}. The appropriate
274 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
281 Generate DVI files. In this case, the @TeX{} backend should be
282 specified, i.e., @code{-dbackend=tex}.
285 Generate pictures of each page, in PNG format. This implies
286 @code{--ps}. The resolution in DPI of the image may be set with
292 Generate PDF. This implies @code{--ps}.
296 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
297 Run LilyPond in a chroot jail.
299 The @code{--jail} option provides a more flexible alternative to
300 @code{--safe} when LilyPond formatting is available through a web
301 server or whenever LilyPond executes externally provided
304 The @code{--jail} option works by changing the root of LilyPond to
305 @var{jail} just before starting the actual compilation process. The user
306 and group are then changed to match those provided, and the current
307 directory is changed to @var{dir}. This setup guarantees that it is not
308 possible (at least in theory) to escape from the jail. Note that for
309 @code{--jail} to work LilyPond must be run as root, which is usually
310 accomplished in a safe way using @command{sudo}.
312 Setting up a jail is a slightly delicate matter, as we must be sure that
313 LilyPond is able to find whatever it needs to compile the source
314 @emph{inside the jail}. A typical setup comprises the following items:
317 @item Setting up a separate filesystem
318 A separate filesystem should be created for LilyPond, so that it can be
319 mounted with safe options such as @code{noexec}, @code{nodev}, and
320 @code{nosuid}. In this way, it is impossible to run executables or to
321 write directly to a device from LilyPond. If you do not want to create a
322 separate partition, just create a file of reasonable size and use it to
323 mount a loop device. A separate filesystem also guarantees that LilyPond
324 cannot write more space than it is allowed.
326 @item Setting up a separate user
327 A separate user and group (say, @code{lily}/@code{lily}) with low
328 privileges should be used to run LilyPond inside the jail. There should
329 be a single directory writable by this user, which should be passed in
332 @item Preparing the jail
333 LilyPond needs to read a number of files while running. All these files
334 are to be copied into the jail, under the same path they appear in the
335 real root filesystem. The entire content of the LilyPond installation
336 (e.g., @file{/usr/share/lilypond})
339 If problems arise, the simplest way to trace them down is to run
340 LilyPond using @command{strace}, which will allow you to determine which
343 @item Running LilyPond
344 In a jail mounted with @code{noexec} it is impossible to execute any external
345 program. Therefore LilyPond must be run with a backend that does not
346 require any such program. As we already mentioned, it must be also run
347 with superuser privileges (which, of course, it will lose immediately),
348 possibly using @command{sudo}. It is a good idea to limit the number of
349 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
350 -t}), and, if your operating system supports it, the amount of memory
351 that can be allocated.
356 Show version information.
359 Be verbose: show full paths of all files read, and give timing
363 Show the warranty with which GNU LilyPond comes. (It comes with
364 @strong{NO WARRANTY}!)
368 @subsection Environment variables
372 @cindex LILYPOND_DATADIR
374 @code{Lilypond} recognizes the following environment variables:
376 @item LILYPOND_DATADIR
377 This specifies a directory where locale messages and
378 data files will be looked up by default. The directory should contain
379 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
382 This selects the language for the warning messages.
384 @item LILYPOND_GC_YIELD
385 With this variable the memory footprint and performance can be
386 adjusted. It is a percentage tunes memory management behavior. With
387 higher values, the program uses more memory, with smaller values, it
388 uses more CPU time. The default value is @code{70}.
394 @section Error messages
396 @cindex error messages
397 Different error messages can appear while compiling a file:
403 Something looks suspect. If you are requesting something out of the
404 ordinary then you will understand the message, and can ignore it.
405 However, warnings usually indicate that something is wrong with the
409 Something is definitely wrong. The current processing step (parsing,
410 interpreting, or formatting) will be finished, but the next step will
416 Something is definitely wrong, and LilyPond cannot continue. This
417 happens rarely. The most usual cause is misinstalled fonts.
420 @cindex trace, Scheme
423 Errors that occur while executing Scheme code are caught by the Scheme
424 interpreter. If running with the verbose option (@code{-V} or
425 @code{--verbose}) then a call trace of the offending
426 function call is printed.
428 @item Programming error
429 @cindex Programming error
430 There was some internal inconsistency. These error messages are
431 intended to help the programmers and debuggers. Usually, they can be
432 ignored. Sometimes, they come in such big quantities that they obscure
435 @item Aborted (core dumped)
436 This signals a serious programming error that caused the program to
437 crash. Such errors are considered critical. If you stumble on one,
441 @cindex errors, message format
442 If warnings and errors can
443 be linked to some part of the input file, then error messages have the
447 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
448 @var{offending input line}
451 A line-break is inserted in the offending line to indicate the column
452 where the error was found. For example,
455 test.ly:2:19: error: not a duration: 5:
460 These locations are LilyPond's best guess about where the warning or
461 error occurred, but (by their very nature) warnings and errors occur
462 when something unexpected happens. If you can't see an error in the
463 indicated line of your input file, try checking one or two lines
464 above the indicated position.
467 @node Updating files with convert-ly
468 @section Updating with @command{convert-ly}
470 @cindex Updating a LilyPond file
473 The LilyPond input syntax is routinely changed to simplify it or improve
474 it in different ways. As a side effect of this, the LilyPond interpreter
475 often is no longer compatible with older input files. To remedy this,
476 the program @command{convert-ly} can be used to deal with most of the
477 syntax changes between LilyPond versions.
479 It uses @code{\version} statements in the input files to detect the
480 old version number. In most cases, to upgrade your input file it is
484 convert-ly -e myfile.ly
488 MacOS X users may execute this command under the menu entry
489 @code{Compile > Update syntax}.
491 If there are no changes to myfile.ly and file called myfile.ly.NEW
492 is created, then myfile.ly is already updated.
494 @subsection Command line options
496 @command{convert-ly} always converts up to the last syntax change handled by
497 it. This means that the @code{\version} number left in the file is
498 usually lower than the version of @command{convert-ly} itself.
500 To upgrade LilyPond fragments in texinfo files, use
503 convert-ly --from=... --to=... --no-version *.itely
506 To see the changes in the LilyPond syntax between two versions, use
509 convert-ly --from=... --to=... -s
512 To upgrade many files at once, combine @code{convert-ly} with
513 standard unix commands. This example will upgrade all @code{.ly}
514 files in the current directory
517 for f in *.ly; do convert-ly -e $f; done;
520 In general, the program is invoked as follows:
523 convert-ly [@var{option}]@dots{} @var{file}@dots{}
527 The following options can be given:
531 Do an inline edit of the input file. Overrides @code{--output}.
533 @item -f,--from=@var{from-patchlevel}
534 Set the version to convert from. If this is not set, @command{convert-ly}
535 will guess this, on the basis of @code{\version} strings in the file.
537 @item -n,--no-version
538 Normally, @command{convert-ly} adds a @code{\version} indicator
539 to the output. Specifying this option suppresses this.
541 @item -s, --show-rules
542 Show all known conversions and exit.
544 @item --to=@var{to-patchlevel}
545 Set the goal version of the conversion. It defaults to the latest
554 * Problems with convert-ly::
558 @node Problems with convert-ly
559 @subsection Problems with @code{convert-ly}
561 Not all language changes are handled. Only one output option can be
562 specified. Automatically updating scheme and lilypond scheme
563 interfaces is quite unlikely; be prepared to tweak scheme code
567 There are a few things that the convert-ly cannot handle. Here's a list
568 of limitations that the community has complained about.
570 This bug report structure has been chosen because convert-ly has a
571 structure that doesn't allow to smoothly implement all needed changes.
572 Thus this is just a wishlist, placed here for reference.
575 Doesn't always convert figured bass correctly, specifically things like {<
576 >}. Mats' comment on working around this:
577 To be able to run convert-ly
578 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
579 and similarly I replaced '>}' with '&}'. After the conversion, I could
580 then change back from '{ #' to '{ <' and from '& }' to '> }'.
581 Doesn't convert all text markup correctly. In the old markup syntax,
582 it was possible to group a number of markup commands together within
584 -#'((bold italic) "string")
585 This will incorrectly be converted into
586 -\markup{{\bold italic} "string"}
587 instead of the correct
588 -\markup{\bold \italic "string"}
590 Doesn't handle \partcombine
591 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
594 \magnify isn't changed to \fontsize.
595 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
596 remove-tag isn't changed.
597 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
598 first-page-number isn't changed.
599 - first-page-number no => print-first-page-number = ##f
600 Line breaks in header strings aren't converted.
601 - \\\\ as line break in \header strings => \markup \center-align <
602 "First Line" "Second Line" >
603 Crescendo and decrescendo terminators aren't converted.
607 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
610 \markup{ \center-align <{ ... }> } should be converted to:
611 \markup{ \center-align {\line { ... }} }
612 but now, \line is missing.
614 Special LaTeX characters such as $~$ in text are not converted to UTF8.
616 \score{} must now begin with a music expression. Anything else
617 (particularly \header{}) must come after the music.
622 @section Reporting bugs
625 @cindex reporting bugs
627 If you have input that results in a crash or an erroneous output, then
628 that is a bug. There is a list of current bugs on our google bug tracker,
630 @uref{http://code.google.com/p/lilypond/issues/list}
632 If you have discovered a bug which is not listed, please report the
633 bug by following the directions on
635 @uref{http://lilypond.org/web/devel/participating/bugs}
637 Please construct submit @ruser{Minimal examples}, of bug reports. We do not
638 have the resources to investigate reports which are not as small as possible.