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::
17 @node Invoking lilypond
18 @section Invoking lilypond
20 Nicely titled output is created through a separate program:
21 @file{@code{lilypond}} is a script that uses the LilyPond formatting
22 engine (which is in a separate program) and La@TeX{} to create a
23 nicely titled piece of sheet music, in PDF (Portable Document Format)
27 @code{lilypond} [@var{option}]@dots{} @var{file}@dots{}
30 To have @code{lilypond} read from stdin, use a dash @code{-} for
31 @var{file}. The program supports the following options.
33 @cindex stdin, reading
37 Keep the temporary directory with all output
38 files. The temporary directory is created in the current directory as @code{@code{lilypond}.dir}.
41 @item -I,--include=@var{dir}
42 Add @var{dir} to LilyPond's include path.
44 Produce MIDI output only.
46 Do not run @file{lilypond-bin}. Useful for debugging @code{lilypond}.
47 @item -o,--output=@var{file}
48 Generate output to @var{file}. The extension of @var{file} is ignored.
50 Do not generate (PDF) or PS.
53 @cindex Scalable fonts
56 Also generate pictures of each page, in PNG format.
58 Gzip the postscript file.
60 Make a .HTML file with links to all output files.
62 Also generate a picture of the first system of the score.
71 @item -s,--set=@var{key}=@var{val}
72 Add @var{key}= @var{val} to the settings, overriding those specified
73 in the files. Possible keys: @code{language}, @code{latexheaders},
74 @code{latexpackages}, @code{latexoptions}, @code{papersize},
75 @code{pagenumber}, @code{linewidth}, @code{orientation},
78 Show version information.
80 Be verbose. This prints out commands as they are executed, and more
81 information about the formatting process is printed.
83 Print even more information. This is useful when generating bug reports.
85 Show the warranty with which GNU LilyPond comes. (It comes with
86 @strong{NO WARRANTY}!)
91 @subsection Additional parameters
93 The @code{lilypond} program responds to several parameters specified
94 in a @code{\paper} section of the input file. They can be overridden
95 by supplying a @code{--set} command line option.
99 Specify La@TeX{} language: the @code{babel} package will be
100 included. Default: unset.
102 Read from the @code{\header} block.
105 Specify additional La@TeX{} headers file.
107 Normally read from the @code{\header} block. Default value: empty.
110 Specify additional La@TeX{} packages file. This works cumulative,
111 so you can add multiple packages using multiple @code{-s=latexpackages} options.
112 Normally read from the @code{\header} block. Default value:
116 Specify additional options for the La@TeX{}
117 @code{\documentclass}. You can put any valid value here. This was
118 designed to allow @code{lilypond} to produce output for double-sided
119 paper, with balanced margins and page numbers on alternating sides. To
120 achieve this specify @code{twoside}.
123 Set orientation. Choices are @code{portrait} or @code{landscape}. Is
124 read from the @code{\paper} block, if set.
127 The vertical extension of the music on the page. It is normally
128 calculated automatically, based on the paper size.
131 The music line width. It is normally read from the @code{\paper}
135 The paper size (as a name, e.g. @code{a4}). It is normally read from
136 the @code{\paper} block.
139 If set to @code{no}, no page numbers will be printed. If set to a
140 positive integer, start with this value as the first page number.
144 The font encoding, should be set identical to the @code{font-encoding}
145 property in the score.
150 @node Invoking the lilypond binary
151 @section Invoking the lilypond binary
152 @cindex Invoking LilyPond
153 @cindex command line options
154 @cindex options, command line
158 The formatting system consists of two parts: a binary executable
159 (@file{lilypond-bin}), which is responsible for the formatting
160 functionality, and support scripts, which post-process the resulting
161 output. Normally, the support scripts are called, which in turn invoke
162 the @code{lilypond-bin} binary. However, @code{lilypond-bin} may be
163 called directly as follows.
166 lilypond-bin [@var{option}]@dots{} @var{file}@dots{}
170 When invoked with a filename that has no extension, the @file{.ly}
171 extension is tried first. To read input from stdin, use a
172 dash @code{-} for @var{file}.
174 When @file{filename.ly} is processed it will produce
175 @file{filename.tex} as output (or @file{filename.ps} for PostScript
176 output). If @file{filename.ly} contains more than one @code{\score}
177 block, then the rest of the scores will be output in numbered files,
178 starting with @file{filename-1.tex}. Several files can be specified;
179 they will each be processed independently. @footnote{The status of
180 GUILE is not reset across invocations, so be careful not to change any
181 system defaults from within Scheme.}
183 We strongly advise against making LilyPond formatting available
184 through a web server. That is, processing input from untrusted users,
185 and returning the resulting PDF file. LilyPond is a big and complex
186 program. It was not written with security in mind. Making it available
187 to the outside world is a huge risk; consider the security
193 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
198 @section Command line options
200 The following options are supported:
204 @item -e,--evaluate=@var{expr}
205 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
206 Multiple @code{-e} options may be given, they will be evaluated
207 sequentially. The function @code{ly:set-option} allows for access to
208 some internal variables. Use @code{-e '(ly:option-usage)'} for more
211 @item -f,--format=@var{format}
214 Output format for sheet music. Choices are @code{tex} (for @TeX{}
215 output, to be processed with La@TeX{}, or through @code{lilypond}),
216 @code{pdftex} for PDF@TeX{} input, @code{ps} (for PostScript),
217 @code{scm} (for a Scheme dump), @code{sk} (for Sketch).
219 @strong{This option is only for developers}. Only the @TeX{} output of
220 these is usable for real work.
223 @cindex output format, setting
224 @cindex Sketch output
225 @cindex PDFTeX output
226 @cindex PostScript output
230 Show a summary of usage.
231 @item --include, -I=@var{directory}
232 Add @var{directory} to the search path for input files.
233 @cindex file searching
235 @item -i,--init=@var{file}
236 Set init file to @var{file} (default: @file{init.ly}).
239 Disable @TeX{} output. If you have a @code{\midi} definition MIDI output
241 @item -o,--output=@var{FILE}
242 Set the default output file to @var{FILE}.
245 Disallow untrusted @code{\include} directives, limit available in-line
246 Scheme function, disable backslashes in @TeX{}, code.
249 Show version information.
251 Be verbose: show full paths of all files read, and give timing
255 Show the warranty with which GNU LilyPond comes. (It comes with
256 @strong{NO WARRANTY}!)
259 @section Environment variables
262 For processing both the @TeX{} and the PostScript output, the
263 appropriate environment variables must be set. The following scripts
267 @item @file{buildscripts/out/lilypond-profile}
269 @item @file{buildscripts/out/lilypond-login} (for C-shells)
272 They should normally be sourced as part of the login process. If these
273 scripts are not run from the system wide login process, then you must
276 @cindex installing LilyPond
278 If you use sh, bash, or a similar shell, then add the following to
279 your @file{.profile}:
281 . @var{/the/path/to/}lilypond-profile
284 If you use csh, tcsh or a similar shell, then add the following to
285 your @file{~/.login}:
287 source @var{/the/path/to/}lilypond-login
290 Of course, in both cases, you should substitute the proper location of
293 These scripts set the following variables:
296 To make sure that @TeX{} and lilypond find data files (among
297 others @file{.tex}, @file{.mf} and @file{.tfm}),
298 you have to set @code{TEXMF} to point to the lilypond data
299 file tree. A typical setting would be
301 @{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
306 For processing PostScript output (obtained with
307 @code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
308 point to the directory containing library PS files.
311 For processing PostScript output (obtained with
312 @code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
313 point to the directory containing PFA files.
315 When you print direct PS output, remember to send the PFA files to the
325 @cindex printing postscript
327 The binary itself recognizes the following environment variables:
330 This specifies a directory where locale messages and
331 data files will be looked up by default. The directory should contain
332 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
335 This selects the language for the warning messages.
339 @cindex LILYPONDPREFIX
342 @section Error messages
344 @cindex error messages
345 Different error messages can appear while compiling a file:
351 Something looks suspect. If you are requesting something out of the
352 ordinary then you will understand the message, and can ignore it.
353 However, warnings usually indicate that something is wrong with the
357 Something is definitely wrong. The current processing step (parsing,
358 interpreting, or formatting) will be finished, but the next step will
364 Something is definitely wrong, and LilyPond cannot continue. This
365 happens rarely. The most usual cause is misinstalled fonts.
367 @cindex trace, Scheme
371 Errors that occur while executing Scheme code are caught by the Scheme
372 interpreter. If running with the verbose option (@code{-V} or
373 @code{--verbose}) then a call trace is printed of the offending
376 @cindex Programming error
377 @item Programming error
378 There was some internal inconsistency. These error messages are
379 intended to help the programmers and debuggers. Usually, they can be
380 ignored. Sometimes, they come in such big quantities that they obscure
381 other output. In this case, file a bug-report.
383 @item Aborted (core dumped)
384 This signals a serious programming error that caused the program to
385 crash. Such errors are considered critical. If you stumble on one,
391 @cindex errors, message format
392 If warnings and errors can
393 be linked to some part of the input file, then error messages have the
397 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
398 @var{offending input line}
401 A line-break is inserted in offending line to indicate the column
402 where the error was found. For example,
405 test.ly:2:19: error: not a duration: 5:
412 @section Reporting bugs
415 @cindex reporting bugs
417 If you have input that results in a crash or an erroneous output, then
418 that is a bug. We try respond to bug-reports promptly, and fix them as
419 soon as possible. For this, we need to reproduce and isolate the
420 problem. Help us by sending a defective input file, so we can
421 reproduce the problem. Make it small, so we can easily debug the
422 problem. Don't forget to tell which version you use, and on which
423 platform you run it. Send the report to
424 @email{bug-lilypond@@gnu.org}.
427 @section Editor support
432 @cindex modes, editor
433 @cindex syntax coloring
434 @cindex coloring, syntax
436 There is support from different editors for LilyPond.
440 Emacs has a @file{lilypond-mode}, which provides keyword
441 autocompletion, indentation, LilyPond specific parenthesis matching
442 and syntax coloring, handy compile short-cuts and reading LilyPond
443 manuals using Info. If lilypond-mode is not installed on your
444 platform, then refer to the installation instructions for more
449 For @uref{http://www.vim.org,VIM}, a vimrc is supplied, along with
450 syntax coloring tools. For more information, refer to the
452 @uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
455 installation instructions.
459 For both editors, there is also a facility to jump in the input file
460 to the source of errors in the graphical output. See @ref{Point and
465 There exists a plugin for @uref{http://www.jedit.org/,jEdit}. Refer to
466 the @uref{http://lily4jedit.sourceforge.net,plugin website} for more
471 @node Point and click
472 @section Point and click
473 @cindex point and click
475 @cindex source specials
476 @cindex specials, source
478 Point and click lets you find notes in the input by clicking on them in
479 the Xdvi window. This makes it easier to find input that causes some
480 error in the sheet music.
482 To use it, you need the following software:
484 @item a dvi viewer that supports src specials:
486 @item Xdvi, version 22.36 or newer. Available from
487 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}.
489 Most @TeX{} distributions ship with xdvik, which is always a few
490 versions behind the official Xdvi. To find out which Xdvi you are
491 running, try @code{xdvi -version} or @code{xdvi.bin -version}.
492 @item KDVI. A dvi viewer for KDE. You need KDVI from KDE 3.0 or
493 newer. Enable option @emph{Inverse search} in the menu @emph{Settings}.
495 Apparently, KDVI does not process PostScript specials correctly. Beams
496 and slurs will not be visible in KDVI.
505 @item an editor with a client/server interface (or a lightweight GUI
511 @item Emacs. Emacs is an extensible text-editor. It is available from
512 @uref{http://www.gnu.org/software/emacs/}. You need version 21 to use
515 @c move this elsewhere?
520 @cindex lilypond-mode for Emacs
521 @cindex syntax coloring
523 @item XEmacs. XEmacs is very similar to Emacs.
527 @item NEdit. NEdit runs under Windows, and Unix.
528 It is available from @uref{http://www.nedit.org}.
532 @item GVim. GVim is a GUI variant of VIM, the popular VI
533 clone. It is available from @uref{http://www.vim.org}.
542 Xdvi must be configured to find the @TeX{} fonts and music
543 fonts. Refer to the Xdvi documentation for more information.
545 To use point-and-click, add one of these lines to the top of your .ly
548 #(ly:set-point-and-click 'line)
550 @cindex line-location
552 When viewing, Control-Mousebutton 1 will take you to the originating
553 spot in the @file{.ly} file. Control-Mousebutton 2 will show all
556 If you correct large files with point-and-click, be sure to start
557 correcting at the end of the file. When you start at the top, and
558 insert one line, all following locations will be off by a line.
561 For using point-and-click with Emacs, add the following
562 In your Emacs startup file (usually @file{~/.emacs}):
567 Make sure that the environment variable @var{XEDITOR} is set to
569 emacsclient --no-wait +%l %f
571 @cindex @var{XEDITOR}
572 If you use XEmacs instead of Emacs, you use @code{(gnuserve-start)} in
573 your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}.
575 For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or
576 use this argument with Xdvi's @code{-editor} option.
579 For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or
580 use this argument with Xdvi's @code{-editor} option.
582 If can also make your editor jump to the exact location of the note
583 you clicked. This is only supported on Emacs and VIM. Users of Emacs version
584 20 must apply the patch @file{emacsclient.patch}. Users of version 21
585 must apply @file{server.el.patch} (version 21.2 and earlier). At the
586 top of the @code{ly} file, replace the @code{set-point-and-click} line
587 with the following line:
589 #(ly:set-point-and-click 'line-column)
591 @cindex line-column-location
592 and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. Vim
593 users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.