1 @c -*- coding: latin-1; 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
56 sequentially. The function @code{ly:set-option} allows access to
57 some internal variables. Use @code{-e '(ly:option-usage)'} for more
60 @item -f,--format=@var{format}
61 which formats should be written. Choices are @code{svg}, @code{ps},
62 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
64 @item -b,--backend=@var{format}
65 the output format to use for the back-end. Choices are
68 for @TeX{} output, to be processed with La@TeX{}. If present, the file
69 @file{file.textmetrics} is read to determine text extents.
71 dump text strings to @file{.texstr} file, which can be run through
72 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
73 extents of strings of text.
76 @cindex PostScript output
78 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
79 these fonts is done. When using oriental character sets, this can
83 for encapsulated PostScript. This dumps every page (system) as a separate
84 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
85 all pages (systems) including fonts.
87 This mode is used by default by lilypond-book.
90 for SVG (Scalable Vector Graphics)
91 @cindex SVG (Scalable Vector Graphics)
93 for a dump of the raw, internal Scheme-based drawing commands.
97 @cindex output format, setting
99 @item -d,--define-default=@var{var}=@var{val}
100 This defines an internal variable @var{var} as the Scheme value
103 Supported values include:
107 @item preview-include-book-title
108 include book-titles in preview
111 These settings are returned when calling
112 @code{(ly:get-option 'command-line-settings)} from Scheme.
115 Show a summary of usage.
117 @item --include, -I=@var{directory}
118 Add @var{directory} to the search path for input files.
119 @cindex file searching
122 @item -i,--init=@var{file}
123 Set init file to @var{file} (default: @file{init.ly}).
125 @item -o,--output=@var{FILE}
126 Set the default output file to @var{FILE}. The appropriate
127 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
134 Generate DVI files. In this case, the @TeX{} backend should be
135 specified, i.e., @code{-f tex}.
138 Generate pictures of each page, in PNG format. This implies @code{--ps}.
141 Generate PDF. This implies @code{--ps}.
144 Generate an output file containing the titles and the first system
147 Do not generate the full pages. Useful in combination with
151 Do not trust the @code{.ly} input.
153 When LilyPond formatting is available through a web server, either the
154 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
155 @code{--safe} option will prevent inline Scheme code from wreaking
158 When LilyPond formatting is available through a web server, the
159 @code{--safe} @b{MUST} be passed. This will prevent inline Scheme
160 code from wreaking havoc, for example
166 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
171 The @code{--safe} option works by evaluating in-line Scheme
172 expressions in a special safe module. This safe module is derived from
173 GUILE @file{safe-r5rs} module, but adds a number of functions of the
174 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
176 In addition, @code{--safe} disallows @code{\include} directives and
177 disables the use of backslashes in @TeX{} strings.
179 In @code{--safe} mode, it is not possible to import LilyPond variables
182 @code{--safe} does @emph{not} detect resource overuse. It is still
183 possible to make the program hang indefinitely, for example by feeding
184 cyclic data structures into the backend. Therefore, if using LilyPond
185 on a publicly accessible webserver, the process should be limited in
186 both CPU and memory usage.
188 Note that @code{--safe} will prevent many useful LilyPond snippets from
189 being compiled. For a softer but secure alternative you can use the
190 @code{--jail} option.
193 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
194 Run LilyPond in a jail.
196 The @code{--jail} option provides a more flexible alternative to
197 @code{--safe} when LilyPond formatting is available through a web
198 server or whenever LilyPond executes externally provided
201 The @code{--jail} option works by changing the root of LilyPond to
202 @var{jail} just before starting the actual compilation process. The user
203 and group are then changed to match those provided, and the current
204 directory is changed to @var{dir}. This setup guarantees that it is not
205 possible (at least in theory) to escape from the jail. Note that for
206 @code{--jail} to work LilyPond must be run as root, which is usually
207 accomplished in a safe way using @command{sudo}.
209 Setting up a jail is a slightly delicate matter, as we must be sure that
210 LilyPond is able to find whatever it needs to compile the source
211 @emph{inside the jail}. A typical setup comprises the following items:
214 @item Setting up a separate filesystem
215 A separate filesystem should be created for LilyPond, so that it can be
216 mounted with safe options such as @code{noexec}, @code{nodev}, and
217 @code{nosuid}. In this way, it is impossible to run executables or to
218 write directly to a device from LilyPond. If you do not want to create a
219 separate partition, just create a file of reasonable size and use it to
220 mount a loop device. A separate filesystem also guarantees that LilyPond
221 cannot write more space than it is allowed.
223 @item Setting up a separate user
224 A separate user and group (say, @samp{lily}/@samp{lily}) with low
225 privileges should be used to run LilyPond inside the jail. There should
226 be a single directory writable by this user, which should be passed in
229 @item Preparing the jail
230 LilyPond needs to read a number of files while running. All these files
231 are to be copied into the jail, under the same path they apper in the
232 real root filesystem. The entire content of the LilyPond installation
233 (e.g., @file{/usr/share/lilypond})
236 If problems arise, the simplest way to trace them down is to run
237 LilyPond using @command{strace}, which will allow you to determine which
240 @item Running LilyPond
241 In a jail mounted with @code{noexec} it is impossible to execute any external
242 program. Therefore LilyPond must be run with a backend that does not
243 require any such program. As we already mentioned, it must be also run
244 with superuser privileges (which, of course, it will lose immediately),
245 possibly using @command{sudo}. It is a good idea to limit the number of
246 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
247 -t}), and, if your operating system supports it, the amount of memory
248 that can be allocated.
253 Show version information.
256 Be verbose: show full paths of all files read, and give timing
260 Show the warranty with which GNU LilyPond comes. (It comes with
261 @strong{NO WARRANTY}!)
265 @section Environment variables
268 For processing both the @TeX{} and the PostScript output, the
269 appropriate environment variables must be set. The following scripts
273 @item @file{buildscripts/@/out/@/lilypond@/-profile}
275 @item @file{buildscripts/@/out/@/lilypond@/-login} (for C-shells)
278 They should normally be sourced as part of the login process. If these
279 scripts are not run from the system wide login process, then you must
282 @cindex installing LilyPond
284 If you use sh, bash, or a similar shell, then add the following to
285 your @file{.profile}:
287 . @var{/the/path/to/}lilypond-profile
290 If you use csh, tcsh or a similar shell, then add the following to
291 your @file{~/.login}:
293 source @var{/the/path/to/}lilypond-login
296 Of course, in both cases, you should substitute the proper location of
299 These scripts set the following variables:
302 To make sure that @TeX{} and lilypond find data files (among
303 others @file{.tex}, @file{.mf}, and @file{.tfm}),
304 you have to set @code{TEXMF} to point to the lilypond data
305 file tree. A typical setting would be
307 @{/usr/share/lilypond/2.4.0,@{!!/usr/share/texmf@}@}
314 @cindex printing postscript
320 @cindex LILYPONDPREFIX
322 @code{Lilypond} recognizes the following environment variables:
325 This specifies a directory where locale messages and
326 data files will be looked up by default. The directory should contain
327 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
330 This selects the language for the warning messages.
335 @section Error messages
337 @cindex error messages
338 Different error messages can appear while compiling a file:
344 Something looks suspect. If you are requesting something out of the
345 ordinary then you will understand the message, and can ignore it.
346 However, warnings usually indicate that something is wrong with the
350 Something is definitely wrong. The current processing step (parsing,
351 interpreting, or formatting) will be finished, but the next step will
357 Something is definitely wrong, and LilyPond cannot continue. This
358 happens rarely. The most usual cause is misinstalled fonts.
360 @cindex trace, Scheme
364 Errors that occur while executing Scheme code are caught by the Scheme
365 interpreter. If running with the verbose option (@code{-V} or
366 @code{--verbose}) then a call trace of the offending
367 function call is printed.
369 @cindex Programming error
370 @item Programming error
371 There was some internal inconsistency. These error messages are
372 intended to help the programmers and debuggers. Usually, they can be
373 ignored. Sometimes, they come in such big quantities that they obscure
374 other output. In this case, file a bug-report.
376 @item Aborted (core dumped)
377 This signals a serious programming error that caused the program to
378 crash. Such errors are considered critical. If you stumble on one,
384 @cindex errors, message format
385 If warnings and errors can
386 be linked to some part of the input file, then error messages have the
390 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
391 @var{offending input line}
394 A line-break is inserted in the offending line to indicate the column
395 where the error was found. For example,
398 test.ly:2:19: error: not a duration: 5:
403 These locations are LilyPond's best guess about where the warning or
404 error occured, but (by their very nature) warnings and errors occur
405 when something unexpected happens. If you can't see an error in the
406 indicated line of your input file, try checking one or two lines
407 above the indicated position.
410 @node Updating files with convert-ly
411 @section Updating with @command{convert-ly}
413 The LilyPond input syntax is routinely changed to simplify it or improve
414 it in different ways. As a side effect of this, the LilyPond interpreter
415 often is no longer compatible with older input files. To remedy this,
416 the program @command{convert-ly} can be used to deal with most of the
417 syntax changes between LilyPond versions.
419 It uses @code{\version} statements in the input files to detect the old
420 version number. In most cases, to upgrade your input file it is sufficient
424 convert-ly -e myfile.ly
427 If there are no changes to myfile.ly and file called myfile.ly.NEW
428 is created, then myfile.ly is already updated.
430 @command{convert-ly} always converts up to the last syntax change handled by
431 it. This means that the @code{\version} number left in the file is
432 usually lower than the version of @command{convert-ly} itself.
434 To upgrade LilyPond fragments in texinfo files, use
437 convert-ly --from=... --to=... --no-version *.itely
440 To upgrade many files at once, combine @code{convert-ly} with
441 standard unix commands. This example will upgrade all @code{.ly}
442 files in the current directory
445 for f in *.ly; do convert-ly -e $f; done;
448 In general, the program is invoked as follows:
451 convert-ly [@var{option}]@dots{} @var{file}@dots{}
455 The following options can be given:
459 Do an inline edit of the input file. Overrides @code{--output}.
461 @item -f,--from=@var{from-patchlevel}
462 Set the version to convert from. If this is not set, @command{convert-ly}
463 will guess this, on the basis of @code{\version} strings in the file.
465 @item -o,--output=@var{file}
466 Set the output file to write.
468 @item -n,--no-version
469 Normally, @command{convert-ly} adds a @code{\version} indicator
470 to the output. Specifying this option suppresses this.
472 @item -s, --show-rules
473 Show all known conversions and exit.
475 @item --to=@var{to-patchlevel}
476 Set the goal version of the conversion. It defaults to the latest
486 Not all language changes are handled. Only one output option can be
490 @c We might want to make this a completely new section, along with more
491 @c info about how to upgrade old input files. -gp
494 Copy and paste from CVS, last updated
497 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
501 There are a few things that the convert-ly cannot handle. Here's a list of limitations
502 that the community has complained about.
504 This bug report structure has been chosen because convert-ly has a structure that doesn't
505 allow to smoothly implement all needed changes. Thus this is just a wishlist, placed
509 Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
510 To be able to run convert-ly
511 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
512 and similarly I replaced '>}' with '&}'. After the conversion, I could
513 then change back from '{ #' to '{ <' and from '& }' to '> }'.
514 Doesn't convert all text markup correctly. In the old markup syntax,
515 it was possible to group a number of markup commands together within parentheses, e.g.
516 -#'((bold italic) "string")
517 This will incorrectly be converted into
518 -\markup{{\bold italic} "string"}
519 instead of the correct
520 -\markup{\bold \italic "string"}
522 Doesn't handle \partcombine
523 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
525 \magnify isn't changed to \fontsize.
526 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
527 remove-tag isn't changed.
528 - \applymusic #(remove-tag '. . .) => \keepWithTag #'. . .
529 firstpagenumber isn't changed.
530 - firstpagenumber no => printfirstpagenumber = ##f
531 Line breaks in header strings aren't converted.
532 - \\\\ as line break in \header strings => \markup \center-align <
533 "First Line" "Second Line" >
534 Crescendo and decrescendo terminators aren't converted.
538 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
540 \markup{ \center-align <{ ... }> } should be converted to:
541 \markup{ \center-align {\line { ... }} }
542 but now, \line is missing.
548 @section Reporting bugs
551 @cindex reporting bugs
553 If you have input that results in a crash or an erroneous output, then
554 that is a bug. We try to respond to bug-reports promptly, and fix them as
555 soon as possible. Help us by sending a defective input file, so we can
556 reproduce the problem. Make it small, so we can easily debug the
557 problem. Don't forget to tell which version of LilyPond you use! Send
558 the report to @email{bug-lilypond@@gnu.org}.
561 @c the bug database is not up to date enough.
563 When you've found a bug, have a look at our
564 @uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if
565 it has already been reported. You could also try to do a few searches
566 on the mailing list for the bug. Sometimes the bug will have already
567 been reported and a fix or workaround is already known.
570 Here is an example of a good bug report:
573 It seems that placement of accidentals is broken. In the
574 following example, the accidental touches the note head.
576 Using Mac OSX 10.3.7, fink package lilypond-devel
587 \override Accidental #'extra-offset = #'(1.0 . 0)
593 @section Editor support
598 @cindex modes, editor
599 @cindex syntax coloring
600 @cindex coloring, syntax
602 There is support from different editors for LilyPond.
606 Emacs has a @file{lilypond-mode}, which provides keyword
607 autocompletion, indentation, LilyPond specific parenthesis matching
608 and syntax coloring, handy compile short-cuts and reading LilyPond
609 manuals using Info. If @file{lilypond-mode} is not installed on your
610 platform, then read the
612 @uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}.
615 installation instructions.
620 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
621 with syntax coloring tools. For more information, refer to the
623 @uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}.
626 installation instructions.
632 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
633 This plugin includes a DVI viewer, integrated help and viewing via
634 GhostScript. It can be installed by doing @key{Plugins > Plugin
635 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
639 All these editors can be made to jump into the input file to the source
640 of a symbol in the graphical output. See @ref{Point and click}.
644 @section File structure
646 The major part of this manual is concerned with entering various
647 forms of music in LilyPond. However, many music expressions are not
648 valid input on their own, for example, a @code{.ly} file containing
655 will result in a parsing error. Instead, music should be inside other
656 expressions, which may be put in a file by themselves. Such
657 expressions are called toplevel expressions. This section enumerates
660 A @code{.ly} file contains any number of toplevel expressions, where a
661 toplevel expression is one of the following
665 An output definition, such as @code{\paper}, @code{\midi}, and
666 @code{\layout}. Such a definition at the toplevel changes the default
667 settings for the block entered.
670 A @code{\header} block. This sets the global header block. This
671 is the block containing the definitions for book-wide settings, like
672 composer, title, etc.
675 An @code{\addquote} statement. See @ref{Quoting other voices}
676 for more information.
679 A @code{\score} block. This score will be collected with other
680 toplevel scores, and combined as a single @code{\book}.
682 This behavior can be changed by setting the variable
683 @code{toplevel-score-handler} at toplevel. The default handler is
684 defined in the init file @file{scm/@/lily@/.scm}.
687 A @code{\book} block logically combines multiple movements
688 (i.e., multiple @code{\score} blocks) in one document. A number of
689 @code{\scores} creates a single output file, where all movement are
692 This behavior can be changed by setting the variable
693 @code{toplevel-book-handler} at toplevel. The default handler is
694 defined in the init file @file{scm/@/lily@/.scm}.
697 A compound music expression, such as
702 This will add the piece in a @code{\score} and format it in a
703 single book together with all other toplevel @code{\score}s and music
706 This behavior can be changed by setting the variable
707 @code{toplevel-music-handler} at toplevel. The default handler is
708 defined in the init file @file{scm/@/lily@/.scm}.
711 A markup text, a verse for example
714 2. The first line verse two.
718 Markup texts are rendered above, between or below the scores or music
719 expressions, wherever they appear.
722 An indentifier, such as
727 This can be used later on in the file by entering @code{\foo}. The
728 name of an identifier should have alphabetic characters only; no
729 numbers, underscores or dashes.
733 The following example shows three things that may be entered at
738 % movements are non-justified by default
750 At any point in a file, any of the following lexical instructions can
754 @item @code{\version}
755 @item @code{\include}
756 @item @code{\renameinput}
760 @node Including LilyPond files
761 @section Including LilyPond files
763 @cindex @code{\include}
764 @cindex including files
766 A large project may be split up into separate files. To refer to another
770 \include "otherfile.ly"
773 For example, you may write separate files for each instrument part and
774 create a ``full score'' file which brings together the individual