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 @rlearning{First steps}
29 if 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}. MacOS@tie{}X users might be more familiar with the terms
43 @q{terminal} or @q{console}. Some additional setup is required
44 for MacOS@tie{}X users; please see @rgeneral{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.
52 * Command line options for lilypond::
53 * Environment variables::
56 @node Invoking lilypond
57 @unnumberedsubsec Invoking @command{lilypond}
59 The @command{lilypond} executable may be called as follows from
63 lilypond [@var{option}]@dots{} @var{file}@dots{}
67 When invoked with a filename that has no extension, the @file{.ly}
68 extension is tried first. To read input from stdin, use a
69 dash (@code{-}) for @var{file}.
71 When @file{filename.ly} is processed it will produce @file{filename.ps}
72 and @file{filename.pdf} as output. Several files can be specified;
73 they will each be processed independently. @footnote{The status of
74 GUILE is not reset after processing a @code{.ly} file, so be careful
75 not to change any system defaults from within Scheme.}
77 If @file{filename.ly} contains more than one @code{\book}
78 block, then the rest of the scores will be output in numbered files,
79 starting with @file{filename-1.pdf}. In addition, the value of
80 @code{output-suffix} will be inserted between the basename and the
81 number. An input file containing
84 #(define output-suffix "violin")
86 #(define output-suffix "cello")
91 will output @var{base}@file{-violin.pdf} and
92 @var{base}@file{-cello-1.pdf}.
95 @node Command line options for lilypond
96 @unnumberedsubsec Command line options for @command{lilypond}
98 @cindex Invoking @command{lilypond}
99 @cindex command line options for @command{lilypond}
100 @cindex options, command line
103 The following options are supported:
107 @item -e,--evaluate=@var{expr}
108 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
109 Multiple @code{-e} options may be given, they will be evaluated
112 The expression will be evaluated in the @code{guile-user} module, so
113 if you want to use definitions in @var{expr}, use
116 lilypond -e '(define-public a 42)'
120 on the command-line, and include
123 #(use-modules (guile-user))
127 at the top of the @code{.ly} file.
129 @item -f,--format=@var{format}
130 which formats should be written. Choices for @code{format} are
131 @code{svg}, @code{ps}, @code{pdf}, and @code{png}.
133 Example: @code{lilypond -fpng @var{filename}.ly}
137 @item -d,--define-default=@var{var}=@var{val}
138 This sets the internal program option @var{var} to the Scheme value
139 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
140 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
142 @cindex point and click, command line
151 -dpoint-and-click='#f'
154 Here are a few interesting options.
156 @cindex help, command line
160 Running @code{lilypond -dhelp} will print all of the @code{-d} options
163 @cindex paper-size, command line
166 This option sets the default paper-size,
168 -dpaper-size=\"letter\"
172 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
173 @c Match " in previous line to help context-sensitive editors
175 @cindex safe, command line
178 Do not trust the @code{.ly} input.
180 When LilyPond formatting is available through a web server, either the
181 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
182 @code{--safe} option will prevent inline Scheme code from wreaking
189 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
194 The @code{-dsafe} option works by evaluating in-line Scheme
195 expressions in a special safe module. This safe module is derived from
196 GUILE @file{safe-r5rs} module, but adds a number of functions of the
197 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
199 In addition, safe mode disallows @code{\include} directives and
200 disables the use of backslashes in @TeX{} strings.
202 In safe mode, it is not possible to import LilyPond variables
205 @code{-dsafe} does @emph{not} detect resource overuse. It is still possible to
206 make the program hang indefinitely, for example by feeding cyclic data
207 structures into the backend. Therefore, if using LilyPond on a
208 publicly accessible webserver, the process should be limited in both
209 CPU and memory usage.
211 The safe mode will prevent many useful LilyPond snippets from being
212 compiled. The @code{--jail} is a more secure alternative, but
213 requires more work to set up.
215 @cindex output format, setting
217 the output format to use for the back-end. Choices for @code{format} are
220 @cindex PostScript output
223 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
224 these fonts is done. When using oriental character sets, this can
229 @cindex Postscript, encapulated
230 @cindex EPS (Encapsulated PostScript)
232 for encapsulated PostScript. This dumps every page (system) as a separate
233 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
234 all pages (systems) including fonts.
236 This mode is used by default by @command{lilypond-book}.
240 @cindex SVG (Scalable Vector Graphics)
242 for SVG (Scalable Vector Graphics).
244 This creates a single SVG file, without embedded fonts, for every
245 page of output. It is recommended to install the Century
246 Schoolbook fonts, included with your LilyPond installation, for
247 optimal rendering. Under UNIX, simply copy these fonts from the
248 LilyPond directory (typically
249 @file{/usr/share/lilypond/VERSION/fonts/otf/}) to
250 @file{~/.fonts/}. The SVG output should be compatible with any
251 SVG editor or user agent.
257 for a dump of the raw, internal Scheme-based drawing commands.
260 do not output a printed score; has the same effect as @code{-dno-print-pages}.
263 Example: @code{lilypond -dbackend=svg @var{filename}.ly}
266 @cindex preview, command line
267 Generate an output file containing the titles and the first system
270 Generate the full pages, the default. @code{-dno-print-pages} is
271 useful in combination with @code{-dpreview}.
278 Show a summary of usage.
280 @item -H,--header=@var{FIELD}
281 Dump a header field to file @file{BASENAME.@var{FIELD}}.
283 @item --include, -I=@var{directory}
284 Add @var{directory} to the search path for input files.
285 @cindex file searching
288 @item -i,--init=@var{file}
289 Set init file to @var{file} (default: @file{init.ly}).
291 @item -o,--output=@var{FILE}
292 Set the default output file to @var{FILE}. The appropriate
293 suffix will be added (e.g. @code{.pdf} for pdf)
295 @cindex PostScript output
300 @cindex Portable Network Graphics (PNG) output
303 Generate pictures of each page, in PNG format. This implies
304 @code{--ps}. The resolution in DPI of the image may be set with
309 @cindex Portable Document Format (PDF) output
312 Generate PDF. This implies @code{--ps}.
316 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
317 Run @command{lilypond} in a chroot jail.
319 The @code{--jail} option provides a more flexible alternative to
320 @code{--safe} when LilyPond formatting is available through a web
321 server or whenever LilyPond executes externally provided
324 The @code{--jail} option works by changing the root of @command{lilypond} to
325 @var{jail} just before starting the actual compilation process. The user
326 and group are then changed to match those provided, and the current
327 directory is changed to @var{dir}. This setup guarantees that it is not
328 possible (at least in theory) to escape from the jail. Note that for
329 @code{--jail} to work @command{lilypond} must be run as root, which is usually
330 accomplished in a safe way using @command{sudo}.
332 Setting up a jail is a slightly delicate matter, as we must be sure that
333 LilyPond is able to find whatever it needs to compile the source
334 @emph{inside the jail}. A typical setup comprises the following items:
337 @item Setting up a separate filesystem
338 A separate filesystem should be created for LilyPond, so that it can be
339 mounted with safe options such as @code{noexec}, @code{nodev}, and
340 @code{nosuid}. In this way, it is impossible to run executables or to
341 write directly to a device from LilyPond. If you do not want to create a
342 separate partition, just create a file of reasonable size and use it to
343 mount a loop device. A separate filesystem also guarantees that LilyPond
344 cannot write more space than it is allowed.
346 @item Setting up a separate user
347 A separate user and group (say, @code{lily}/@code{lily}) with low
348 privileges should be used to run LilyPond inside the jail. There should
349 be a single directory writable by this user, which should be passed in
352 @item Preparing the jail
353 LilyPond needs to read a number of files while running. All these files
354 are to be copied into the jail, under the same path they appear in the
355 real root filesystem. The entire content of the LilyPond installation
356 (e.g., @file{/usr/share/lilypond})
359 If problems arise, the simplest way to trace them down is to run
360 LilyPond using @command{strace}, which will allow you to determine which
363 @item Running LilyPond
364 In a jail mounted with @code{noexec} it is impossible to execute any external
365 program. Therefore LilyPond must be run with a backend that does not
366 require any such program. As we already mentioned, it must be also run
367 with superuser privileges (which, of course, it will lose immediately),
368 possibly using @command{sudo}. It is a good idea to limit the number of
369 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
370 -t}), and, if your operating system supports it, the amount of memory
371 that can be allocated.
376 Show version information.
379 Be verbose: show full paths of all files read, and give timing
383 Show the warranty with which GNU LilyPond comes. (It comes with
384 @strong{NO WARRANTY}!)
387 @node Environment variables
388 @unnumberedsubsec Environment variables
392 @cindex LILYPOND_DATADIR
394 @command{lilypond} recognizes the following environment variables:
396 @item LILYPOND_DATADIR
397 This specifies a directory where locale messages and
398 data files will be looked up by default. The directory should contain
399 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
402 This selects the language for the warning messages.
404 @item LILYPOND_GC_YIELD
405 With this variable the memory footprint and performance can be
406 adjusted. It is a percentage tunes memory management behavior. With
407 higher values, the program uses more memory, with smaller values, it
408 uses more CPU time. The default value is @code{70}.
414 @section Error messages
416 @cindex error messages
417 Different error messages can appear while compiling a file:
423 Something looks suspect. If you are requesting something out of the
424 ordinary then you will understand the message, and can ignore it.
425 However, warnings usually indicate that something is wrong with the
430 Something is definitely wrong. The current processing step (parsing,
431 interpreting, or formatting) will be finished, but the next step will
436 Something is definitely wrong, and LilyPond cannot continue. This
437 happens rarely. The most usual cause is misinstalled fonts.
440 @cindex trace, Scheme
443 Errors that occur while executing Scheme code are caught by the Scheme
444 interpreter. If running with the verbose option (@code{-V} or
445 @code{--verbose}) then a call trace of the offending
446 function call is printed.
448 @item Programming error
449 @cindex Programming error
450 There was some internal inconsistency. These error messages are
451 intended to help the programmers and debuggers. Usually, they can be
452 ignored. Sometimes, they come in such big quantities that they obscure
455 @item Aborted (core dumped)
456 @cindex Aborted (core dumped)
457 This signals a serious programming error that caused the program to
458 crash. Such errors are considered critical. If you stumble on one,
462 @cindex errors, message format
463 If warnings and errors can
464 be linked to some part of the input file, then error messages have the
468 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
469 @var{offending input line}
472 A line-break is inserted in the offending line to indicate the column
473 where the error was found. For example,
476 test.ly:2:19: error: not a duration: 5
481 These locations are LilyPond's best guess about where the warning or
482 error occurred, but (by their very nature) warnings and errors occur
483 when something unexpected happens. If you can't see an error in the
484 indicated line of your input file, try checking one or two lines
485 above the indicated position.
487 More information about errors is given in @ref{Common errors}.