2 @node Invoking LilyPond
3 @chapter Invoking LilyPond
5 This chapter details the technicalities of running LilyPond.
14 * Invoking lilypond-latex::
17 @node Invoking lilypond
18 @section Invoking lilypond
19 @cindex Invoking LilyPond
20 @cindex command line options
21 @cindex options, command line
25 The @code{lilypond} may be called as follows from the command line.
28 lilypond [@var{option}]@dots{} @var{file}@dots{}
32 When invoked with a filename that has no extension, the @file{.ly}
33 extension is tried first. To read input from stdin, use a
34 dash @code{-} for @var{file}.
36 When @file{filename.ly} is processed it will produce
37 @file{filename.tex} as output (or @file{filename.ps} for PostScript
38 output). If @file{filename.ly} contains more than one @code{\score}
39 block, then the rest of the scores will be output in numbered files,
40 starting with @file{filename-1.tex}. Several files can be specified;
41 they will each be processed independently. @footnote{The status of
42 GUILE is not reset across invocations, so be careful not to change any
43 system defaults from within Scheme.}
46 @section Command line options
48 The following options are supported:
52 @item -e,--evaluate=@var{expr}
53 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
54 Multiple @code{-e} options may be given, they will be evaluated
55 sequentially. The function @code{ly:set-option} allows for access to
56 some internal variables. Use @code{-e '(ly:option-usage)'} for more
59 @item -f,--format=@var{format}
62 A comma separated list of back-end output formats to use. Choices are
63 @code{tex} (for @TeX{} output, to be processed with La@TeX{}, and
64 @code{ps} for PostScript.
66 Other output options are intended for developers.
69 @cindex output format, setting
70 @cindex PostScript output
74 Show a summary of usage.
75 @item --include, -I=@var{directory}
76 Add @var{directory} to the search path for input files.
77 @cindex file searching
79 @item -i,--init=@var{file}
80 Set init file to @var{file} (default: @file{init.ly}).
81 @item -o,--output=@var{FILE}
82 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}.
89 Generate pictures of each page, in PNG format. This implies @code{--ps}.
91 Generate PDF. This implies @code{--ps}.
93 Also generate a picture of the first system of the score.
96 Do not trust the @code{.ly} input.
98 When LilyPond formatting available through a web server, the
99 @code{--safe} @b{MUST} be passed. This will prevent code like
104 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
108 The @code{--safe} option works by evaluating in-line Scheme
109 expressions in a special safe module. This safe module is derived from
110 GUILE @file{safe-r5rs} module, but adds a number of functions of the
111 LilyPond API. These functions are listed in @file{safe-lily.scm}.
113 In addition, @code{--safe} disallows @code{\include} directives and
114 disables the use of backslashes in @TeX{} strings.
116 In @code{--safe} mode, it is not possible to import LilyPond variables
120 Show version information.
122 Be verbose: show full paths of all files read, and give timing
126 Show the warranty with which GNU LilyPond comes. (It comes with
127 @strong{NO WARRANTY}!)
130 @section Environment variables
133 For processing both the @TeX{} and the PostScript output, the
134 appropriate environment variables must be set. The following scripts
138 @item @file{buildscripts/out/lilypond-profile}
140 @item @file{buildscripts/out/lilypond-login} (for C-shells)
143 They should normally be sourced as part of the login process. If these
144 scripts are not run from the system wide login process, then you must
147 @cindex installing LilyPond
149 If you use sh, bash, or a similar shell, then add the following to
150 your @file{.profile}:
152 . @var{/the/path/to/}lilypond-profile
155 If you use csh, tcsh or a similar shell, then add the following to
156 your @file{~/.login}:
158 source @var{/the/path/to/}lilypond-login
161 Of course, in both cases, you should substitute the proper location of
164 These scripts set the following variables:
167 To make sure that @TeX{} and lilypond find data files (among
168 others @file{.tex}, @file{.mf} and @file{.tfm}),
169 you have to set @code{TEXMF} to point to the lilypond data
170 file tree. A typical setting would be
172 @{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
177 For processing PostScript output (obtained with
178 @code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
179 point to the directory containing library PS files.
182 For processing PostScript output (obtained with
183 @code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
184 point to the directory containing PFA files.
186 When you print direct PS output, remember to send the PFA files to the
196 @cindex printing postscript
198 The binary itself recognizes the following environment variables:
201 This specifies a directory where locale messages and
202 data files will be looked up by default. The directory should contain
203 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
206 This selects the language for the warning messages.
210 @cindex LILYPONDPREFIX
213 @section Error messages
215 @cindex error messages
216 Different error messages can appear while compiling a file:
222 Something looks suspect. If you are requesting something out of the
223 ordinary then you will understand the message, and can ignore it.
224 However, warnings usually indicate that something is wrong with the
228 Something is definitely wrong. The current processing step (parsing,
229 interpreting, or formatting) will be finished, but the next step will
235 Something is definitely wrong, and LilyPond cannot continue. This
236 happens rarely. The most usual cause is misinstalled fonts.
238 @cindex trace, Scheme
242 Errors that occur while executing Scheme code are caught by the Scheme
243 interpreter. If running with the verbose option (@code{-V} or
244 @code{--verbose}) then a call trace is printed of the offending
247 @cindex Programming error
248 @item Programming error
249 There was some internal inconsistency. These error messages are
250 intended to help the programmers and debuggers. Usually, they can be
251 ignored. Sometimes, they come in such big quantities that they obscure
252 other output. In this case, file a bug-report.
254 @item Aborted (core dumped)
255 This signals a serious programming error that caused the program to
256 crash. Such errors are considered critical. If you stumble on one,
262 @cindex errors, message format
263 If warnings and errors can
264 be linked to some part of the input file, then error messages have the
268 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
269 @var{offending input line}
272 A line-break is inserted in offending line to indicate the column
273 where the error was found. For example,
276 test.ly:2:19: error: not a duration: 5:
283 @section Reporting bugs
286 @cindex reporting bugs
288 If you have input that results in a crash or an erroneous output, then
289 that is a bug. We try respond to bug-reports promptly, and fix them as
290 soon as possible. For this, we need to reproduce and isolate the
291 problem. Help us by sending a defective input file, so we can
292 reproduce the problem. Make it small, so we can easily debug the
293 problem. Don't forget to tell which version you use, and on which
294 platform you run it. Send the report to
295 @email{bug-lilypond@@gnu.org}.
298 @section Editor support
303 @cindex modes, editor
304 @cindex syntax coloring
305 @cindex coloring, syntax
307 There is support from different editors for LilyPond.
311 Emacs has a @file{lilypond-mode}, which provides keyword
312 autocompletion, indentation, LilyPond specific parenthesis matching
313 and syntax coloring, handy compile short-cuts and reading LilyPond
314 manuals using Info. If lilypond-mode is not installed on your
315 platform, then refer to the installation instructions for more
320 For @uref{http://www.vim.org,VIM}, a vimrc is supplied, along with
321 syntax coloring tools. For more information, refer to the
323 @uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
326 installation instructions.
330 For both editors, there is also a facility to jump in the input file
331 to the source of errors in the graphical output. See @ref{Point and
336 There exists a plugin for @uref{http://www.jedit.org/,jEdit}. Refer to
337 the @uref{http://lily4jedit.sourceforge.net,plugin website} for more
342 @node Point and click
343 @section Point and click
344 @cindex point and click
346 @cindex source specials
347 @cindex specials, source
349 Point and click lets you find notes in the input by clicking on them in
350 the Xdvi window. This makes it easier to find input that causes some
351 error in the sheet music.
353 To use it, you need the following software:
355 @item a dvi viewer that supports src specials:
357 @item Xdvi, version 22.36 or newer. Available from
358 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}.
360 Most @TeX{} distributions ship with xdvik, which is always a few
361 versions behind the official Xdvi. To find out which Xdvi you are
362 running, try @code{xdvi -version} or @code{xdvi.bin -version}.
363 @item KDVI. A dvi viewer for KDE. You need KDVI from KDE 3.0 or
364 newer. Enable option @emph{Inverse search} in the menu @emph{Settings}.
366 Apparently, KDVI does not process PostScript specials correctly. Beams
367 and slurs will not be visible in KDVI.
376 @item an editor with a client/server interface (or a lightweight GUI
382 @item Emacs. Emacs is an extensible text-editor. It is available from
383 @uref{http://www.gnu.org/software/emacs/}. You need version 21 to use
386 @c move this elsewhere?
391 @cindex lilypond-mode for Emacs
392 @cindex syntax coloring
394 @item XEmacs. XEmacs is very similar to Emacs.
398 @item NEdit. NEdit runs under Windows, and Unix.
399 It is available from @uref{http://www.nedit.org}.
403 @item GVim. GVim is a GUI variant of VIM, the popular VI
404 clone. It is available from @uref{http://www.vim.org}.
413 Xdvi must be configured to find the @TeX{} fonts and music
414 fonts. Refer to the Xdvi documentation for more information.
416 To use point-and-click, add one of these lines to the top of your .ly
419 #(ly:set-point-and-click 'line)
421 @cindex line-location
423 When viewing, Control-Mousebutton 1 will take you to the originating
424 spot in the @file{.ly} file. Control-Mousebutton 2 will show all
427 If you correct large files with point-and-click, be sure to start
428 correcting at the end of the file. When you start at the top, and
429 insert one line, all following locations will be off by a line.
432 For using point-and-click with Emacs, add the following
433 In your Emacs startup file (usually @file{~/.emacs}):
438 Make sure that the environment variable @var{XEDITOR} is set to
440 emacsclient --no-wait +%l %f
442 @cindex @var{XEDITOR}
443 If you use XEmacs instead of Emacs, you use @code{(gnuserve-start)} in
444 your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}.
446 For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or
447 use this argument with Xdvi's @code{-editor} option.
450 For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or
451 use this argument with Xdvi's @code{-editor} option.
453 If can also make your editor jump to the exact location of the note
454 you clicked. This is only supported on Emacs and VIM. Users of Emacs version
455 20 must apply the patch @file{emacsclient.patch}. Users of version 21
456 must apply @file{server.el.patch} (version 21.2 and earlier). At the
457 top of the @code{ly} file, replace the @code{set-point-and-click} line
458 with the following line:
460 #(ly:set-point-and-click 'line-column)
462 @cindex line-column-location
463 and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. Vim
464 users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.
468 @node Invoking lilypond-latex
469 @section Invoking lilypond-latex
471 Before LilyPond 3.0, the @code{lilypond} program only generated music
472 notation. Titles and page layout was done in a separate wrapper
473 program. For compatibility with older files, this wrapper program has
474 been retained as @code{lilypond-latex}. It uses the LilyPond program
475 and La@TeX{} to create a nicely titled piece of sheet music. Use of
476 this program is only necessary if the input file contains special
477 La@TeX{} options or formatting codes in markup texts.
479 The @code{lilypond-latex} wrapper is invoked from the command-line as
482 @code{lilypond-latex} [@var{option}]@dots{} @var{file}@dots{}
485 To have @code{lilypond-latex} read from stdin, use a dash @code{-} for
486 @var{file}. The program supports the following options.
488 @cindex stdin, reading
492 Keep the temporary directory with all output
493 files. The temporary directory is created in the current directory as @code{@code{lilypond}.dir}.
496 @item -I,--include=@var{dir}
497 Add @var{dir} to LilyPond's include path.
498 @item -o,--output=@var{file}
499 Generate output to @var{file}. The extension of @var{file} is ignored.
501 Also generate pictures of each page, in PNG format.
503 Also generate a picture of the first system of the score.
512 @item -s,--set=@var{key}=@var{val}
513 Add @var{key}= @var{val} to the settings, overriding those specified
514 in the files. Possible keys: @code{language}, @code{latexheaders},
515 @code{latexpackages}, @code{latexoptions}, @code{papersize},
516 @code{linewidth}, @code{orientation},
519 Show version information.
521 Be verbose. This prints out commands as they are executed, and more
522 information about the formatting process is printed.
524 Print even more information. This is useful when generating bug reports.
526 Show the warranty with which GNU LilyPond comes. (It comes with
527 @strong{NO WARRANTY}!)
532 @subsection Additional parameters
534 The @code{lilypond} program responds to several parameters specified
535 in a @code{\paper} section of the input file. They can be overridden
536 by supplying a @code{--set} command line option.
540 Specify La@TeX{} language: the @code{babel} package will be
541 included. Default: unset.
543 Read from the @code{\header} block.
546 Specify additional La@TeX{} headers file.
547 Normally read from the @code{\header} block. Default value: empty.
550 Specify additional La@TeX{} packages file. This works cumulative,
551 so you can add multiple packages using multiple @code{-s=latexpackages} options.
552 Normally read from the @code{\header} block. Default value:
556 Specify additional options for the La@TeX{}
557 @code{\documentclass}. You can put any valid value here. This was
558 designed to allow @code{lilypond} to produce output for double-sided
559 paper, with balanced margins and page numbers on alternating sides. To
560 achieve this specify @code{twoside}.
563 Set orientation. Choices are @code{portrait} or @code{landscape}. Is
564 read from the @code{\paper} block, if set.
567 The vertical extension of the music on the page. It is normally
568 calculated automatically, based on the paper size.
571 The music line width. It is normally read from the @code{\paper}
575 The paper size (as a name, e.g. @code{a4}). It is normally read from
576 the @code{\paper} block.
579 The font encoding, should be set identical to the @code{font-encoding}
580 property in the score.