1 @c -*- coding: utf-8; mode: texinfo; -*-
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 @command{lilypond}
16 This chapter details the technicalities of running LilyPond.
20 * Command-line usage::
28 Most users run LilyPond through a GUI; see
30 @c @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
47 @c @ref{Setup for MacOS X}.
49 Describing how to use this part of an operating system is outside the
50 scope of this manual; please consult other documentation on this topic
51 if you are unfamiliar with the command-line.
55 * Command line options for lilypond::
56 * Environment variables::
59 @node Invoking lilypond
60 @subsection Invoking @command{lilypond}
62 The @command{lilypond} executable may be called as follows from the command line.
65 lilypond [@var{option}]@dots{} @var{file}@dots{}
69 When invoked with a filename that has no extension, the @file{.ly}
70 extension is tried first. To read input from stdin, use a
71 dash (@code{-}) for @var{file}.
73 When @file{filename.ly} is processed it will produce @file{filename.ps}
74 and @file{filename.pdf} as output. 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 If @file{filename.ly} contains more than one @code{\score}
80 block, then the rest of the scores will be output in numbered files,
81 starting with @file{filename-1.pdf}. In addition, the value of
82 @code{output-suffix} will be inserted between the basename and the
83 number. An input file containing
86 #(define output-suffix "violin")
88 #(define output-suffix "cello")
93 will output @var{base}@file{-violin.pdf} and
94 @var{base}@file{-cello-1.pdf}.
97 @node Command line options for lilypond
98 @subsection Command line options for @command{lilypond}
100 @cindex Invoking @command{lilypond}
101 @cindex command line options for @command{lilypond}
102 @cindex options, command line
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.
158 @cindex help, command line
162 Running @code{lilypond -dhelp} will print all of the @code{-d} options
165 @cindex paper-size, command line
168 This option sets the default paper-size,
170 -dpaper-size=\"letter\"
174 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
175 @c Match " in previous line to help context-sensitive editors
177 @cindex safe, command line
180 Do not trust the @code{.ly} input.
182 When LilyPond formatting is available through a web server, either the
183 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
184 @code{--safe} option will prevent inline Scheme code from wreaking
191 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
196 The @code{-dsafe} option works by evaluating in-line Scheme
197 expressions in a special safe module. This safe module is derived from
198 GUILE @file{safe-r5rs} module, but adds a number of functions of the
199 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
201 In addition, safe mode disallows @code{\include} directives and
202 disables the use of backslashes in @TeX{} strings.
204 In safe mode, it is not possible to import LilyPond variables
207 @code{-dsafe} does @emph{not} detect resource overuse. It is still possible to
208 make the program hang indefinitely, for example by feeding cyclic data
209 structures into the backend. Therefore, if using LilyPond on a
210 publicly accessible webserver, the process should be limited in both
211 CPU and memory usage.
213 The safe mode will prevent many useful LilyPond snippets from being
214 compiled. The @code{--jail} is a more secure alternative, but
215 requires more work to set up.
217 @cindex output format, setting
219 the output format to use for the back-end. Choices for @code{format} are
222 @cindex PostScript output
225 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
226 these fonts is done. When using oriental character sets, this can
231 @cindex Postscript, encapulated
232 @cindex EPS (Encapsulated PostScript)
234 for encapsulated PostScript. This dumps every page (system) as a separate
235 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
236 all pages (systems) including fonts.
238 This mode is used by default by @command{lilypond-book}.
242 @cindex SVG (Scalable Vector Graphics)
244 for SVG (Scalable Vector Graphics).
246 This creates a single SVG file, without embedded fonts, for every
247 page of output. It is recommended to install the Century
248 Schoolbook fonts, included with your LilyPond installation, for
249 optimal rendering. Under UNIX, simply copy these fonts from the
250 LilyPond directory (typically
251 @file{/usr/share/lilypond/VERSION/fonts/otf/}) to
252 @file{~/.fonts/}. The SVG output should be compatible with any
253 SVG editor or user agent.
259 for a dump of the raw, internal Scheme-based drawing commands.
262 do not output a printed score; has the same effect as @code{-dno-print-pages}.
265 Example: @code{lilypond -dbackend=svg @var{filename}.ly}
268 @cindex preview, command line
269 Generate an output file containing the titles and the first system
272 Generate the full pages, the default. @code{-dno-print-pages} is
273 useful in combination with @code{-dpreview}.
280 Show a summary of usage.
282 @item -H,--header=@var{FIELD}
283 Dump a header field to file @file{BASENAME.@var{FIELD}}.
285 @item --include, -I=@var{directory}
286 Add @var{directory} to the search path for input files.
287 @cindex file searching
290 @item -i,--init=@var{file}
291 Set init file to @var{file} (default: @file{init.ly}).
293 @item -o,--output=@var{FILE}
294 Set the default output file to @var{FILE}. The appropriate
295 suffix will be added (e.g. @code{.pdf} for pdf)
297 @cindex PostScript output
302 @cindex Portable Network Graphics (PNG) output
305 Generate pictures of each page, in PNG format. This implies
306 @code{--ps}. The resolution in DPI of the image may be set with
311 @cindex Portable Document Format (PDF) output
314 Generate PDF. This implies @code{--ps}.
318 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
319 Run @command{lilypond} in a chroot jail.
321 The @code{--jail} option provides a more flexible alternative to
322 @code{--safe} when LilyPond formatting is available through a web
323 server or whenever LilyPond executes externally provided
326 The @code{--jail} option works by changing the root of @command{lilypond} to
327 @var{jail} just before starting the actual compilation process. The user
328 and group are then changed to match those provided, and the current
329 directory is changed to @var{dir}. This setup guarantees that it is not
330 possible (at least in theory) to escape from the jail. Note that for
331 @code{--jail} to work @command{lilypond} must be run as root, which is usually
332 accomplished in a safe way using @command{sudo}.
334 Setting up a jail is a slightly delicate matter, as we must be sure that
335 LilyPond is able to find whatever it needs to compile the source
336 @emph{inside the jail}. A typical setup comprises the following items:
339 @item Setting up a separate filesystem
340 A separate filesystem should be created for LilyPond, so that it can be
341 mounted with safe options such as @code{noexec}, @code{nodev}, and
342 @code{nosuid}. In this way, it is impossible to run executables or to
343 write directly to a device from LilyPond. If you do not want to create a
344 separate partition, just create a file of reasonable size and use it to
345 mount a loop device. A separate filesystem also guarantees that LilyPond
346 cannot write more space than it is allowed.
348 @item Setting up a separate user
349 A separate user and group (say, @code{lily}/@code{lily}) with low
350 privileges should be used to run LilyPond inside the jail. There should
351 be a single directory writable by this user, which should be passed in
354 @item Preparing the jail
355 LilyPond needs to read a number of files while running. All these files
356 are to be copied into the jail, under the same path they appear in the
357 real root filesystem. The entire content of the LilyPond installation
358 (e.g., @file{/usr/share/lilypond})
361 If problems arise, the simplest way to trace them down is to run
362 LilyPond using @command{strace}, which will allow you to determine which
365 @item Running LilyPond
366 In a jail mounted with @code{noexec} it is impossible to execute any external
367 program. Therefore LilyPond must be run with a backend that does not
368 require any such program. As we already mentioned, it must be also run
369 with superuser privileges (which, of course, it will lose immediately),
370 possibly using @command{sudo}. It is a good idea to limit the number of
371 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
372 -t}), and, if your operating system supports it, the amount of memory
373 that can be allocated.
378 Show version information.
381 Be verbose: show full paths of all files read, and give timing
385 Show the warranty with which GNU LilyPond comes. (It comes with
386 @strong{NO WARRANTY}!)
389 @node Environment variables
390 @subsection Environment variables
394 @cindex LILYPOND_DATADIR
396 @command{lilypond} recognizes the following environment variables:
398 @item LILYPOND_DATADIR
399 This specifies a directory where locale messages and
400 data files will be looked up by default. The directory should contain
401 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
404 This selects the language for the warning messages.
406 @item LILYPOND_GC_YIELD
407 With this variable the memory footprint and performance can be
408 adjusted. It is a percentage tunes memory management behavior. With
409 higher values, the program uses more memory, with smaller values, it
410 uses more CPU time. The default value is @code{70}.
416 @section Error messages
418 @cindex error messages
419 Different error messages can appear while compiling a file:
425 Something looks suspect. If you are requesting something out of the
426 ordinary then you will understand the message, and can ignore it.
427 However, warnings usually indicate that something is wrong with the
431 Something is definitely wrong. The current processing step (parsing,
432 interpreting, or formatting) will be finished, but the next step will
438 Something is definitely wrong, and LilyPond cannot continue. This
439 happens rarely. The most usual cause is misinstalled fonts.
442 @cindex trace, Scheme
445 Errors that occur while executing Scheme code are caught by the Scheme
446 interpreter. If running with the verbose option (@code{-V} or
447 @code{--verbose}) then a call trace of the offending
448 function call is printed.
450 @item Programming error
451 @cindex Programming error
452 There was some internal inconsistency. These error messages are
453 intended to help the programmers and debuggers. Usually, they can be
454 ignored. Sometimes, they come in such big quantities that they obscure
457 @item Aborted (core dumped)
458 This signals a serious programming error that caused the program to
459 crash. Such errors are considered critical. If you stumble on one,
463 @cindex errors, message format
464 If warnings and errors can
465 be linked to some part of the input file, then error messages have the
469 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
470 @var{offending input line}
473 A line-break is inserted in the offending line to indicate the column
474 where the error was found. For example,
477 test.ly:2:19: error: not a duration: 5
482 These locations are LilyPond's best guess about where the warning or
483 error occurred, but (by their very nature) warnings and errors occur
484 when something unexpected happens. If you can't see an error in the
485 indicated line of your input file, try checking one or two lines
486 above the indicated position.