1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
11 @node Running LilyPond
12 @chapter Running LilyPond
14 This chapter details the technicalities of running LilyPond.
16 Some of these commands are run from the command-line. By
17 @q{command-line}, we mean the command
18 line in the operating system. Windows users
19 might be more familiar with the terms @q{DOS shell} or
20 @q{command shell}; OSX users might be more familiar with the
21 terms @q{terminal} or @q{console}. OSX users should also
22 consult @ref{Notes for the MacOS X app}.
25 this part of an operating system is outside the scope of this
26 manual; please consult other documentation on this topic if
27 you are unfamiliar with the command-line.
31 * Notes for the MacOS X app::
32 * Updating files with convert-ly::
39 @node Invoking lilypond
40 @section Invoking lilypond
41 @cindex Invoking LilyPond
42 @cindex command line options
43 @cindex options, command line
47 The @code{lilypond} executable may be called as follows from the command line.
50 lilypond [@var{option}]@dots{} @var{file}@dots{}
54 When invoked with a filename that has no extension, the @file{.ly}
55 extension is tried first. To read input from stdin, use a
56 dash (@code{-}) for @var{file}.
58 When @file{filename.ly} is processed it will produce
59 @file{filename.tex} as output (or @file{filename.ps} for PostScript
60 output). If @file{filename.ly} contains more than one @code{\score}
61 block, then the rest of the scores will be output in numbered files,
62 starting with @file{filename-1.tex}. Several files can be specified;
63 they will each be processed independently. @footnote{The status of
64 GUILE is not reset after processing a @code{.ly} file, so be careful
65 not to change any system defaults from within Scheme.}
68 @subsection Command line options
70 The following options are supported:
74 @item -e,--evaluate=@var{expr}
75 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
76 Multiple @code{-e} options may be given, they will be evaluated
79 The expression will be evaluated in the @code{guile-user} module, so
80 if you want to use definitions in @var{expr}, use
83 lilypond -e '(define-public a 42)'
87 on the command-line, and include
90 #(use-modules (guile-user))
94 at the top of the @code{.ly} file.
96 @item -f,--format=@var{format}
97 which formats should be written. Choices are @code{svg}, @code{ps},
98 @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
100 @item -b,--backend=@var{format}
101 the output format to use for the back-end. Choices are
104 for @TeX{} output, to be processed with La@TeX{}. If present, the file
105 @file{file.textmetrics} is read to determine text extents.
107 dump text strings to @file{.texstr} file, which can be run through
108 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
109 extents of strings of text. @strong{Warning:} this functionality is
110 currently missing due to heavy restructuring of the source code.
113 @cindex PostScript output
115 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
116 these fonts is done. When using oriental character sets, this can
120 for encapsulated PostScript. This dumps every page (system) as a separate
121 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
122 all pages (systems) including fonts.
124 This mode is used by default by lilypond-book.
127 for SVG (Scalable Vector Graphics). This dumps every page as a separate
128 @file{SVG} file, with embedded fonts.
129 @cindex SVG (Scalable Vector Graphics)
130 You need a SVG viewer which supports embedded fonts, or a SVG
131 viewer which is able to replace the embedded fonts with OTF fonts.
132 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
133 (version 0.42 or later), after copying the OTF fonts in directory
134 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
136 for a dump of the raw, internal Scheme-based drawing commands.
140 @cindex output format, setting
142 @item -d,--define-default=@var{var}=@var{val}
143 This sets the internal program option @var{var} to the Scheme value
144 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
145 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
147 @cindex point and click, command line
156 -dpoint-and-click='#f'
159 Another notable option is
162 -dpaper-size=\"letter\"
166 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
168 Setting the @code{-dhelp} option will print a summary of the options
172 Show a summary of usage.
174 @item -H,--header=FIELD
175 Dump a header field to file BASENAME.FIELD
177 @item --include, -I=@var{directory}
178 Add @var{directory} to the search path for input files.
179 @cindex file searching
182 @item -i,--init=@var{file}
183 Set init file to @var{file} (default: @file{init.ly}).
185 @item -o,--output=@var{FILE}
186 Set the default output file to @var{FILE}. The appropriate
187 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
194 Generate DVI files. In this case, the @TeX{} backend should be
195 specified, i.e., @code{-b tex}.
198 Generate pictures of each page, in PNG format. This implies
199 @code{--ps}. The resolution in DPI of the image may be set with
205 Generate PDF. This implies @code{--ps}.
208 Generate an output file containing the titles and the first system
211 Do not generate the full pages. Useful in combination with
215 Do not trust the @code{.ly} input.
217 When LilyPond formatting is available through a web server, either the
218 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
219 @code{--safe} option will prevent inline Scheme code from wreaking
226 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
231 The @code{--safe} option works by evaluating in-line Scheme
232 expressions in a special safe module. This safe module is derived from
233 GUILE @file{safe-r5rs} module, but adds a number of functions of the
234 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
236 In addition, @code{--safe} disallows @code{\include} directives and
237 disables the use of backslashes in @TeX{} strings.
239 In @code{--safe} mode, it is not possible to import LilyPond variables
242 @code{--safe} does @emph{not} detect resource overuse. It is still
243 possible to make the program hang indefinitely, for example by feeding
244 cyclic data structures into the backend. Therefore, if using LilyPond
245 on a publicly accessible webserver, the process should be limited in
246 both CPU and memory usage.
248 Note that @code{--safe} will prevent many useful LilyPond snippets from
249 being compiled. For a softer but secure alternative you can use the
250 @code{--jail} option.
253 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
254 Run LilyPond in a chroot jail.
256 The @code{--jail} option provides a more flexible alternative to
257 @code{--safe} when LilyPond formatting is available through a web
258 server or whenever LilyPond executes externally provided
261 The @code{--jail} option works by changing the root of LilyPond to
262 @var{jail} just before starting the actual compilation process. The user
263 and group are then changed to match those provided, and the current
264 directory is changed to @var{dir}. This setup guarantees that it is not
265 possible (at least in theory) to escape from the jail. Note that for
266 @code{--jail} to work LilyPond must be run as root, which is usually
267 accomplished in a safe way using @command{sudo}.
269 Setting up a jail is a slightly delicate matter, as we must be sure that
270 LilyPond is able to find whatever it needs to compile the source
271 @emph{inside the jail}. A typical setup comprises the following items:
274 @item Setting up a separate filesystem
275 A separate filesystem should be created for LilyPond, so that it can be
276 mounted with safe options such as @code{noexec}, @code{nodev}, and
277 @code{nosuid}. In this way, it is impossible to run executables or to
278 write directly to a device from LilyPond. If you do not want to create a
279 separate partition, just create a file of reasonable size and use it to
280 mount a loop device. A separate filesystem also guarantees that LilyPond
281 cannot write more space than it is allowed.
283 @item Setting up a separate user
284 A separate user and group (say, @samp{lily}/@samp{lily}) with low
285 privileges should be used to run LilyPond inside the jail. There should
286 be a single directory writable by this user, which should be passed in
289 @item Preparing the jail
290 LilyPond needs to read a number of files while running. All these files
291 are to be copied into the jail, under the same path they appear in the
292 real root filesystem. The entire content of the LilyPond installation
293 (e.g., @file{/usr/share/lilypond})
296 If problems arise, the simplest way to trace them down is to run
297 LilyPond using @command{strace}, which will allow you to determine which
300 @item Running LilyPond
301 In a jail mounted with @code{noexec} it is impossible to execute any external
302 program. Therefore LilyPond must be run with a backend that does not
303 require any such program. As we already mentioned, it must be also run
304 with superuser privileges (which, of course, it will lose immediately),
305 possibly using @command{sudo}. It is a good idea to limit the number of
306 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
307 -t}), and, if your operating system supports it, the amount of memory
308 that can be allocated.
313 Show version information.
316 Be verbose: show full paths of all files read, and give timing
320 Show the warranty with which GNU LilyPond comes. (It comes with
321 @strong{NO WARRANTY}!)
325 @subsection Environment variables
329 @cindex LILYPONDPREFIX
331 @code{Lilypond} recognizes the following environment variables:
334 This specifies a directory where locale messages and
335 data files will be looked up by default. The directory should contain
336 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
339 This selects the language for the warning messages.
341 @item LILYPOND_GC_YIELD
342 With this variable the memory footprint and performance can be
343 adjusted. It is a percentage tunes memory management behavior. With
344 higher values, the program uses more memory, with smaller values, it
345 uses more CPU time. The default value is @code{70}.
350 @node Notes for the MacOS X app
351 @section Notes for the MacOS X app
353 The scripts (such as lilypond-book, convert-ly, abc2ly, and even
354 lilypond itself) are also
355 included inside MacOS X .app. They can be run from the command line by
356 invoking them directly, e.g.
359 @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond
363 The same is true of the other scripts in that directory, including
364 lilypond-book, convert-ly, abc2ly, etc.
366 Alternatively, you may create scripts which add the path
367 automatically. Create a directory to store these scripts,
374 Create a file called @code{lilypond} which contains
377 exec @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond "$@"
380 Create similar files @code{lilypond-book}, @code{convert-ly}, and
381 any other helper programs you use (@code{abc2ly}, @code{midi2ly},
382 etc). Simply replace the @code{bin/lilypond} with
383 @code{bin/convert-ly} (or other program name) in the above file.
385 Make the file executable,
391 Now, add this directory to your path. Modify (or create)
392 a file called @code{.profile} in your home directory such that it contains
395 export PATH=$PATH:~/bin
399 This file should end with a blank line.
401 Note that @var{path/to} will generally be @code{/Applications/}.
404 @node Updating files with convert-ly
405 @section Updating with @command{convert-ly}
407 @cindex Updating a LilyPond file
410 The LilyPond input syntax is routinely changed to simplify it or improve
411 it in different ways. As a side effect of this, the LilyPond interpreter
412 often is no longer compatible with older input files. To remedy this,
413 the program @command{convert-ly} can be used to deal with most of the
414 syntax changes between LilyPond versions.
416 It uses @code{\version} statements in the input files to detect the
417 old version number. In most cases, to upgrade your input file it is
418 sufficient to run@footnote{MacOS X users may execute this command
419 under the menu entry @samp{Compile > Update syntax}.}
422 convert-ly -e myfile.ly
425 If there are no changes to myfile.ly and file called myfile.ly.NEW
426 is created, then myfile.ly is already updated.
428 @command{convert-ly} always converts up to the last syntax change handled by
429 it. This means that the @code{\version} number left in the file is
430 usually lower than the version of @command{convert-ly} itself.
432 To upgrade LilyPond fragments in texinfo files, use
435 convert-ly --from=... --to=... --no-version *.itely
438 To upgrade many files at once, combine @code{convert-ly} with
439 standard unix commands. This example will upgrade all @code{.ly}
440 files in the current directory
443 for f in *.ly; do convert-ly -e $f; done;
446 In general, the program is invoked as follows:
449 convert-ly [@var{option}]@dots{} @var{file}@dots{}
453 The following options can be given:
457 Do an inline edit of the input file. Overrides @code{--output}.
459 @item -f,--from=@var{from-patchlevel}
460 Set the version to convert from. If this is not set, @command{convert-ly}
461 will guess this, on the basis of @code{\version} strings in the file.
463 @item -n,--no-version
464 Normally, @command{convert-ly} adds a @code{\version} indicator
465 to the output. Specifying this option suppresses this.
467 @item -s, --show-rules
468 Show all known conversions and exit.
470 @item --to=@var{to-patchlevel}
471 Set the goal version of the conversion. It defaults to the latest
481 Not all language changes are handled. Only one output option can be
482 specified. Automatically updating scheme and lilypond scheme
483 interfaces is quite unlikely; be prepared to tweak scheme code
487 @c We might want to make this a completely new section, along with more
488 @c info about how to upgrade old input files. -gp
491 Copy and paste from CVS, last updated
494 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/
495 convert-ly.txt?rev=HEAD&content-type=text/plain
497 NEW: not exactly copied; this list has been modified. Since we're
498 changing the bug system, it doesn't make sense to copy from
499 the bug CVS any more. I'll figure out something else. -gp
503 There are a few things that the convert-ly cannot handle. Here's a list of
505 that the community has complained about.
507 This bug report structure has been chosen because convert-ly has a structure
509 allow to smoothly implement all needed changes. Thus this is just a wishlist,
514 Doesn't always convert figured bass correctly, specifically things like {<
515 >}. Mats' comment on working around this:
516 To be able to run convert-ly
517 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
518 and similarly I replaced '>}' with '&}'. After the conversion, I could
519 then change back from '{ #' to '{ <' and from '& }' to '> }'.
520 Doesn't convert all text markup correctly. In the old markup syntax,
521 it was possible to group a number of markup commands together within
523 -#'((bold italic) "string")
524 This will incorrectly be converted into
525 -\markup{{\bold italic} "string"}
526 instead of the correct
527 -\markup{\bold \italic "string"}
529 Doesn't handle \partcombine
530 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
533 \magnify isn't changed to \fontsize.
534 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
535 remove-tag isn't changed.
536 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
537 first-page-number isn't changed.
538 - first-page-number no => print-first-page-number = ##f
539 Line breaks in header strings aren't converted.
540 - \\\\ as line break in \header strings => \markup \center-align <
541 "First Line" "Second Line" >
542 Crescendo and decrescendo terminators aren't converted.
546 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
549 \markup{ \center-align <{ ... }> } should be converted to:
550 \markup{ \center-align {\line { ... }} }
551 but now, \line is missing.
553 Special LaTeX characters such as $~$ in text are not converted to UTF8.
555 \score{} must now begin with a music expression. Anything else
556 (particularly \header{}) must come after the music.
561 @section Reporting bugs
564 @cindex reporting bugs
566 If you have input that results in a crash or an erroneous output, then
567 that is a bug. There is a list of current bugs on our google bug tracker,
569 @uref{http://code.google.com/p/lilypond/issues/list}
571 If you have discovered a bug which is not listed, please report the
572 bug by following the directions on
574 @uref{http://lilypond.org/web/devel/participating/bugs}
578 @section Error messages
580 @cindex error messages
581 Different error messages can appear while compiling a file:
587 Something looks suspect. If you are requesting something out of the
588 ordinary then you will understand the message, and can ignore it.
589 However, warnings usually indicate that something is wrong with the
593 Something is definitely wrong. The current processing step (parsing,
594 interpreting, or formatting) will be finished, but the next step will
600 Something is definitely wrong, and LilyPond cannot continue. This
601 happens rarely. The most usual cause is misinstalled fonts.
603 @cindex trace, Scheme
607 Errors that occur while executing Scheme code are caught by the Scheme
608 interpreter. If running with the verbose option (@code{-V} or
609 @code{--verbose}) then a call trace of the offending
610 function call is printed.
612 @cindex Programming error
613 @item Programming error
614 There was some internal inconsistency. These error messages are
615 intended to help the programmers and debuggers. Usually, they can be
616 ignored. Sometimes, they come in such big quantities that they obscure
617 other output. In this case, file a bug-report.
619 @item Aborted (core dumped)
620 This signals a serious programming error that caused the program to
621 crash. Such errors are considered critical. If you stumble on one,
627 @cindex errors, message format
628 If warnings and errors can
629 be linked to some part of the input file, then error messages have the
633 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
634 @var{offending input line}
637 A line-break is inserted in the offending line to indicate the column
638 where the error was found. For example,
641 test.ly:2:19: error: not a duration: 5:
646 These locations are LilyPond's best guess about where the warning or
647 error occurred, but (by their very nature) warnings and errors occur
648 when something unexpected happens. If you can't see an error in the
649 indicated line of your input file, try checking one or two lines
650 above the indicated position.
654 @section Editor support
659 @cindex modes, editor
660 @cindex syntax coloring
661 @cindex coloring, syntax
663 There is support from different editors for LilyPond.
667 Emacs has a @file{lilypond-mode}, which provides keyword
668 autocompletion, indentation, LilyPond specific parenthesis matching
669 and syntax coloring, handy compile short-cuts and reading LilyPond
670 manuals using Info. If @file{lilypond-mode} is not installed on your
671 platform, then read the
673 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
676 installation instructions.
681 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
682 with syntax coloring tools. For more information, refer to the
684 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
687 installation instructions.
693 The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
694 This plugin includes a DVI viewer, integrated help and viewing via
695 GhostScript. It can be installed by doing @key{Plugins > Plugin
696 Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
700 All these editors can be made to jump into the input file to the source
701 of a symbol in the graphical output. See @ref{Point and click}.
704 @node Point and click
705 @section Point and click
706 @cindex point and click
709 Point and click lets you find notes in the input by clicking on them
710 in the PDF viewer. This makes it easier to find input that causes
711 some error in the sheet music.
713 When this functionality is active, LilyPond adds hyperlinks to the PDF
714 file. These hyperlinks are sent to the web-browser, which opens a
715 text-editor with the cursor in the right place.
717 To make this chain work, you should configure your PDF viewer to
718 follow hyperlinks using the @file{lilypond-invoke-editor} script
719 supplied with LilyPond.
721 For Xpdf on Unix, the following should be present in
722 @file{xpdfrc}@footnote{On unix, this file is found either in
723 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
726 urlCommand "lilypond-invoke-editor %s"
729 The program @file{lilypond-invoke-editor} is a small helper
730 program. It will invoke an editor for the special @code{textedit}
731 URIs, and run a web browser for others. It tests the environment
732 variable @code{EDITOR} for the following patterns,
738 emacsclient --no-wait +@var{line}:@var{column} @var{file}
743 gvim --remote +:@var{line}:norm@var{char} @var{file}
749 nc -noask +@var{line} @var{file}'
753 The environment variable @code{LYEDITOR} is used to override this. It
754 contains the command line to start the editor, where @code{%(file)s},
755 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
756 and line respectively. The setting
759 emacsclient --no-wait +%(line)s:%(column)s %(file)s
763 for @code{LYEDITOR} is equivalent to the standard emacsclient
767 @cindex file size, output
769 The point and click links enlarge the output files significantly. For
770 reducing the size of PDF and PS files, point and click may be switched
774 #(ly:set-option 'point-and-click #f)
778 in a @file{.ly} file. Alternately, you may pass this as an command-line
782 lilypond -dno-point-and-click file.ly