1 @c -*- coding: latin-1; mode: texinfo; -*-
3 @chapter Running LilyPond
5 This chapter details the technicalities of running LilyPond.
13 * Invoking lilypond-latex::
16 @node Invoking lilypond
17 @section Invoking lilypond
18 @cindex Invoking LilyPond
19 @cindex command line options
20 @cindex options, command line
24 The @code{lilypond} executable may be called as follows from the command line.
27 lilypond [@var{option}]@dots{} @var{file}@dots{}
31 When invoked with a filename that has no extension, the @file{.ly}
32 extension is tried first. To read input from stdin, use a
33 dash (@code{-}) for @var{file}.
35 When @file{filename.ly} is processed it will produce
36 @file{filename.tex} as output (or @file{filename.ps} for PostScript
37 output). If @file{filename.ly} contains more than one @code{\score}
38 block, then the rest of the scores will be output in numbered files,
39 starting with @file{filename-1.tex}. Several files can be specified;
40 they will each be processed independently. @footnote{The status of
41 GUILE is not reset after processing a @code{.ly} file, so be careful
42 not to change any system defaults from within Scheme.}
45 @section Command line options
47 The following options are supported:
51 @item -e,--evaluate=@var{expr}
52 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
53 Multiple @code{-e} options may be given, they will be evaluated
54 sequentially. The function @code{ly:set-option} allows access to
55 some internal variables. Use @code{-e '(ly:option-usage)'} for more
58 @item -f,--format=@var{format}
59 A comma separated list of back-end output formats to use. Choices are
60 @code{tex} (for @TeX{} output, to be processed with La@TeX{}), and
61 @code{ps} for PostScript.
63 There are other output options, but they are intended for developers.
64 @cindex output format, setting
65 @cindex PostScript output
69 Show a summary of usage.
71 @item --include, -I=@var{directory}
72 Add @var{directory} to the search path for input files.
73 @cindex file searching
76 @item -i,--init=@var{file}
77 Set init file to @var{file} (default: @file{init.ly}).
79 @item -o,--output=@var{FILE}
80 Set the default output file to @var{FILE}.
86 Generate DVI files. In this case, the @TeX{} backend should be
87 specified, i.e., @code{-f tex}.
90 Generate pictures of each page, in PNG format. This implies @code{--ps}.
93 Generate PDF. This implies @code{--ps}.
96 Generate an output file containing the titles and the first system
99 Do not generate the full pages. Useful in combination with
103 Do not trust the @code{.ly} input.
105 When LilyPond formatting is available through a web server, the
106 @code{--safe} @b{MUST} be passed. This will prevent inline Scheme
107 code from wreaking havoc, for example
113 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
118 The @code{--safe} option works by evaluating in-line Scheme
119 expressions in a special safe module. This safe module is derived from
120 GUILE @file{safe-r5rs} module, but adds a number of functions of the
121 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
123 In addition, @code{--safe} disallows @code{\include} directives and
124 disables the use of backslashes in @TeX{} strings.
126 In @code{--safe} mode, it is not possible to import LilyPond variables
129 @code{--safe} does @emph{not} detect resource overuse. It is still
130 possible to make the program hang indefinitely, for example by feeding
131 cyclic data structures into the backend. Therefore, if using LilyPond
132 on a publicly accessible webserver, the process should be limited in
133 both CPU and memory usage.
136 Show version information.
139 Be verbose: show full paths of all files read, and give timing
143 Show the warranty with which GNU LilyPond comes. (It comes with
144 @strong{NO WARRANTY}!)
148 @section Environment variables
150 For processing both the @TeX{} and the PostScript output, the
151 appropriate environment variables must be set. The following scripts
155 @item @file{buildscripts/@/out/@/lilypond@/-profile}
157 @item @file{buildscripts/@/out/@/lilypond@/-login} (for C-shells)
160 They should normally be sourced as part of the login process. If these
161 scripts are not run from the system wide login process, then you must
164 @cindex installing LilyPond
166 If you use sh, bash, or a similar shell, then add the following to
167 your @file{.profile}:
169 . @var{/the/path/to/}lilypond-profile
172 If you use csh, tcsh or a similar shell, then add the following to
173 your @file{~/.login}:
175 source @var{/the/path/to/}lilypond-login
178 Of course, in both cases, you should substitute the proper location of
181 These scripts set the following variables:
184 To make sure that @TeX{} and lilypond find data files (among
185 others @file{.tex}, @file{.mf}, and @file{.tfm}),
186 you have to set @code{TEXMF} to point to the lilypond data
187 file tree. A typical setting would be
189 @{/usr/share/lilypond/2.4.0,@{!!/usr/share/texmf@}@}
197 @cindex printing postscript
199 The binary itself recognizes the following environment variables:
202 This specifies a directory where locale messages and
203 data files will be looked up by default. The directory should contain
204 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
207 This selects the language for the warning messages.
211 @cindex LILYPONDPREFIX
214 @section Error messages
216 @cindex error messages
217 Different error messages can appear while compiling a file:
223 Something looks suspect. If you are requesting something out of the
224 ordinary then you will understand the message, and can ignore it.
225 However, warnings usually indicate that something is wrong with the
229 Something is definitely wrong. The current processing step (parsing,
230 interpreting, or formatting) will be finished, but the next step will
236 Something is definitely wrong, and LilyPond cannot continue. This
237 happens rarely. The most usual cause is misinstalled fonts.
239 @cindex trace, Scheme
243 Errors that occur while executing Scheme code are caught by the Scheme
244 interpreter. If running with the verbose option (@code{-V} or
245 @code{--verbose}) then a call trace of the offending
246 function call is printed.
248 @cindex Programming error
249 @item Programming error
250 There was some internal inconsistency. These error messages are
251 intended to help the programmers and debuggers. Usually, they can be
252 ignored. Sometimes, they come in such big quantities that they obscure
253 other output. In this case, file a bug-report.
255 @item Aborted (core dumped)
256 This signals a serious programming error that caused the program to
257 crash. Such errors are considered critical. If you stumble on one,
263 @cindex errors, message format
264 If warnings and errors can
265 be linked to some part of the input file, then error messages have the
269 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
270 @var{offending input line}
273 A line-break is inserted in the offending line to indicate the column
274 where the error was found. For example,
277 test.ly:2:19: error: not a duration: 5:
282 These locations are LilyPond's best guess about where the warning or
283 error occured, but (by their very nature) warnings and errors occur
284 when something unexpected happens. If you can't see an error in the
285 indicated line of your input file, try checking one or two lines
286 above the indicated position.
290 @section Reporting bugs
293 @cindex reporting bugs
295 If you have input that results in a crash or an erroneous output, then
296 that is a bug. We try to respond to bug-reports promptly, and fix them as
297 soon as possible. Help us by sending a defective input file, so we can
298 reproduce the problem. Make it small, so we can easily debug the
299 problem. Don't forget to tell which version of LilyPond you use! Send
300 the report to @email{bug-lilypond@@gnu.org}.
302 When you've found a bug, have a look at our
303 @uref{http://@/lilypond@/.org/@/doc/@/v2.3/@/bugs/,bug database} to see if
304 it has already been reported. You could also try to do a few searches
305 on the mailing list for the bug. Sometimes the bug will have already
306 been reported and a fix or workaround is already known.
308 Here is an example of a good bug report:
311 It seems that placement of accidentals is broken. In the
312 following example, the accidental touches the note head.
314 Using Mac OSX 10.3.5, fink package lilypond-unstable
325 \override Accidental #'extra-offset = #'(1.0 . 0)
331 @section Editor support
336 @cindex modes, editor
337 @cindex syntax coloring
338 @cindex coloring, syntax
340 There is support from different editors for LilyPond.
344 Emacs has a @file{lilypond-mode}, which provides keyword
345 autocompletion, indentation, LilyPond specific parenthesis matching
346 and syntax coloring, handy compile short-cuts and reading LilyPond
347 manuals using Info. If @file{lilypond-mode} is not installed on your
348 platform, then read the
350 @uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
353 installation instructions.
358 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
359 with syntax coloring tools. For more information, refer to the
361 @uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
364 installation instructions.
370 The @uref{http://@/www@/.jedit@/.org/,jEdit} editor has a LilyPond plugin.
371 This plugin includes a DVI viewer, integrated help and viewing via
372 GhostScript. It can be installed by doing @key{Plugins > Plugin
373 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
377 All these editors can be made to jump into the input file to the source
378 of a symbol in the graphical output. See @ref{Point and click}.
383 @node Invoking lilypond-latex
384 @section Invoking lilypond-latex
386 Before LilyPond 2.4, the @code{lilypond} program only generated music
387 notation. Titles and page layout was done in a separate wrapper
388 program. For compatibility with older files, this wrapper program has
389 been retained as @code{lilypond-latex}. It uses the LilyPond program
390 and La@TeX{} to create a nicely titled piece of sheet music. Use of
391 this program is only necessary if the input file contains special
392 La@TeX{} options or formatting codes in markup texts.
394 The @code{lilypond-latex} wrapper is invoked from the command-line as
397 @code{lilypond-latex} [@var{option}]@dots{} @var{file}@dots{}
400 To have @code{lilypond-latex} read from stdin, use a dash (@code{-}) for
401 @var{file}. The program supports the following options.
403 @cindex stdin, reading
407 Keep the temporary directory with all output files. The temporary
408 directory is created in the current directory as @code{@code{lilypond}.dir}.
413 @item -I,--include=@var{dir}
414 Add @var{dir} to LilyPond's include path.
416 @item -o,--output=@var{file}
417 Generate output to @var{file}. The extension of @var{file} is ignored.
420 Also generate pictures of each page, in PNG format.
423 Also generate a picture of the first system of the score.
432 @item -s,--set=@var{key}=@var{val}
433 Add @var{key}= @var{val} to the settings, overriding those specified
434 in the files. Possible keys: @code{language}, @code{latexheaders},
435 @code{latexpackages}, @code{latexoptions}, @code{papersize},
436 @code{linewidth}, @code{orientation},
440 Show version information.
443 Be verbose. This prints out commands as they are executed, and more
444 information about the formatting process is printed.
447 Print even more information. This is useful when generating bug reports.
450 Show the warranty with which GNU LilyPond comes. (It comes with
451 @strong{NO WARRANTY}!)
455 @subsection Additional parameters
457 The @code{lilypond} program responds to several parameters specified
458 in a @code{\layout} section of the input file. They can be overridden
459 by supplying a @code{--set} command line option.
463 Specify La@TeX{} language: the @code{babel} package will be
464 included. Default: unset.
466 Read from the @code{\header} block.
469 Specify additional La@TeX{} header files.
470 Normally read from the @code{\header} block. Default value: empty.
473 Specify additional La@TeX{} package files. This works cumulative,
474 so you can add multiple packages using multiple @code{-s=latexpackages} options.
475 Normally read from the @code{\header} block. Default value:
479 Specify additional options for the La@TeX{}
480 @code{\documentclass}. You can put any valid value here. This was
481 designed to allow @code{lilypond} to produce output for double-sided
482 paper, with balanced margins and page numbers on alternating sides. To
483 achieve this specify @code{twoside}.
486 Set orientation. Choices are @code{portrait} or @code{landscape}. Is
487 read from the @code{\layout} block, if set.
490 The vertical extension of the music on the page. It is normally
491 calculated automatically, based on the paper size.
494 The music line width. It is normally read from the @code{\layout}
498 The paper size (as a name, e.g., @code{a4}). It is normally read from
499 the @code{\layout} block.
502 The font encoding, should be set identical to the @code{font-encoding}
503 property in the score.