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.
16 Some of these commands are run from the command-line. By
17 @q{command-line}, we mean the command
18 line in the operating system. Windows users
19 might be more familiar with the terms @q{DOS shell} or
20 @q{command shell}; OSX users might be more familiar with the
21 terms @q{terminal} or @q{console}. OSX users should also
22 consult @ref{MacOS X on the command-line}.
25 this part of an operating system is outside the scope of this
26 manual; please consult other documentation on this topic if
27 you are unfamiliar with the command-line.
29 These are separate programs from lilypond itself, and are run
30 on the command-line; see @ref{Command-line usage} for more information.
33 * Command-line usage::
35 * Updating files with convert-ly::
40 @node Command-line usage
41 @section Command-line usage
43 This section contains extra information for using LilyPond on the
44 command-line. This may be desirable to pass extra options to the
45 program. In addition, there are certain extra @q{helper} programs (such
46 as @code{midi2ly}) which are only available on the command-line.
48 By @q{command-line}, we mean the command line in the operating system.
49 Windows users might be more familiar with the terms @q{DOS shell} or
50 @q{command shell}; OSX users might be more familiar with the terms
51 @q{terminal} or @q{console}. OSX users should also consult @ref{MacOS X
54 Describing how to use this part of an operating system is outside the
55 scope of this manual; please consult other documentation on this topic
56 if you are unfamiliar with the command-line.
60 @node Invoking lilypond
61 @section Invoking lilypond
63 @cindex Invoking LilyPond
64 @cindex command line options
65 @cindex options, command line
69 The @code{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
81 @file{filename.tex} as output (or @file{filename.ps} for PostScript
82 output). If @file{filename.ly} contains more than one @code{\score}
83 block, then the rest of the scores will be output in numbered files,
84 starting with @file{filename-1.tex}. Several files can be specified;
85 they will each be processed independently. @footnote{The status of
86 GUILE is not reset after processing a @code{.ly} file, so be careful
87 not to change any system defaults from within Scheme.}
89 In addition, the value of @code{output-suffix} will be inserted between
90 the basename and the number. An input file containing
93 #(define output-suffix "violin")
95 #(define output-suffix "cello")
100 will output @var{base}@file{-violin.ps} and
101 @var{base}@file{-cello-1.ps}.
105 @subsection Command line options
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}, @code{png}, @code{tex}, @code{dvi}.
137 Example: @code{lilypond -fpng 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{\"} ).
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 safe 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.
214 the output format to use for the back-end. Choices for @code{format} are
217 for @TeX{} output, to be processed with La@TeX{}. If present, the file
218 @file{file.textmetrics} is read to determine text extents.
220 dump text strings to @file{.texstr} file, which can be run through
221 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
222 extents of strings of text. @strong{Warning:} this functionality is
223 currently missing due to heavy restructuring of the source code.
226 @cindex PostScript output
228 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
229 these fonts is done. When using oriental character sets, this can
233 for encapsulated PostScript. This dumps every page (system) as a separate
234 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
235 all pages (systems) including fonts.
237 This mode is used by default by lilypond-book.
240 for SVG (Scalable Vector Graphics). This dumps every page as a separate
241 @file{SVG} file, with embedded fonts.
242 @cindex SVG (Scalable Vector Graphics)
243 You need a SVG viewer which supports embedded fonts, or a SVG
244 viewer which is able to replace the embedded fonts with OTF fonts.
245 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
246 (version 0.42 or later), after copying the OTF fonts in directory
247 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
249 for a dump of the raw, internal Scheme-based drawing commands.
253 Example: @code{lilypond -dbackend=svg filename.ly}
255 @cindex output format, setting
258 Generate an output file containing the titles and the first system
261 Generate the full pages, the default. @code{-dno-print-pages} is
262 useful in combination with @code{-dpreview}.
269 Show a summary of usage.
271 @item -H,--header=FIELD
272 Dump a header field to file BASENAME.FIELD
274 @item --include, -I=@var{directory}
275 Add @var{directory} to the search path for input files.
276 @cindex file searching
279 @item -i,--init=@var{file}
280 Set init file to @var{file} (default: @file{init.ly}).
282 @item -o,--output=@var{FILE}
283 Set the default output file to @var{FILE}. The appropriate
284 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
291 Generate DVI files. In this case, the @TeX{} backend should be
292 specified, i.e., @code{-dbackend=tex}.
295 Generate pictures of each page, in PNG format. This implies
296 @code{--ps}. The resolution in DPI of the image may be set with
302 Generate PDF. This implies @code{--ps}.
306 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
307 Run LilyPond in a chroot jail.
309 The @code{--jail} option provides a more flexible alternative to
310 @code{--safe} when LilyPond formatting is available through a web
311 server or whenever LilyPond executes externally provided
314 The @code{--jail} option works by changing the root of LilyPond to
315 @var{jail} just before starting the actual compilation process. The user
316 and group are then changed to match those provided, and the current
317 directory is changed to @var{dir}. This setup guarantees that it is not
318 possible (at least in theory) to escape from the jail. Note that for
319 @code{--jail} to work LilyPond must be run as root, which is usually
320 accomplished in a safe way using @command{sudo}.
322 Setting up a jail is a slightly delicate matter, as we must be sure that
323 LilyPond is able to find whatever it needs to compile the source
324 @emph{inside the jail}. A typical setup comprises the following items:
327 @item Setting up a separate filesystem
328 A separate filesystem should be created for LilyPond, so that it can be
329 mounted with safe options such as @code{noexec}, @code{nodev}, and
330 @code{nosuid}. In this way, it is impossible to run executables or to
331 write directly to a device from LilyPond. If you do not want to create a
332 separate partition, just create a file of reasonable size and use it to
333 mount a loop device. A separate filesystem also guarantees that LilyPond
334 cannot write more space than it is allowed.
336 @item Setting up a separate user
337 A separate user and group (say, @samp{lily}/@samp{lily}) with low
338 privileges should be used to run LilyPond inside the jail. There should
339 be a single directory writable by this user, which should be passed in
342 @item Preparing the jail
343 LilyPond needs to read a number of files while running. All these files
344 are to be copied into the jail, under the same path they appear in the
345 real root filesystem. The entire content of the LilyPond installation
346 (e.g., @file{/usr/share/lilypond})
349 If problems arise, the simplest way to trace them down is to run
350 LilyPond using @command{strace}, which will allow you to determine which
353 @item Running LilyPond
354 In a jail mounted with @code{noexec} it is impossible to execute any external
355 program. Therefore LilyPond must be run with a backend that does not
356 require any such program. As we already mentioned, it must be also run
357 with superuser privileges (which, of course, it will lose immediately),
358 possibly using @command{sudo}. It is a good idea to limit the number of
359 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
360 -t}), and, if your operating system supports it, the amount of memory
361 that can be allocated.
366 Show version information.
369 Be verbose: show full paths of all files read, and give timing
373 Show the warranty with which GNU LilyPond comes. (It comes with
374 @strong{NO WARRANTY}!)
378 @subsection Environment variables
382 @cindex LILYPOND_DATADIR
384 @code{Lilypond} recognizes the following environment variables:
386 @item LILYPOND_DATADIR
387 This specifies a directory where locale messages and
388 data files will be looked up by default. The directory should contain
389 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
392 This selects the language for the warning messages.
394 @item LILYPOND_GC_YIELD
395 With this variable the memory footprint and performance can be
396 adjusted. It is a percentage tunes memory management behavior. With
397 higher values, the program uses more memory, with smaller values, it
398 uses more CPU time. The default value is @code{70}.
403 @node Updating files with convert-ly
404 @section Updating with @command{convert-ly}
406 @cindex Updating a LilyPond file
409 The LilyPond input syntax is routinely changed to simplify it or improve
410 it in different ways. As a side effect of this, the LilyPond interpreter
411 often is no longer compatible with older input files. To remedy this,
412 the program @command{convert-ly} can be used to deal with most of the
413 syntax changes between LilyPond versions.
415 It uses @code{\version} statements in the input files to detect the
416 old version number. In most cases, to upgrade your input file it is
417 sufficient to run@footnote{MacOS X users may execute this command
418 under the menu entry @samp{Compile > Update syntax}.}
421 convert-ly -e myfile.ly
424 If there are no changes to myfile.ly and file called myfile.ly.NEW
425 is created, then myfile.ly is already updated.
427 @command{convert-ly} always converts up to the last syntax change handled by
428 it. This means that the @code{\version} number left in the file is
429 usually lower than the version of @command{convert-ly} itself.
431 To upgrade LilyPond fragments in texinfo files, use
434 convert-ly --from=... --to=... --no-version *.itely
437 To see the changes in the LilyPond syntax between two versions, use
440 convert-ly --from=... --to=... -s
443 To upgrade many files at once, combine @code{convert-ly} with
444 standard unix commands. This example will upgrade all @code{.ly}
445 files in the current directory
448 for f in *.ly; do convert-ly -e $f; done;
451 In general, the program is invoked as follows:
454 convert-ly [@var{option}]@dots{} @var{file}@dots{}
458 The following options can be given:
462 Do an inline edit of the input file. Overrides @code{--output}.
464 @item -f,--from=@var{from-patchlevel}
465 Set the version to convert from. If this is not set, @command{convert-ly}
466 will guess this, on the basis of @code{\version} strings in the file.
468 @item -n,--no-version
469 Normally, @command{convert-ly} adds a @code{\version} indicator
470 to the output. Specifying this option suppresses this.
472 @item -s, --show-rules
473 Show all known conversions and exit.
475 @item --to=@var{to-patchlevel}
476 Set the goal version of the conversion. It defaults to the latest
486 Not all language changes are handled. Only one output option can be
487 specified. Automatically updating scheme and lilypond scheme
488 interfaces is quite unlikely; be prepared to tweak scheme code
492 @c We might want to make this a completely new section, along with more
493 @c info about how to upgrade old input files. -gp
496 Copy and paste from CVS, last updated
499 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/
500 convert-ly.txt?rev=HEAD&content-type=text/plain
502 NEW: not exactly copied; this list has been modified. Since we're
503 changing the bug system, it doesn't make sense to copy from
504 the bug CVS any more. I'll figure out something else. -gp
508 There are a few things that the convert-ly cannot handle. Here's a list of
510 that the community has complained about.
512 This bug report structure has been chosen because convert-ly has a structure
514 allow to smoothly implement all needed changes. Thus this is just a wishlist,
519 Doesn't always convert figured bass correctly, specifically things like {<
520 >}. Mats' comment on working around this:
521 To be able to run convert-ly
522 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
523 and similarly I replaced '>}' with '&}'. After the conversion, I could
524 then change back from '{ #' to '{ <' and from '& }' to '> }'.
525 Doesn't convert all text markup correctly. In the old markup syntax,
526 it was possible to group a number of markup commands together within
528 -#'((bold italic) "string")
529 This will incorrectly be converted into
530 -\markup{{\bold italic} "string"}
531 instead of the correct
532 -\markup{\bold \italic "string"}
534 Doesn't handle \partcombine
535 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
538 \magnify isn't changed to \fontsize.
539 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
540 remove-tag isn't changed.
541 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
542 first-page-number isn't changed.
543 - first-page-number no => print-first-page-number = ##f
544 Line breaks in header strings aren't converted.
545 - \\\\ as line break in \header strings => \markup \center-align <
546 "First Line" "Second Line" >
547 Crescendo and decrescendo terminators aren't converted.
551 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
554 \markup{ \center-align <{ ... }> } should be converted to:
555 \markup{ \center-align {\line { ... }} }
556 but now, \line is missing.
558 Special LaTeX characters such as $~$ in text are not converted to UTF8.
560 \score{} must now begin with a music expression. Anything else
561 (particularly \header{}) must come after the music.
566 @section Reporting bugs
569 @cindex reporting bugs
571 If you have input that results in a crash or an erroneous output, then
572 that is a bug. There is a list of current bugs on our google bug tracker,
574 @uref{http://code.google.com/p/lilypond/issues/list}
576 If you have discovered a bug which is not listed, please report the
577 bug by following the directions on
579 @uref{http://lilypond.org/web/devel/participating/bugs}
581 Please construct submit @ruser{Minimal examples}, of bug reports. We do not
582 have the resources to investigate reports which are not as small as possible.
586 @section Error messages
588 @cindex error messages
589 Different error messages can appear while compiling a file:
595 Something looks suspect. If you are requesting something out of the
596 ordinary then you will understand the message, and can ignore it.
597 However, warnings usually indicate that something is wrong with the
601 Something is definitely wrong. The current processing step (parsing,
602 interpreting, or formatting) will be finished, but the next step will
608 Something is definitely wrong, and LilyPond cannot continue. This
609 happens rarely. The most usual cause is misinstalled fonts.
611 @cindex trace, Scheme
615 Errors that occur while executing Scheme code are caught by the Scheme
616 interpreter. If running with the verbose option (@code{-V} or
617 @code{--verbose}) then a call trace of the offending
618 function call is printed.
620 @cindex Programming error
621 @item Programming error
622 There was some internal inconsistency. These error messages are
623 intended to help the programmers and debuggers. Usually, they can be
624 ignored. Sometimes, they come in such big quantities that they obscure
625 other output. In this case, file a bug-report.
627 @item Aborted (core dumped)
628 This signals a serious programming error that caused the program to
629 crash. Such errors are considered critical. If you stumble on one,
635 @cindex errors, message format
636 If warnings and errors can
637 be linked to some part of the input file, then error messages have the
641 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
642 @var{offending input line}
645 A line-break is inserted in the offending line to indicate the column
646 where the error was found. For example,
649 test.ly:2:19: error: not a duration: 5:
654 These locations are LilyPond's best guess about where the warning or
655 error occurred, but (by their very nature) warnings and errors occur
656 when something unexpected happens. If you can't see an error in the
657 indicated line of your input file, try checking one or two lines
658 above the indicated position.