2 @node Invoking LilyPond
3 @chapter Invoking LilyPond
5 This chapter details the technicalities of running LilyPond.
9 * Invoking lilypond:: Titling LilyPond scores.
10 * Invoking the lilypond binary::
16 @node Invoking the lilypond binary
17 @section Invoking the lilypond binary
18 @cindex Invoking LilyPond
19 @cindex command line options
20 @cindex options, command line
24 The formatting system consists of two parts: a binary executable
25 (@file{lilypond}), which is responsible for the formatting
26 functionality, and support scripts, which post-process the resulting
27 output. Normally, the support scripts are called, which in turn invoke
28 the @code{lilypond-bin} binary. However, @code{lilypond-bin} may be
29 called directly as follows.
32 lilypond-bin [@var{option}]@dots{} @var{file}@dots{}
36 When invoked with a filename that has no extension, the @file{.ly}
37 extension is tried first. To read input from stdin, use a
38 dash @code{-} for @var{file}.
40 When @file{filename.ly} is processed it will produce
41 @file{filename.tex} as output (or @file{filename.ps} for PostScript
42 output). If @file{filename.ly} contains more than one @code{\score}
43 block, then the rest of the scores will be output in numbered files,
44 starting with @file{filename-1.tex}. Several files can be specified;
45 they will each be processed independently. @footnote{The status of
46 GUILE is not reset across invocations, so be careful not to change any
47 system defaults from within Scheme.}
50 @section Command line options
52 The following options are supported:
56 @item -e,--evaluate=@var{expr}
57 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
58 Multiple @code{-e} options may be given, they will be evaluated
59 sequentially. The function @code{ly:set-option} allows for access to
60 some internal variables. Use @code{-e '(ly:option-usage)'} for more
63 @item -f,--format=@var{format}
66 A comma separated list of back-end output formats to use. Choices are
67 @code{tex} (for @TeX{} output, to be processed with La@TeX{}, and
68 @code{ps} for PostScript.
70 Other output options are intended for developers.
73 @cindex output format, setting
74 @cindex PostScript output
78 Show a summary of usage.
79 @item --include, -I=@var{directory}
80 Add @var{directory} to the search path for input files.
81 @cindex file searching
83 @item -i,--init=@var{file}
84 Set init file to @var{file} (default: @file{init.ly}).
85 @item -o,--output=@var{FILE}
86 Set the default output file to @var{FILE}.
90 Generate DVI files. In this case, the @TeX{} backend should be
91 specified, i.e. @code{-f tex}.
93 Generate pictures of each page, in PNG format. This implies @code{--ps}.
95 Generate PDF. This implies @code{--ps}.
97 Also generate a picture of the first system of the score.
100 Do not trust the @code{.ly} input.
102 When LilyPond formatting available through a web server, the
103 @code{--safe} @b{MUST} be passed. This will prevent code like
108 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
112 The @code{--safe} option works by evaluating in-line Scheme
113 expressions in a special safe module. This safe module is derived from
114 GUILE @file{safe-r5rs} module, but adds a number of functions of the
115 LilyPond API. These functions are listed in @file{safe-lily.scm}.
117 In addition, @code{--safe} disallows @code{\include} directives and
118 disables the use of backslashes in @TeX{} strings.
120 In @code{--safe} mode, it is not possible to import LilyPond variables
124 Show version information.
126 Be verbose: show full paths of all files read, and give timing
130 Show the warranty with which GNU LilyPond comes. (It comes with
131 @strong{NO WARRANTY}!)
134 @section Environment variables
137 For processing both the @TeX{} and the PostScript output, the
138 appropriate environment variables must be set. The following scripts
142 @item @file{buildscripts/out/lilypond-profile}
144 @item @file{buildscripts/out/lilypond-login} (for C-shells)
147 They should normally be sourced as part of the login process. If these
148 scripts are not run from the system wide login process, then you must
151 @cindex installing LilyPond
153 If you use sh, bash, or a similar shell, then add the following to
154 your @file{.profile}:
156 . @var{/the/path/to/}lilypond-profile
159 If you use csh, tcsh or a similar shell, then add the following to
160 your @file{~/.login}:
162 source @var{/the/path/to/}lilypond-login
165 Of course, in both cases, you should substitute the proper location of
168 These scripts set the following variables:
171 To make sure that @TeX{} and lilypond find data files (among
172 others @file{.tex}, @file{.mf} and @file{.tfm}),
173 you have to set @code{TEXMF} to point to the lilypond data
174 file tree. A typical setting would be
176 @{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
181 For processing PostScript output (obtained with
182 @code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
183 point to the directory containing library PS files.
186 For processing PostScript output (obtained with
187 @code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
188 point to the directory containing PFA files.
190 When you print direct PS output, remember to send the PFA files to the
200 @cindex printing postscript
202 The binary itself recognizes the following environment variables:
205 This specifies a directory where locale messages and
206 data files will be looked up by default. The directory should contain
207 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
210 This selects the language for the warning messages.
214 @cindex LILYPONDPREFIX
217 @section Error messages
219 @cindex error messages
220 Different error messages can appear while compiling a file:
226 Something looks suspect. If you are requesting something out of the
227 ordinary then you will understand the message, and can ignore it.
228 However, warnings usually indicate that something is wrong with the
232 Something is definitely wrong. The current processing step (parsing,
233 interpreting, or formatting) will be finished, but the next step will
239 Something is definitely wrong, and LilyPond cannot continue. This
240 happens rarely. The most usual cause is misinstalled fonts.
242 @cindex trace, Scheme
246 Errors that occur while executing Scheme code are caught by the Scheme
247 interpreter. If running with the verbose option (@code{-V} or
248 @code{--verbose}) then a call trace is printed of the offending
251 @cindex Programming error
252 @item Programming error
253 There was some internal inconsistency. These error messages are
254 intended to help the programmers and debuggers. Usually, they can be
255 ignored. Sometimes, they come in such big quantities that they obscure
256 other output. In this case, file a bug-report.
258 @item Aborted (core dumped)
259 This signals a serious programming error that caused the program to
260 crash. Such errors are considered critical. If you stumble on one,
266 @cindex errors, message format
267 If warnings and errors can
268 be linked to some part of the input file, then error messages have the
272 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
273 @var{offending input line}
276 A line-break is inserted in offending line to indicate the column
277 where the error was found. For example,
280 test.ly:2:19: error: not a duration: 5:
287 @section Reporting bugs
290 @cindex reporting bugs
292 If you have input that results in a crash or an erroneous output, then
293 that is a bug. We try respond to bug-reports promptly, and fix them as
294 soon as possible. For this, we need to reproduce and isolate the
295 problem. Help us by sending a defective input file, so we can
296 reproduce the problem. Make it small, so we can easily debug the
297 problem. Don't forget to tell which version you use, and on which
298 platform you run it. Send the report to
299 @email{bug-lilypond@@gnu.org}.
302 @section Editor support
307 @cindex modes, editor
308 @cindex syntax coloring
309 @cindex coloring, syntax
311 There is support from different editors for LilyPond.
315 Emacs has a @file{lilypond-mode}, which provides keyword
316 autocompletion, indentation, LilyPond specific parenthesis matching
317 and syntax coloring, handy compile short-cuts and reading LilyPond
318 manuals using Info. If lilypond-mode is not installed on your
319 platform, then refer to the installation instructions for more
324 For @uref{http://www.vim.org,VIM}, a vimrc is supplied, along with
325 syntax coloring tools. For more information, refer to the
327 @uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
330 installation instructions.
334 For both editors, there is also a facility to jump in the input file
335 to the source of errors in the graphical output. See @ref{Point and
340 There exists a plugin for @uref{http://www.jedit.org/,jEdit}. Refer to
341 the @uref{http://lily4jedit.sourceforge.net,plugin website} for more
346 @node Point and click
347 @section Point and click
348 @cindex point and click
350 @cindex source specials
351 @cindex specials, source
353 Point and click lets you find notes in the input by clicking on them in
354 the Xdvi window. This makes it easier to find input that causes some
355 error in the sheet music.
357 To use it, you need the following software:
359 @item a dvi viewer that supports src specials:
361 @item Xdvi, version 22.36 or newer. Available from
362 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}.
364 Most @TeX{} distributions ship with xdvik, which is always a few
365 versions behind the official Xdvi. To find out which Xdvi you are
366 running, try @code{xdvi -version} or @code{xdvi.bin -version}.
367 @item KDVI. A dvi viewer for KDE. You need KDVI from KDE 3.0 or
368 newer. Enable option @emph{Inverse search} in the menu @emph{Settings}.
370 Apparently, KDVI does not process PostScript specials correctly. Beams
371 and slurs will not be visible in KDVI.
380 @item an editor with a client/server interface (or a lightweight GUI
386 @item Emacs. Emacs is an extensible text-editor. It is available from
387 @uref{http://www.gnu.org/software/emacs/}. You need version 21 to use
390 @c move this elsewhere?
395 @cindex lilypond-mode for Emacs
396 @cindex syntax coloring
398 @item XEmacs. XEmacs is very similar to Emacs.
402 @item NEdit. NEdit runs under Windows, and Unix.
403 It is available from @uref{http://www.nedit.org}.
407 @item GVim. GVim is a GUI variant of VIM, the popular VI
408 clone. It is available from @uref{http://www.vim.org}.
417 Xdvi must be configured to find the @TeX{} fonts and music
418 fonts. Refer to the Xdvi documentation for more information.
420 To use point-and-click, add one of these lines to the top of your .ly
423 #(ly:set-point-and-click 'line)
425 @cindex line-location
427 When viewing, Control-Mousebutton 1 will take you to the originating
428 spot in the @file{.ly} file. Control-Mousebutton 2 will show all
431 If you correct large files with point-and-click, be sure to start
432 correcting at the end of the file. When you start at the top, and
433 insert one line, all following locations will be off by a line.
436 For using point-and-click with Emacs, add the following
437 In your Emacs startup file (usually @file{~/.emacs}):
442 Make sure that the environment variable @var{XEDITOR} is set to
444 emacsclient --no-wait +%l %f
446 @cindex @var{XEDITOR}
447 If you use XEmacs instead of Emacs, you use @code{(gnuserve-start)} in
448 your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}.
450 For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or
451 use this argument with Xdvi's @code{-editor} option.
454 For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or
455 use this argument with Xdvi's @code{-editor} option.
457 If can also make your editor jump to the exact location of the note
458 you clicked. This is only supported on Emacs and VIM. Users of Emacs version
459 20 must apply the patch @file{emacsclient.patch}. Users of version 21
460 must apply @file{server.el.patch} (version 21.2 and earlier). At the
461 top of the @code{ly} file, replace the @code{set-point-and-click} line
462 with the following line:
464 #(ly:set-point-and-click 'line-column)
466 @cindex line-column-location
467 and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. Vim
468 users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.
472 @node Invoking lilypond-latex
473 @section Invoking lilypond-latex
475 Before LilyPond 3.0, the task of generating nicely titled output was
476 relegated to a separate program. This wrapper script
477 @code{lilypond-latex} uses the LilyPond program and La@TeX{} to create
478 a nicely titled piece of sheet music.
481 @code{lilypond} [@var{option}]@dots{} @var{file}@dots{}
484 To have @code{lilypond} read from stdin, use a dash @code{-} for
485 @var{file}. The program supports the following options.
487 @cindex stdin, reading
491 Keep the temporary directory with all output
492 files. The temporary directory is created in the current directory as @code{@code{lilypond}.dir}.
495 @item -I,--include=@var{dir}
496 Add @var{dir} to LilyPond's include path.
497 @item -o,--output=@var{file}
498 Generate output to @var{file}. The extension of @var{file} is ignored.
500 Also generate pictures of each page, in PNG format.
502 Also generate a picture of the first system of the score.
511 @item -s,--set=@var{key}=@var{val}
512 Add @var{key}= @var{val} to the settings, overriding those specified
513 in the files. Possible keys: @code{language}, @code{latexheaders},
514 @code{latexpackages}, @code{latexoptions}, @code{papersize},
515 @code{linewidth}, @code{orientation},
518 Show version information.
520 Be verbose. This prints out commands as they are executed, and more
521 information about the formatting process is printed.
523 Print even more information. This is useful when generating bug reports.
525 Show the warranty with which GNU LilyPond comes. (It comes with
526 @strong{NO WARRANTY}!)
531 @subsection Additional parameters
533 The @code{lilypond} program responds to several parameters specified
534 in a @code{\paper} section of the input file. They can be overridden
535 by supplying a @code{--set} command line option.
539 Specify La@TeX{} language: the @code{babel} package will be
540 included. Default: unset.
542 Read from the @code{\header} block.
545 Specify additional La@TeX{} headers file.
546 Normally read from the @code{\header} block. Default value: empty.
549 Specify additional La@TeX{} packages file. This works cumulative,
550 so you can add multiple packages using multiple @code{-s=latexpackages} options.
551 Normally read from the @code{\header} block. Default value:
555 Specify additional options for the La@TeX{}
556 @code{\documentclass}. You can put any valid value here. This was
557 designed to allow @code{lilypond} to produce output for double-sided
558 paper, with balanced margins and page numbers on alternating sides. To
559 achieve this specify @code{twoside}.
562 Set orientation. Choices are @code{portrait} or @code{landscape}. Is
563 read from the @code{\paper} block, if set.
566 The vertical extension of the music on the page. It is normally
567 calculated automatically, based on the paper size.
570 The music line width. It is normally read from the @code{\paper}
574 The paper size (as a name, e.g. @code{a4}). It is normally read from
575 the @code{\paper} block.
578 The font encoding, should be set identical to the @code{font-encoding}
579 property in the score.