1 @c -*- coding: utf-8; mode: texinfo; -*-
3 @chapter Running LilyPond
5 This chapter details the technicalities of running LilyPond.
11 * Updating files with convert-ly::
15 * Including LilyPond files::
18 @node Invoking lilypond
19 @section Invoking lilypond
20 @cindex Invoking LilyPond
21 @cindex command line options
22 @cindex options, command line
26 The @code{lilypond} executable may be called as follows from the command line.
29 lilypond [@var{option}]@dots{} @var{file}@dots{}
33 When invoked with a filename that has no extension, the @file{.ly}
34 extension is tried first. To read input from stdin, use a
35 dash (@code{-}) for @var{file}.
37 When @file{filename.ly} is processed it will produce
38 @file{filename.tex} as output (or @file{filename.ps} for PostScript
39 output). If @file{filename.ly} contains more than one @code{\score}
40 block, then the rest of the scores will be output in numbered files,
41 starting with @file{filename-1.tex}. Several files can be specified;
42 they will each be processed independently. @footnote{The status of
43 GUILE is not reset after processing a @code{.ly} file, so be careful
44 not to change any system defaults from within Scheme.}
47 @section Command line options
49 The following options are supported:
53 @item -e,--evaluate=@var{expr}
54 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
55 Multiple @code{-e} options may be given, they will be evaluated
58 @item -f,--format=@var{format}
59 which formats should be written. Choices are @code{svg}, @code{ps},
60 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
62 @item -b,--backend=@var{format}
63 the output format to use for the back-end. Choices are
66 for @TeX{} output, to be processed with La@TeX{}. If present, the file
67 @file{file.textmetrics} is read to determine text extents.
69 dump text strings to @file{.texstr} file, which can be run through
70 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
71 extents of strings of text.
74 @cindex PostScript output
76 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
77 these fonts is done. When using oriental character sets, this can
81 for encapsulated PostScript. This dumps every page (system) as a separate
82 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
83 all pages (systems) including fonts.
85 This mode is used by default by lilypond-book.
88 for SVG (Scalable Vector Graphics).
89 @cindex SVG (Scalable Vector Graphics)
90 SVG files include embedded fonts. Thus you need a SVG capable
91 viewer which supports embedded fonts, or a SVG viewer is able to
92 replace the embedded fonts with OTF fonts.
93 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
94 (version 0.42 or later), after copying the OTF fonts in directory
95 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @code{~/.fonts/}.
97 for a dump of the raw, internal Scheme-based drawing commands.
101 @cindex output format, setting
103 @item -d,--define-default=@var{var}=@var{val}
104 This sets the internal program option @var{var} to the Scheme value
105 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
106 switch off an option, @code{no-} may be prefixed to @var{var}, eg.
114 -dpoint-and-click='#f'
117 @cindex point and click
119 Setting the @code{help} option will print a summary of the options
123 Show a summary of usage.
125 @item --include, -I=@var{directory}
126 Add @var{directory} to the search path for input files.
127 @cindex file searching
130 @item -i,--init=@var{file}
131 Set init file to @var{file} (default: @file{init.ly}).
133 @item -o,--output=@var{FILE}
134 Set the default output file to @var{FILE}. The appropriate
135 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
142 Generate DVI files. In this case, the @TeX{} backend should be
143 specified, i.e., @code{-b tex}.
146 Generate pictures of each page, in PNG format. This implies
147 @code{--ps}. The resolution in DPI of the image may be set with
153 Generate PDF. This implies @code{--ps}.
156 Generate an output file containing the titles and the first system
159 Do not generate the full pages. Useful in combination with
163 Do not trust the @code{.ly} input.
165 When LilyPond formatting is available through a web server, either the
166 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
167 @code{--safe} option will prevent inline Scheme code from wreaking
170 When LilyPond formatting is available through a web server, the
171 @code{--safe} @b{MUST} be passed. This will prevent inline Scheme
172 code from wreaking havoc, for example
178 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
183 The @code{--safe} option works by evaluating in-line Scheme
184 expressions in a special safe module. This safe module is derived from
185 GUILE @file{safe-r5rs} module, but adds a number of functions of the
186 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
188 In addition, @code{--safe} disallows @code{\include} directives and
189 disables the use of backslashes in @TeX{} strings.
191 In @code{--safe} mode, it is not possible to import LilyPond variables
194 @code{--safe} does @emph{not} detect resource overuse. It is still
195 possible to make the program hang indefinitely, for example by feeding
196 cyclic data structures into the backend. Therefore, if using LilyPond
197 on a publicly accessible webserver, the process should be limited in
198 both CPU and memory usage.
200 Note that @code{--safe} will prevent many useful LilyPond snippets from
201 being compiled. For a softer but secure alternative you can use the
202 @code{--jail} option.
205 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
206 Run LilyPond in a chroot jail.
208 The @code{--jail} option provides a more flexible alternative to
209 @code{--safe} when LilyPond formatting is available through a web
210 server or whenever LilyPond executes externally provided
213 The @code{--jail} option works by changing the root of LilyPond to
214 @var{jail} just before starting the actual compilation process. The user
215 and group are then changed to match those provided, and the current
216 directory is changed to @var{dir}. This setup guarantees that it is not
217 possible (at least in theory) to escape from the jail. Note that for
218 @code{--jail} to work LilyPond must be run as root, which is usually
219 accomplished in a safe way using @command{sudo}.
221 Setting up a jail is a slightly delicate matter, as we must be sure that
222 LilyPond is able to find whatever it needs to compile the source
223 @emph{inside the jail}. A typical setup comprises the following items:
226 @item Setting up a separate filesystem
227 A separate filesystem should be created for LilyPond, so that it can be
228 mounted with safe options such as @code{noexec}, @code{nodev}, and
229 @code{nosuid}. In this way, it is impossible to run executables or to
230 write directly to a device from LilyPond. If you do not want to create a
231 separate partition, just create a file of reasonable size and use it to
232 mount a loop device. A separate filesystem also guarantees that LilyPond
233 cannot write more space than it is allowed.
235 @item Setting up a separate user
236 A separate user and group (say, @samp{lily}/@samp{lily}) with low
237 privileges should be used to run LilyPond inside the jail. There should
238 be a single directory writable by this user, which should be passed in
241 @item Preparing the jail
242 LilyPond needs to read a number of files while running. All these files
243 are to be copied into the jail, under the same path they apper in the
244 real root filesystem. The entire content of the LilyPond installation
245 (e.g., @file{/usr/share/lilypond})
248 If problems arise, the simplest way to trace them down is to run
249 LilyPond using @command{strace}, which will allow you to determine which
252 @item Running LilyPond
253 In a jail mounted with @code{noexec} it is impossible to execute any external
254 program. Therefore LilyPond must be run with a backend that does not
255 require any such program. As we already mentioned, it must be also run
256 with superuser privileges (which, of course, it will lose immediately),
257 possibly using @command{sudo}. It is a good idea to limit the number of
258 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
259 -t}), and, if your operating system supports it, the amount of memory
260 that can be allocated.
265 Show version information.
268 Be verbose: show full paths of all files read, and give timing
272 Show the warranty with which GNU LilyPond comes. (It comes with
273 @strong{NO WARRANTY}!)
277 @section Environment variables
281 @cindex LILYPONDPREFIX
283 @code{Lilypond} recognizes the following environment variables:
286 This specifies a directory where locale messages and
287 data files will be looked up by default. The directory should contain
288 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
291 This selects the language for the warning messages.
293 @item LILYPOND_GC_YIELD
294 With this variable the memory footprint and performance can be
295 adjusted. It is a percentage tunes memory management behavior. With
296 higher values, the program uses more memory, with smaller values, it
297 uses more CPU time. The default value is @code{70}.
303 @section Error messages
305 @cindex error messages
306 Different error messages can appear while compiling a file:
312 Something looks suspect. If you are requesting something out of the
313 ordinary then you will understand the message, and can ignore it.
314 However, warnings usually indicate that something is wrong with the
318 Something is definitely wrong. The current processing step (parsing,
319 interpreting, or formatting) will be finished, but the next step will
325 Something is definitely wrong, and LilyPond cannot continue. This
326 happens rarely. The most usual cause is misinstalled fonts.
328 @cindex trace, Scheme
332 Errors that occur while executing Scheme code are caught by the Scheme
333 interpreter. If running with the verbose option (@code{-V} or
334 @code{--verbose}) then a call trace of the offending
335 function call is printed.
337 @cindex Programming error
338 @item Programming error
339 There was some internal inconsistency. These error messages are
340 intended to help the programmers and debuggers. Usually, they can be
341 ignored. Sometimes, they come in such big quantities that they obscure
342 other output. In this case, file a bug-report.
344 @item Aborted (core dumped)
345 This signals a serious programming error that caused the program to
346 crash. Such errors are considered critical. If you stumble on one,
352 @cindex errors, message format
353 If warnings and errors can
354 be linked to some part of the input file, then error messages have the
358 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
359 @var{offending input line}
362 A line-break is inserted in the offending line to indicate the column
363 where the error was found. For example,
366 test.ly:2:19: error: not a duration: 5:
371 These locations are LilyPond's best guess about where the warning or
372 error occured, but (by their very nature) warnings and errors occur
373 when something unexpected happens. If you can't see an error in the
374 indicated line of your input file, try checking one or two lines
375 above the indicated position.
378 @node Updating files with convert-ly
379 @section Updating with @command{convert-ly}
381 @cindex Updating a LilyPond file
382 @cindex @code{convert-ly}
384 The LilyPond input syntax is routinely changed to simplify it or improve
385 it in different ways. As a side effect of this, the LilyPond interpreter
386 often is no longer compatible with older input files. To remedy this,
387 the program @command{convert-ly} can be used to deal with most of the
388 syntax changes between LilyPond versions.
390 It uses @code{\version} statements in the input files to detect the
391 old version number. In most cases, to upgrade your input file it is
392 sufficient to run@footnote{MacOS X users may execute this command
393 under the menu entry @samp{Compile > Update syntax}.}
396 convert-ly -e myfile.ly
399 If there are no changes to myfile.ly and file called myfile.ly.NEW
400 is created, then myfile.ly is already updated.
402 @command{convert-ly} always converts up to the last syntax change handled by
403 it. This means that the @code{\version} number left in the file is
404 usually lower than the version of @command{convert-ly} itself.
406 To upgrade LilyPond fragments in texinfo files, use
409 convert-ly --from=... --to=... --no-version *.itely
412 To upgrade many files at once, combine @code{convert-ly} with
413 standard unix commands. This example will upgrade all @code{.ly}
414 files in the current directory
417 for f in *.ly; do convert-ly -e $f; done;
420 In general, the program is invoked as follows:
423 convert-ly [@var{option}]@dots{} @var{file}@dots{}
427 The following options can be given:
431 Do an inline edit of the input file. Overrides @code{--output}.
433 @item -f,--from=@var{from-patchlevel}
434 Set the version to convert from. If this is not set, @command{convert-ly}
435 will guess this, on the basis of @code{\version} strings in the file.
437 @item -n,--no-version
438 Normally, @command{convert-ly} adds a @code{\version} indicator
439 to the output. Specifying this option suppresses this.
441 @item -s, --show-rules
442 Show all known conversions and exit.
444 @item --to=@var{to-patchlevel}
445 Set the goal version of the conversion. It defaults to the latest
455 Not all language changes are handled. Only one output option can be
459 @c We might want to make this a completely new section, along with more
460 @c info about how to upgrade old input files. -gp
463 Copy and paste from CVS, last updated
466 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
470 There are a few things that the convert-ly cannot handle. Here's a list of limitations
471 that the community has complained about.
473 This bug report structure has been chosen because convert-ly has a structure that doesn't
474 allow to smoothly implement all needed changes. Thus this is just a wishlist, placed
478 Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
479 To be able to run convert-ly
480 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
481 and similarly I replaced '>}' with '&}'. After the conversion, I could
482 then change back from '{ #' to '{ <' and from '& }' to '> }'.
483 Doesn't convert all text markup correctly. In the old markup syntax,
484 it was possible to group a number of markup commands together within parentheses, e.g.
485 -#'((bold italic) "string")
486 This will incorrectly be converted into
487 -\markup{{\bold italic} "string"}
488 instead of the correct
489 -\markup{\bold \italic "string"}
491 Doesn't handle \partcombine
492 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
494 \magnify isn't changed to \fontsize.
495 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
496 remove-tag isn't changed.
497 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
498 firstpagenumber isn't changed.
499 - firstpagenumber no => printfirstpagenumber = ##f
500 Line breaks in header strings aren't converted.
501 - \\\\ as line break in \header strings => \markup \center-align <
502 "First Line" "Second Line" >
503 Crescendo and decrescendo terminators aren't converted.
507 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
509 \markup{ \center-align <{ ... }> } should be converted to:
510 \markup{ \center-align {\line { ... }} }
511 but now, \line is missing.
513 Special LaTeX characters such as $~$ in text are not converted to UTF8.
519 @section Reporting bugs
522 @cindex reporting bugs
524 If you have input that results in a crash or an erroneous output, then
525 that is a bug. We try to respond to bug-reports promptly, and fix them as
526 soon as possible. Help us by sending a defective input file, so we can
527 reproduce the problem. Make it small, so we can easily debug the
528 problem. Don't forget to tell which version of LilyPond you use! Send
532 @uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs}
536 @c the bug database is not up to date enough.
538 When you've found a bug, have a look at our
539 @uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if
540 it has already been reported. You could also try to do a few searches
541 on the mailing list for the bug. Sometimes the bug will have already
542 been reported and a fix or workaround is already known.
545 Here is an example of a good bug report:
548 It seems that placement of accidentals is broken. In the
549 following example, the accidental touches the note head.
551 Using Mac OSX 10.3.7, fink package lilypond-devel
562 \override Accidental #'extra-offset = #'(1.0 . 0)
568 @section Editor support
573 @cindex modes, editor
574 @cindex syntax coloring
575 @cindex coloring, syntax
577 There is support from different editors for LilyPond.
581 Emacs has a @file{lilypond-mode}, which provides keyword
582 autocompletion, indentation, LilyPond specific parenthesis matching
583 and syntax coloring, handy compile short-cuts and reading LilyPond
584 manuals using Info. If @file{lilypond-mode} is not installed on your
585 platform, then read the
587 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
590 installation instructions.
595 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
596 with syntax coloring tools. For more information, refer to the
598 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
601 installation instructions.
607 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
608 This plugin includes a DVI viewer, integrated help and viewing via
609 GhostScript. It can be installed by doing @key{Plugins > Plugin
610 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
614 All these editors can be made to jump into the input file to the source
615 of a symbol in the graphical output. See @ref{Point and click}.
619 @section File structure
621 The major part of this manual is concerned with entering various
622 forms of music in LilyPond. However, many music expressions are not
623 valid input on their own, for example, a @code{.ly} file containing
630 will result in a parsing error. Instead, music should be inside other
631 expressions, which may be put in a file by themselves. Such
632 expressions are called toplevel expressions. This section enumerates
635 A @code{.ly} file contains any number of toplevel expressions, where a
636 toplevel expression is one of the following
640 An output definition, such as @code{\paper}, @code{\midi}, and
641 @code{\layout}. Such a definition at the toplevel changes the default
642 settings for the block entered.
645 A @code{\header} block. This sets the global header block. This
646 is the block containing the definitions for book-wide settings, like
647 composer, title, etc.
650 An @code{\addquote} statement. See @ref{Quoting other voices}
651 for more information.
654 A @code{\score} block. This score will be collected with other
655 toplevel scores, and combined as a single @code{\book}.
657 This behavior can be changed by setting the variable
658 @code{toplevel-score-handler} at toplevel. The default handler is
659 defined in the init file @file{scm/@/lily@/.scm}.
661 The @code{\score} must begin with music, and may contain only
665 A @code{\book} block logically combines multiple movements
666 (i.e., multiple @code{\score} blocks) in one document. A number of
667 @code{\scores} creates a single output file, where all movement are
670 This behavior can be changed by setting the variable
671 @code{toplevel-book-handler} at toplevel. The default handler is
672 defined in the init file @file{scm/@/lily@/.scm}.
675 A compound music expression, such as
680 This will add the piece in a @code{\score} and format it in a
681 single book together with all other toplevel @code{\score}s and music
684 This behavior can be changed by setting the variable
685 @code{toplevel-music-handler} at toplevel. The default handler is
686 defined in the init file @file{scm/@/lily@/.scm}.
689 A markup text, a verse for example
692 2. The first line verse two.
696 Markup texts are rendered above, between or below the scores or music
697 expressions, wherever they appear.
700 An indentifier, such as
705 This can be used later on in the file by entering @code{\foo}. The
706 name of an identifier should have alphabetic characters only; no
707 numbers, underscores or dashes.
711 The following example shows three things that may be entered at
716 % movements are non-justified by default
728 At any point in a file, any of the following lexical instructions can
732 @item @code{\version}
733 @item @code{\include}
734 @item @code{\renameinput}
738 @node Including LilyPond files
739 @section Including LilyPond files
741 @cindex @code{\include}
742 @cindex including files
744 A large project may be split up into separate files. To refer to another
748 \include "otherfile.ly"
751 The line @code{\include "file.ly"} is equivalent to pasting the contents
752 of file.ly into the current file at the place where you have the
753 \include. For example, for a large project you might write separate files
754 for each instrument part and create a ``full score'' file which brings
755 together the individual instrument files.
757 The initialization of LilyPond is done in a number of files that are
758 included by default when you start the program, normally transparent to the
759 user. Run lilypond --verbose to see a list of paths and files that Lily
762 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
763 VERSION is in the form ``2.6.1'') are on the path and available to
764 @code{\include}. Files in the
765 current working directory are available to \include, but a file of the same
766 name in LilyPond's installation takes precedence. Files are
767 available to \include from directories in the search path specified as an
768 option when invoking @code{lilypond --include=DIR} which adds DIR to the search
771 The @code{\include} statement can use full path information, but with the Unix
772 convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
773 if @file{stuff.ly} is located one directory higher than the current working
777 \include "../stuff.ly"