1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
5 @chapter Running LilyPond
7 This chapter details the technicalities of running LilyPond.
9 Some of these commands are run from the command-line. By
10 ``command-line'', we mean the command
11 line in the operating system. Windows users
12 might be more familiar with the terms ``DOS shell'' or
13 ``command shell''; OSX users might be more familiar with the
14 terms ``terminal'' or ``console''. OSX users should also
15 consult @ref{Notes for the MacOS X app}.
18 this part of an operating system is outside the scope of this
19 manual; please consult other documentation on this topic if
20 you are unfamiliar with the command-line.
24 * Notes for the MacOS X app::
25 * Updating files with convert-ly::
32 @node Invoking lilypond
33 @section Invoking lilypond
34 @cindex Invoking LilyPond
35 @cindex command line options
36 @cindex options, command line
40 The @code{lilypond} executable may be called as follows from the command line.
43 lilypond [@var{option}]@dots{} @var{file}@dots{}
47 When invoked with a filename that has no extension, the @file{.ly}
48 extension is tried first. To read input from stdin, use a
49 dash (@code{-}) for @var{file}.
51 When @file{filename.ly} is processed it will produce
52 @file{filename.tex} as output (or @file{filename.ps} for PostScript
53 output). If @file{filename.ly} contains more than one @code{\score}
54 block, then the rest of the scores will be output in numbered files,
55 starting with @file{filename-1.tex}. Several files can be specified;
56 they will each be processed independently. @footnote{The status of
57 GUILE is not reset after processing a @code{.ly} file, so be careful
58 not to change any system defaults from within Scheme.}
61 @subsection Command line options
63 The following options are supported:
67 @item -e,--evaluate=@var{expr}
68 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
69 Multiple @code{-e} options may be given, they will be evaluated
72 The expression will be evaluated in the @code{guile-user} module, so
73 if you want to use definitions in @var{expr}, use
76 lilypond -e '(define-public a 42)'
80 on the command-line, and include
83 #(use-modules (guile-user))
87 at the top of the @code{.ly} file.
89 @item -f,--format=@var{format}
90 which formats should be written. Choices are @code{svg}, @code{ps},
91 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
93 @item -b,--backend=@var{format}
94 the output format to use for the back-end. Choices are
97 for @TeX{} output, to be processed with La@TeX{}. If present, the file
98 @file{file.textmetrics} is read to determine text extents.
100 dump text strings to @file{.texstr} file, which can be run through
101 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
102 extents of strings of text.
105 @cindex PostScript output
107 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
108 these fonts is done. When using oriental character sets, this can
112 for encapsulated PostScript. This dumps every page (system) as a separate
113 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
114 all pages (systems) including fonts.
116 This mode is used by default by lilypond-book.
119 for SVG (Scalable Vector Graphics). This dumps every page as a separate
120 @file{SVG} file, with embedded fonts.
121 @cindex SVG (Scalable Vector Graphics)
122 You need a SVG viewer which supports embedded fonts, or a SVG
123 viewer which is able to replace the embedded fonts with OTF fonts.
124 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
125 (version 0.42 or later), after copying the OTF fonts in directory
126 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
128 for a dump of the raw, internal Scheme-based drawing commands.
132 @cindex output format, setting
134 @item -d,--define-default=@var{var}=@var{val}
135 This sets the internal program option @var{var} to the Scheme value
136 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
137 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
139 @cindex point and click, command line
148 -dpoint-and-click='#f'
151 Another notable option is
154 -dpaper-size=\"letter\"
158 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
160 Setting the @code{-dhelp} option will print a summary of the options
164 Show a summary of usage.
166 @item -H,--header=FIELD
167 Dump a header field to file BASENAME.FIELD
169 @item --include, -I=@var{directory}
170 Add @var{directory} to the search path for input files.
171 @cindex file searching
174 @item -i,--init=@var{file}
175 Set init file to @var{file} (default: @file{init.ly}).
177 @item -o,--output=@var{FILE}
178 Set the default output file to @var{FILE}. The appropriate
179 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
186 Generate DVI files. In this case, the @TeX{} backend should be
187 specified, i.e., @code{-b tex}.
190 Generate pictures of each page, in PNG format. This implies
191 @code{--ps}. The resolution in DPI of the image may be set with
197 Generate PDF. This implies @code{--ps}.
200 Generate an output file containing the titles and the first system
203 Do not generate the full pages. Useful in combination with
207 Do not trust the @code{.ly} input.
209 When LilyPond formatting is available through a web server, either the
210 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
211 @code{--safe} option will prevent inline Scheme code from wreaking
218 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
223 The @code{--safe} option works by evaluating in-line Scheme
224 expressions in a special safe module. This safe module is derived from
225 GUILE @file{safe-r5rs} module, but adds a number of functions of the
226 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
228 In addition, @code{--safe} disallows @code{\include} directives and
229 disables the use of backslashes in @TeX{} strings.
231 In @code{--safe} mode, it is not possible to import LilyPond variables
234 @code{--safe} does @emph{not} detect resource overuse. It is still
235 possible to make the program hang indefinitely, for example by feeding
236 cyclic data structures into the backend. Therefore, if using LilyPond
237 on a publicly accessible webserver, the process should be limited in
238 both CPU and memory usage.
240 Note that @code{--safe} will prevent many useful LilyPond snippets from
241 being compiled. For a softer but secure alternative you can use the
242 @code{--jail} option.
245 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
246 Run LilyPond in a chroot jail.
248 The @code{--jail} option provides a more flexible alternative to
249 @code{--safe} when LilyPond formatting is available through a web
250 server or whenever LilyPond executes externally provided
253 The @code{--jail} option works by changing the root of LilyPond to
254 @var{jail} just before starting the actual compilation process. The user
255 and group are then changed to match those provided, and the current
256 directory is changed to @var{dir}. This setup guarantees that it is not
257 possible (at least in theory) to escape from the jail. Note that for
258 @code{--jail} to work LilyPond must be run as root, which is usually
259 accomplished in a safe way using @command{sudo}.
261 Setting up a jail is a slightly delicate matter, as we must be sure that
262 LilyPond is able to find whatever it needs to compile the source
263 @emph{inside the jail}. A typical setup comprises the following items:
266 @item Setting up a separate filesystem
267 A separate filesystem should be created for LilyPond, so that it can be
268 mounted with safe options such as @code{noexec}, @code{nodev}, and
269 @code{nosuid}. In this way, it is impossible to run executables or to
270 write directly to a device from LilyPond. If you do not want to create a
271 separate partition, just create a file of reasonable size and use it to
272 mount a loop device. A separate filesystem also guarantees that LilyPond
273 cannot write more space than it is allowed.
275 @item Setting up a separate user
276 A separate user and group (say, @samp{lily}/@samp{lily}) with low
277 privileges should be used to run LilyPond inside the jail. There should
278 be a single directory writable by this user, which should be passed in
281 @item Preparing the jail
282 LilyPond needs to read a number of files while running. All these files
283 are to be copied into the jail, under the same path they appear in the
284 real root filesystem. The entire content of the LilyPond installation
285 (e.g., @file{/usr/share/lilypond})
288 If problems arise, the simplest way to trace them down is to run
289 LilyPond using @command{strace}, which will allow you to determine which
292 @item Running LilyPond
293 In a jail mounted with @code{noexec} it is impossible to execute any external
294 program. Therefore LilyPond must be run with a backend that does not
295 require any such program. As we already mentioned, it must be also run
296 with superuser privileges (which, of course, it will lose immediately),
297 possibly using @command{sudo}. It is a good idea to limit the number of
298 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
299 -t}), and, if your operating system supports it, the amount of memory
300 that can be allocated.
305 Show version information.
308 Be verbose: show full paths of all files read, and give timing
312 Show the warranty with which GNU LilyPond comes. (It comes with
313 @strong{NO WARRANTY}!)
317 @subsection Environment variables
321 @cindex LILYPONDPREFIX
323 @code{Lilypond} recognizes the following environment variables:
326 This specifies a directory where locale messages and
327 data files will be looked up by default. The directory should contain
328 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
331 This selects the language for the warning messages.
333 @item LILYPOND_GC_YIELD
334 With this variable the memory footprint and performance can be
335 adjusted. It is a percentage tunes memory management behavior. With
336 higher values, the program uses more memory, with smaller values, it
337 uses more CPU time. The default value is @code{70}.
342 @node Notes for the MacOS X app
343 @section Notes for the MacOS X app
345 The scripts (such as lilypond-book, convert-ly, abc2ly, and even
346 lilypond itself) are also
347 included inside MacOS X .app. They can be run from the command line by
348 invoking them directly, e.g.
351 @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond
355 The same is true of the other scripts in that directory, including
356 lilypond-book, convert-ly, abc2ly, etc.
358 Alternatively, you may add this directory to your path. Modify (or create)
359 a file called @code{.profile} in your home directory such that it contains
362 export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin
366 This file should end with a blank line.
368 Note that @var{path/to} will generally be @code{/Applications/}.
371 @node Updating files with convert-ly
372 @section Updating with @command{convert-ly}
374 @cindex Updating a LilyPond file
377 The LilyPond input syntax is routinely changed to simplify it or improve
378 it in different ways. As a side effect of this, the LilyPond interpreter
379 often is no longer compatible with older input files. To remedy this,
380 the program @command{convert-ly} can be used to deal with most of the
381 syntax changes between LilyPond versions.
383 It uses @code{\version} statements in the input files to detect the
384 old version number. In most cases, to upgrade your input file it is
385 sufficient to run@footnote{MacOS X users may execute this command
386 under the menu entry @samp{Compile > Update syntax}.}
389 convert-ly -e myfile.ly
392 If there are no changes to myfile.ly and file called myfile.ly.NEW
393 is created, then myfile.ly is already updated.
395 @command{convert-ly} always converts up to the last syntax change handled by
396 it. This means that the @code{\version} number left in the file is
397 usually lower than the version of @command{convert-ly} itself.
399 To upgrade LilyPond fragments in texinfo files, use
402 convert-ly --from=... --to=... --no-version *.itely
405 To upgrade many files at once, combine @code{convert-ly} with
406 standard unix commands. This example will upgrade all @code{.ly}
407 files in the current directory
410 for f in *.ly; do convert-ly -e $f; done;
413 In general, the program is invoked as follows:
416 convert-ly [@var{option}]@dots{} @var{file}@dots{}
420 The following options can be given:
424 Do an inline edit of the input file. Overrides @code{--output}.
426 @item -f,--from=@var{from-patchlevel}
427 Set the version to convert from. If this is not set, @command{convert-ly}
428 will guess this, on the basis of @code{\version} strings in the file.
430 @item -n,--no-version
431 Normally, @command{convert-ly} adds a @code{\version} indicator
432 to the output. Specifying this option suppresses this.
434 @item -s, --show-rules
435 Show all known conversions and exit.
437 @item --to=@var{to-patchlevel}
438 Set the goal version of the conversion. It defaults to the latest
448 Not all language changes are handled. Only one output option can be
449 specified. Automatically updating scheme and lilypond scheme
450 interfaces is quite unlikely; be prepared to tweak scheme code
454 @c We might want to make this a completely new section, along with more
455 @c info about how to upgrade old input files. -gp
458 Copy and paste from CVS, last updated
461 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/
462 convert-ly.txt?rev=HEAD&content-type=text/plain
464 NEW: not exactly copied; this list has been modified. Since we're
465 changing the bug system, it doesn't make sense to copy from
466 the bug CVS any more. I'll figure out something else. -gp
470 There are a few things that the convert-ly cannot handle. Here's a list of
472 that the community has complained about.
474 This bug report structure has been chosen because convert-ly has a structure
476 allow to smoothly implement all needed changes. Thus this is just a wishlist,
481 Doesn't always convert figured bass correctly, specifically things like {<
482 >}. Mats' comment on working around this:
483 To be able to run convert-ly
484 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
485 and similarly I replaced '>}' with '&}'. After the conversion, I could
486 then change back from '{ #' to '{ <' and from '& }' to '> }'.
487 Doesn't convert all text markup correctly. In the old markup syntax,
488 it was possible to group a number of markup commands together within
490 -#'((bold italic) "string")
491 This will incorrectly be converted into
492 -\markup{{\bold italic} "string"}
493 instead of the correct
494 -\markup{\bold \italic "string"}
496 Doesn't handle \partcombine
497 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
500 \magnify isn't changed to \fontsize.
501 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
502 remove-tag isn't changed.
503 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
504 first-page-number isn't changed.
505 - first-page-number no => print-first-page-number = ##f
506 Line breaks in header strings aren't converted.
507 - \\\\ as line break in \header strings => \markup \center-align <
508 "First Line" "Second Line" >
509 Crescendo and decrescendo terminators aren't converted.
513 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
516 \markup{ \center-align <{ ... }> } should be converted to:
517 \markup{ \center-align {\line { ... }} }
518 but now, \line is missing.
520 Special LaTeX characters such as $~$ in text are not converted to UTF8.
522 \score{} must now begin with a music expression. Anything else
523 (particularly \header{}) must come after the music.
528 @section Reporting bugs
531 @cindex reporting bugs
533 If you have input that results in a crash or an erroneous output, then
534 that is a bug. We try to respond to bug-reports promptly, and fix them as
535 soon as possible. Help us by sending a defective input file, so we can
536 reproduce the problem. Send the report via:
539 @uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs}
545 @item Try to produce a very small input file which demonstrates the problem;
546 one or two bars is often sufficient to reproduce a bug. The smaller the
547 input file is, the easier it is for us to debug the problem.
549 @item Don't forget to tell which version of LilyPond you use!
551 @item If possible, use @code{ragged-right} in your example. This makes sure
552 that the bug can be reproduced in all paper sizes.
556 @c the bug database is not up to date enough.
558 When you've found a bug, have a look at our
559 @uref{http://@/lilypond@/.org/@/bugs/@/v2.8/@/,bug database} to see if
560 it has already been reported. You could also try to do a few searches
561 on the mailing list for the bug. Sometimes the bug will have already
562 been reported and a fix or workaround is already known.
565 Here is an example of a good bug report:
568 It seems that placement of accidentals is broken. In the
569 following example, the accidental touches the note head.
571 Using Mac OSX 10.3.7, lilypond 2.7.32
574 \layout { ragged-right = ##t }
581 \layout { ragged-right = ##t }
583 \override Accidental #'extra-offset = #'(1.0 . 0)
589 @section Error messages
591 @cindex error messages
592 Different error messages can appear while compiling a file:
598 Something looks suspect. If you are requesting something out of the
599 ordinary then you will understand the message, and can ignore it.
600 However, warnings usually indicate that something is wrong with the
604 Something is definitely wrong. The current processing step (parsing,
605 interpreting, or formatting) will be finished, but the next step will
611 Something is definitely wrong, and LilyPond cannot continue. This
612 happens rarely. The most usual cause is misinstalled fonts.
614 @cindex trace, Scheme
618 Errors that occur while executing Scheme code are caught by the Scheme
619 interpreter. If running with the verbose option (@code{-V} or
620 @code{--verbose}) then a call trace of the offending
621 function call is printed.
623 @cindex Programming error
624 @item Programming error
625 There was some internal inconsistency. These error messages are
626 intended to help the programmers and debuggers. Usually, they can be
627 ignored. Sometimes, they come in such big quantities that they obscure
628 other output. In this case, file a bug-report.
630 @item Aborted (core dumped)
631 This signals a serious programming error that caused the program to
632 crash. Such errors are considered critical. If you stumble on one,
638 @cindex errors, message format
639 If warnings and errors can
640 be linked to some part of the input file, then error messages have the
644 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
645 @var{offending input line}
648 A line-break is inserted in the offending line to indicate the column
649 where the error was found. For example,
652 test.ly:2:19: error: not a duration: 5:
657 These locations are LilyPond's best guess about where the warning or
658 error occurred, but (by their very nature) warnings and errors occur
659 when something unexpected happens. If you can't see an error in the
660 indicated line of your input file, try checking one or two lines
661 above the indicated position.
665 @section Editor support
670 @cindex modes, editor
671 @cindex syntax coloring
672 @cindex coloring, syntax
674 There is support from different editors for LilyPond.
678 Emacs has a @file{lilypond-mode}, which provides keyword
679 autocompletion, indentation, LilyPond specific parenthesis matching
680 and syntax coloring, handy compile short-cuts and reading LilyPond
681 manuals using Info. If @file{lilypond-mode} is not installed on your
682 platform, then read the
684 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
687 installation instructions.
692 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
693 with syntax coloring tools. For more information, refer to the
695 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
698 installation instructions.
704 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
705 This plugin includes a DVI viewer, integrated help and viewing via
706 GhostScript. It can be installed by doing @key{Plugins > Plugin
707 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
711 All these editors can be made to jump into the input file to the source
712 of a symbol in the graphical output. See @ref{Point and click}.
715 @node Point and click
716 @section Point and click
717 @cindex point and click
720 Point and click lets you find notes in the input by clicking on them
721 in the PDF viewer. This makes it easier to find input that causes
722 some error in the sheet music.
724 When this functionality is active, LilyPond adds hyperlinks to the PDF
725 file. These hyperlinks are sent to the web-browser, which opens a
726 text-editor with the cursor in the right place.
728 To make this chain work, you should configure your PDF viewer to
729 follow hyperlinks using the @file{lilypond-invoke-editor} script
730 supplied with LilyPond.
732 For Xpdf on Unix, the following should be present in
733 @file{xpdfrc}@footnote{On unix, this file is found either in
734 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
737 urlCommand "lilypond-invoke-editor %s"
740 The program @file{lilypond-invoke-editor} is a small helper
741 program. It will invoke an editor for the special @code{textedit}
742 URIs, and run a web browser for others. It tests the environment
743 variable @code{EDITOR} for the following patterns,
749 emacsclient --no-wait +@var{line}:@var{column} @var{file}
754 gvim --remote +:@var{line}:norm@var{char} @var{file}
760 nc -noask +@var{line} @var{file}'
764 The environment variable @code{LYEDITOR} is used to override this. It
765 contains the command line to start the editor, where @code{%(file)s},
766 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
767 and line respectively. The setting
770 emacsclient --no-wait +%(line)s:%(column)s %(file)s
774 for @code{LYEDITOR} is equivalent to the standard emacsclient
778 @cindex file size, output
780 The point and click links enlarge the output files significantly. For
781 reducing the size of PDF and PS files, point and click may be switched
785 #(ly:set-option 'point-and-click #f)
789 in a @file{.ly} file. Alternately, you may pass this as an command-line
793 lilypond -dno-point-and-click file.ly