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{Notes for the MacOS X app}.
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.
31 * Updating files with convert-ly::
36 @node Invoking lilypond
37 @section Invoking lilypond
38 @cindex Invoking LilyPond
39 @cindex command line options
40 @cindex options, command line
44 The @code{lilypond} executable may be called as follows from the command line.
47 lilypond [@var{option}]@dots{} @var{file}@dots{}
51 When invoked with a filename that has no extension, the @file{.ly}
52 extension is tried first. To read input from stdin, use a
53 dash (@code{-}) for @var{file}.
55 When @file{filename.ly} is processed it will produce
56 @file{filename.tex} as output (or @file{filename.ps} for PostScript
57 output). If @file{filename.ly} contains more than one @code{\score}
58 block, then the rest of the scores will be output in numbered files,
59 starting with @file{filename-1.tex}. Several files can be specified;
60 they will each be processed independently. @footnote{The status of
61 GUILE is not reset after processing a @code{.ly} file, so be careful
62 not to change any system defaults from within Scheme.}
64 In addition, the value of @code{output-suffix} will be inserted between
65 the basename and the number. An input file containing
68 #(define output-suffix "violin")
70 #(define output-suffix "cello")
75 will output @var{base}@file{-violin.ps} and
76 @var{base}@file{-cello-1.ps}.
80 @subsection Command line options
82 The following options are supported:
86 @item -e,--evaluate=@var{expr}
87 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
88 Multiple @code{-e} options may be given, they will be evaluated
91 The expression will be evaluated in the @code{guile-user} module, so
92 if you want to use definitions in @var{expr}, use
95 lilypond -e '(define-public a 42)'
99 on the command-line, and include
102 #(use-modules (guile-user))
106 at the top of the @code{.ly} file.
108 @item -f,--format=@var{format}
109 which formats should be written. Choices for @code{format} are
110 @code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
112 Example: @code{lilypond -fpng filename.ly}
116 @item -d,--define-default=@var{var}=@var{val}
117 This sets the internal program option @var{var} to the Scheme value
118 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
119 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
121 @cindex point and click, command line
130 -dpoint-and-click='#f'
133 Here are a few interesting options.
137 Running @code{lilypond -dhelp} will print all of the @code{-d} options
141 This option sets the default paper-size,
143 -dpaper-size=\"letter\"
147 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
151 Do not trust the @code{.ly} input.
153 When LilyPond formatting is available through a web server, either the
154 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
155 @code{--safe} option will prevent inline Scheme code from wreaking
162 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
167 The @code{-dsafe} option works by evaluating in-line Scheme
168 expressions in a special safe module. This safe module is derived from
169 GUILE @file{safe-r5rs} module, but adds a number of functions of the
170 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
172 In addition, safe mode disallows @code{\include} directives and
173 disables the use of backslashes in @TeX{} strings.
175 In safe mode, it is not possible to import LilyPond variables
178 safe does @emph{not} detect resource overuse. It is still possible to
179 make the program hang indefinitely, for example by feeding cyclic data
180 structures into the backend. Therefore, if using LilyPond on a
181 publicly accessible webserver, the process should be limited in both
182 CPU and memory usage.
184 The safe mode will prevent many useful LilyPond snippets from being
185 compiled. The @code{--jail} is a more secure alternative, but
186 requires more work to set up.
189 the output format to use for the back-end. Choices for @code{format} are
192 for @TeX{} output, to be processed with La@TeX{}. If present, the file
193 @file{file.textmetrics} is read to determine text extents.
195 dump text strings to @file{.texstr} file, which can be run through
196 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
197 extents of strings of text. @strong{Warning:} this functionality is
198 currently missing due to heavy restructuring of the source code.
201 @cindex PostScript output
203 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
204 these fonts is done. When using oriental character sets, this can
208 for encapsulated PostScript. This dumps every page (system) as a separate
209 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
210 all pages (systems) including fonts.
212 This mode is used by default by lilypond-book.
215 for SVG (Scalable Vector Graphics). This dumps every page as a separate
216 @file{SVG} file, with embedded fonts.
217 @cindex SVG (Scalable Vector Graphics)
218 You need a SVG viewer which supports embedded fonts, or a SVG
219 viewer which is able to replace the embedded fonts with OTF fonts.
220 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
221 (version 0.42 or later), after copying the OTF fonts in directory
222 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
224 for a dump of the raw, internal Scheme-based drawing commands.
228 Example: @code{lilypond -dbackend=svg filename.ly}
230 @cindex output format, setting
233 Generate an output file containing the titles and the first system
236 Generate the full pages, the default. @code{-dno-print-pages} is
237 useful in combination with @code{-dpreview}.
244 Show a summary of usage.
246 @item -H,--header=FIELD
247 Dump a header field to file BASENAME.FIELD
249 @item --include, -I=@var{directory}
250 Add @var{directory} to the search path for input files.
251 @cindex file searching
254 @item -i,--init=@var{file}
255 Set init file to @var{file} (default: @file{init.ly}).
257 @item -o,--output=@var{FILE}
258 Set the default output file to @var{FILE}. The appropriate
259 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
266 Generate DVI files. In this case, the @TeX{} backend should be
267 specified, i.e., @code{-dbackend=tex}.
270 Generate pictures of each page, in PNG format. This implies
271 @code{--ps}. The resolution in DPI of the image may be set with
277 Generate PDF. This implies @code{--ps}.
281 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
282 Run LilyPond in a chroot jail.
284 The @code{--jail} option provides a more flexible alternative to
285 @code{--safe} when LilyPond formatting is available through a web
286 server or whenever LilyPond executes externally provided
289 The @code{--jail} option works by changing the root of LilyPond to
290 @var{jail} just before starting the actual compilation process. The user
291 and group are then changed to match those provided, and the current
292 directory is changed to @var{dir}. This setup guarantees that it is not
293 possible (at least in theory) to escape from the jail. Note that for
294 @code{--jail} to work LilyPond must be run as root, which is usually
295 accomplished in a safe way using @command{sudo}.
297 Setting up a jail is a slightly delicate matter, as we must be sure that
298 LilyPond is able to find whatever it needs to compile the source
299 @emph{inside the jail}. A typical setup comprises the following items:
302 @item Setting up a separate filesystem
303 A separate filesystem should be created for LilyPond, so that it can be
304 mounted with safe options such as @code{noexec}, @code{nodev}, and
305 @code{nosuid}. In this way, it is impossible to run executables or to
306 write directly to a device from LilyPond. If you do not want to create a
307 separate partition, just create a file of reasonable size and use it to
308 mount a loop device. A separate filesystem also guarantees that LilyPond
309 cannot write more space than it is allowed.
311 @item Setting up a separate user
312 A separate user and group (say, @samp{lily}/@samp{lily}) with low
313 privileges should be used to run LilyPond inside the jail. There should
314 be a single directory writable by this user, which should be passed in
317 @item Preparing the jail
318 LilyPond needs to read a number of files while running. All these files
319 are to be copied into the jail, under the same path they appear in the
320 real root filesystem. The entire content of the LilyPond installation
321 (e.g., @file{/usr/share/lilypond})
324 If problems arise, the simplest way to trace them down is to run
325 LilyPond using @command{strace}, which will allow you to determine which
328 @item Running LilyPond
329 In a jail mounted with @code{noexec} it is impossible to execute any external
330 program. Therefore LilyPond must be run with a backend that does not
331 require any such program. As we already mentioned, it must be also run
332 with superuser privileges (which, of course, it will lose immediately),
333 possibly using @command{sudo}. It is a good idea to limit the number of
334 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
335 -t}), and, if your operating system supports it, the amount of memory
336 that can be allocated.
341 Show version information.
344 Be verbose: show full paths of all files read, and give timing
348 Show the warranty with which GNU LilyPond comes. (It comes with
349 @strong{NO WARRANTY}!)
353 @subsection Environment variables
357 @cindex LILYPOND_DATADIR
359 @code{Lilypond} recognizes the following environment variables:
361 @item LILYPOND_DATADIR
362 This specifies a directory where locale messages and
363 data files will be looked up by default. The directory should contain
364 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
367 This selects the language for the warning messages.
369 @item LILYPOND_GC_YIELD
370 With this variable the memory footprint and performance can be
371 adjusted. It is a percentage tunes memory management behavior. With
372 higher values, the program uses more memory, with smaller values, it
373 uses more CPU time. The default value is @code{70}.
378 @node Updating files with convert-ly
379 @section Updating with @command{convert-ly}
381 @cindex Updating a LilyPond file
384 The LilyPond input syntax is routinely changed to simplify it or improve
385 it in different ways. As a side effect of this, the LilyPond interpreter
386 often is no longer compatible with older input files. To remedy this,
387 the program @command{convert-ly} can be used to deal with most of the
388 syntax changes between LilyPond versions.
390 It uses @code{\version} statements in the input files to detect the
391 old version number. In most cases, to upgrade your input file it is
392 sufficient to run@footnote{MacOS X users may execute this command
393 under the menu entry @samp{Compile > Update syntax}.}
396 convert-ly -e myfile.ly
399 If there are no changes to myfile.ly and file called myfile.ly.NEW
400 is created, then myfile.ly is already updated.
402 @command{convert-ly} always converts up to the last syntax change handled by
403 it. This means that the @code{\version} number left in the file is
404 usually lower than the version of @command{convert-ly} itself.
406 To upgrade LilyPond fragments in texinfo files, use
409 convert-ly --from=... --to=... --no-version *.itely
412 To see the changes in the LilyPond syntax between two versions, use
415 convert-ly --from=... --to=... -s
418 To upgrade many files at once, combine @code{convert-ly} with
419 standard unix commands. This example will upgrade all @code{.ly}
420 files in the current directory
423 for f in *.ly; do convert-ly -e $f; done;
426 In general, the program is invoked as follows:
429 convert-ly [@var{option}]@dots{} @var{file}@dots{}
433 The following options can be given:
437 Do an inline edit of the input file. Overrides @code{--output}.
439 @item -f,--from=@var{from-patchlevel}
440 Set the version to convert from. If this is not set, @command{convert-ly}
441 will guess this, on the basis of @code{\version} strings in the file.
443 @item -n,--no-version
444 Normally, @command{convert-ly} adds a @code{\version} indicator
445 to the output. Specifying this option suppresses this.
447 @item -s, --show-rules
448 Show all known conversions and exit.
450 @item --to=@var{to-patchlevel}
451 Set the goal version of the conversion. It defaults to the latest
461 Not all language changes are handled. Only one output option can be
462 specified. Automatically updating scheme and lilypond scheme
463 interfaces is quite unlikely; be prepared to tweak scheme code
467 @c We might want to make this a completely new section, along with more
468 @c info about how to upgrade old input files. -gp
471 Copy and paste from CVS, last updated
474 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/
475 convert-ly.txt?rev=HEAD&content-type=text/plain
477 NEW: not exactly copied; this list has been modified. Since we're
478 changing the bug system, it doesn't make sense to copy from
479 the bug CVS any more. I'll figure out something else. -gp
483 There are a few things that the convert-ly cannot handle. Here's a list of
485 that the community has complained about.
487 This bug report structure has been chosen because convert-ly has a structure
489 allow to smoothly implement all needed changes. Thus this is just a wishlist,
494 Doesn't always convert figured bass correctly, specifically things like {<
495 >}. Mats' comment on working around this:
496 To be able to run convert-ly
497 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
498 and similarly I replaced '>}' with '&}'. After the conversion, I could
499 then change back from '{ #' to '{ <' and from '& }' to '> }'.
500 Doesn't convert all text markup correctly. In the old markup syntax,
501 it was possible to group a number of markup commands together within
503 -#'((bold italic) "string")
504 This will incorrectly be converted into
505 -\markup{{\bold italic} "string"}
506 instead of the correct
507 -\markup{\bold \italic "string"}
509 Doesn't handle \partcombine
510 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
513 \magnify isn't changed to \fontsize.
514 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
515 remove-tag isn't changed.
516 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
517 first-page-number isn't changed.
518 - first-page-number no => print-first-page-number = ##f
519 Line breaks in header strings aren't converted.
520 - \\\\ as line break in \header strings => \markup \center-align <
521 "First Line" "Second Line" >
522 Crescendo and decrescendo terminators aren't converted.
526 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
529 \markup{ \center-align <{ ... }> } should be converted to:
530 \markup{ \center-align {\line { ... }} }
531 but now, \line is missing.
533 Special LaTeX characters such as $~$ in text are not converted to UTF8.
535 \score{} must now begin with a music expression. Anything else
536 (particularly \header{}) must come after the music.
541 @section Reporting bugs
544 @cindex reporting bugs
546 If you have input that results in a crash or an erroneous output, then
547 that is a bug. There is a list of current bugs on our google bug tracker,
549 @uref{http://code.google.com/p/lilypond/issues/list}
551 If you have discovered a bug which is not listed, please report the
552 bug by following the directions on
554 @uref{http://lilypond.org/web/devel/participating/bugs}
556 Please construct submit @ruser{Minimal examples}, of bug reports. We do not
557 have the resources to investigate reports which are not as small as possible.
561 @section Error messages
563 @cindex error messages
564 Different error messages can appear while compiling a file:
570 Something looks suspect. If you are requesting something out of the
571 ordinary then you will understand the message, and can ignore it.
572 However, warnings usually indicate that something is wrong with the
576 Something is definitely wrong. The current processing step (parsing,
577 interpreting, or formatting) will be finished, but the next step will
583 Something is definitely wrong, and LilyPond cannot continue. This
584 happens rarely. The most usual cause is misinstalled fonts.
586 @cindex trace, Scheme
590 Errors that occur while executing Scheme code are caught by the Scheme
591 interpreter. If running with the verbose option (@code{-V} or
592 @code{--verbose}) then a call trace of the offending
593 function call is printed.
595 @cindex Programming error
596 @item Programming error
597 There was some internal inconsistency. These error messages are
598 intended to help the programmers and debuggers. Usually, they can be
599 ignored. Sometimes, they come in such big quantities that they obscure
600 other output. In this case, file a bug-report.
602 @item Aborted (core dumped)
603 This signals a serious programming error that caused the program to
604 crash. Such errors are considered critical. If you stumble on one,
610 @cindex errors, message format
611 If warnings and errors can
612 be linked to some part of the input file, then error messages have the
616 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
617 @var{offending input line}
620 A line-break is inserted in the offending line to indicate the column
621 where the error was found. For example,
624 test.ly:2:19: error: not a duration: 5:
629 These locations are LilyPond's best guess about where the warning or
630 error occurred, but (by their very nature) warnings and errors occur
631 when something unexpected happens. If you can't see an error in the
632 indicated line of your input file, try checking one or two lines
633 above the indicated position.