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 for @code{format} are
98 @code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
100 Example: @code{lilypond -fpng filename.ly}
102 @item -b,--backend=@var{format}
103 the output format to use for the back-end. Choices for @code{format} are
106 for @TeX{} output, to be processed with La@TeX{}. If present, the file
107 @file{file.textmetrics} is read to determine text extents.
109 dump text strings to @file{.texstr} file, which can be run through
110 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
111 extents of strings of text. @strong{Warning:} this functionality is
112 currently missing due to heavy restructuring of the source code.
115 @cindex PostScript output
117 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
118 these fonts is done. When using oriental character sets, this can
122 for encapsulated PostScript. This dumps every page (system) as a separate
123 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
124 all pages (systems) including fonts.
126 This mode is used by default by lilypond-book.
129 for SVG (Scalable Vector Graphics). This dumps every page as a separate
130 @file{SVG} file, with embedded fonts.
131 @cindex SVG (Scalable Vector Graphics)
132 You need a SVG viewer which supports embedded fonts, or a SVG
133 viewer which is able to replace the embedded fonts with OTF fonts.
134 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
135 (version 0.42 or later), after copying the OTF fonts in directory
136 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
138 for a dump of the raw, internal Scheme-based drawing commands.
142 Example: @code{lilypond -bsvg filename.ly}
144 @cindex output format, setting
146 @item -d,--define-default=@var{var}=@var{val}
147 This sets the internal program option @var{var} to the Scheme value
148 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
149 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
151 @cindex point and click, command line
160 -dpoint-and-click='#f'
163 Another notable option is
166 -dpaper-size=\"letter\"
170 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
172 Setting the @code{-dhelp} option will print a summary of the options
176 Show a summary of usage.
178 @item -H,--header=FIELD
179 Dump a header field to file BASENAME.FIELD
181 @item --include, -I=@var{directory}
182 Add @var{directory} to the search path for input files.
183 @cindex file searching
186 @item -i,--init=@var{file}
187 Set init file to @var{file} (default: @file{init.ly}).
189 @item -o,--output=@var{FILE}
190 Set the default output file to @var{FILE}. The appropriate
191 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
198 Generate DVI files. In this case, the @TeX{} backend should be
199 specified, i.e., @code{-b tex}.
202 Generate pictures of each page, in PNG format. This implies
203 @code{--ps}. The resolution in DPI of the image may be set with
209 Generate PDF. This implies @code{--ps}.
212 Generate an output file containing the titles and the first system
215 Do not generate the full pages. Useful in combination with
219 Do not trust the @code{.ly} input.
221 When LilyPond formatting is available through a web server, either the
222 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
223 @code{--safe} option will prevent inline Scheme code from wreaking
230 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
235 The @code{--safe} option works by evaluating in-line Scheme
236 expressions in a special safe module. This safe module is derived from
237 GUILE @file{safe-r5rs} module, but adds a number of functions of the
238 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
240 In addition, @code{--safe} disallows @code{\include} directives and
241 disables the use of backslashes in @TeX{} strings.
243 In @code{--safe} mode, it is not possible to import LilyPond variables
246 @code{--safe} does @emph{not} detect resource overuse. It is still
247 possible to make the program hang indefinitely, for example by feeding
248 cyclic data structures into the backend. Therefore, if using LilyPond
249 on a publicly accessible webserver, the process should be limited in
250 both CPU and memory usage.
252 Note that @code{--safe} will prevent many useful LilyPond snippets from
253 being compiled. For a softer but secure alternative you can use the
254 @code{--jail} option.
257 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
258 Run LilyPond in a chroot jail.
260 The @code{--jail} option provides a more flexible alternative to
261 @code{--safe} when LilyPond formatting is available through a web
262 server or whenever LilyPond executes externally provided
265 The @code{--jail} option works by changing the root of LilyPond to
266 @var{jail} just before starting the actual compilation process. The user
267 and group are then changed to match those provided, and the current
268 directory is changed to @var{dir}. This setup guarantees that it is not
269 possible (at least in theory) to escape from the jail. Note that for
270 @code{--jail} to work LilyPond must be run as root, which is usually
271 accomplished in a safe way using @command{sudo}.
273 Setting up a jail is a slightly delicate matter, as we must be sure that
274 LilyPond is able to find whatever it needs to compile the source
275 @emph{inside the jail}. A typical setup comprises the following items:
278 @item Setting up a separate filesystem
279 A separate filesystem should be created for LilyPond, so that it can be
280 mounted with safe options such as @code{noexec}, @code{nodev}, and
281 @code{nosuid}. In this way, it is impossible to run executables or to
282 write directly to a device from LilyPond. If you do not want to create a
283 separate partition, just create a file of reasonable size and use it to
284 mount a loop device. A separate filesystem also guarantees that LilyPond
285 cannot write more space than it is allowed.
287 @item Setting up a separate user
288 A separate user and group (say, @samp{lily}/@samp{lily}) with low
289 privileges should be used to run LilyPond inside the jail. There should
290 be a single directory writable by this user, which should be passed in
293 @item Preparing the jail
294 LilyPond needs to read a number of files while running. All these files
295 are to be copied into the jail, under the same path they appear in the
296 real root filesystem. The entire content of the LilyPond installation
297 (e.g., @file{/usr/share/lilypond})
300 If problems arise, the simplest way to trace them down is to run
301 LilyPond using @command{strace}, which will allow you to determine which
304 @item Running LilyPond
305 In a jail mounted with @code{noexec} it is impossible to execute any external
306 program. Therefore LilyPond must be run with a backend that does not
307 require any such program. As we already mentioned, it must be also run
308 with superuser privileges (which, of course, it will lose immediately),
309 possibly using @command{sudo}. It is a good idea to limit the number of
310 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
311 -t}), and, if your operating system supports it, the amount of memory
312 that can be allocated.
317 Show version information.
320 Be verbose: show full paths of all files read, and give timing
324 Show the warranty with which GNU LilyPond comes. (It comes with
325 @strong{NO WARRANTY}!)
329 @subsection Environment variables
333 @cindex LILYPONDPREFIX
335 @code{Lilypond} recognizes the following environment variables:
338 This specifies a directory where locale messages and
339 data files will be looked up by default. The directory should contain
340 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
343 This selects the language for the warning messages.
345 @item LILYPOND_GC_YIELD
346 With this variable the memory footprint and performance can be
347 adjusted. It is a percentage tunes memory management behavior. With
348 higher values, the program uses more memory, with smaller values, it
349 uses more CPU time. The default value is @code{70}.
354 @node Notes for the MacOS X app
355 @section Notes for the MacOS X app
357 The scripts (such as lilypond-book, convert-ly, abc2ly, and even
358 lilypond itself) are also
359 included inside MacOS X .app. They can be run from the command line by
360 invoking them directly, e.g.
363 @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond
367 The same is true of the other scripts in that directory, including
368 lilypond-book, convert-ly, abc2ly, etc.
370 Alternatively, you may create scripts which add the path
371 automatically. Create a directory to store these scripts,
378 Create a file called @code{lilypond} which contains
381 exec @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond "$@@"
384 Create similar files @code{lilypond-book}, @code{convert-ly}, and
385 any other helper programs you use (@code{abc2ly}, @code{midi2ly},
386 etc). Simply replace the @code{bin/lilypond} with
387 @code{bin/convert-ly} (or other program name) in the above file.
389 Make the file executable,
395 Now, add this directory to your path. Modify (or create)
396 a file called @code{.profile} in your home directory such that it contains
399 export PATH=$PATH:~/bin
403 This file should end with a blank line.
405 Note that @var{path/to} will generally be @code{/Applications/}.
408 @node Updating files with convert-ly
409 @section Updating with @command{convert-ly}
411 @cindex Updating a LilyPond file
414 The LilyPond input syntax is routinely changed to simplify it or improve
415 it in different ways. As a side effect of this, the LilyPond interpreter
416 often is no longer compatible with older input files. To remedy this,
417 the program @command{convert-ly} can be used to deal with most of the
418 syntax changes between LilyPond versions.
420 It uses @code{\version} statements in the input files to detect the
421 old version number. In most cases, to upgrade your input file it is
422 sufficient to run@footnote{MacOS X users may execute this command
423 under the menu entry @samp{Compile > Update syntax}.}
426 convert-ly -e myfile.ly
429 If there are no changes to myfile.ly and file called myfile.ly.NEW
430 is created, then myfile.ly is already updated.
432 @command{convert-ly} always converts up to the last syntax change handled by
433 it. This means that the @code{\version} number left in the file is
434 usually lower than the version of @command{convert-ly} itself.
436 To upgrade LilyPond fragments in texinfo files, use
439 convert-ly --from=... --to=... --no-version *.itely
442 To upgrade many files at once, combine @code{convert-ly} with
443 standard unix commands. This example will upgrade all @code{.ly}
444 files in the current directory
447 for f in *.ly; do convert-ly -e $f; done;
450 In general, the program is invoked as follows:
453 convert-ly [@var{option}]@dots{} @var{file}@dots{}
457 The following options can be given:
461 Do an inline edit of the input file. Overrides @code{--output}.
463 @item -f,--from=@var{from-patchlevel}
464 Set the version to convert from. If this is not set, @command{convert-ly}
465 will guess this, on the basis of @code{\version} strings in the file.
467 @item -n,--no-version
468 Normally, @command{convert-ly} adds a @code{\version} indicator
469 to the output. Specifying this option suppresses this.
471 @item -s, --show-rules
472 Show all known conversions and exit.
474 @item --to=@var{to-patchlevel}
475 Set the goal version of the conversion. It defaults to the latest
485 Not all language changes are handled. Only one output option can be
486 specified. Automatically updating scheme and lilypond scheme
487 interfaces is quite unlikely; be prepared to tweak scheme code
491 @c We might want to make this a completely new section, along with more
492 @c info about how to upgrade old input files. -gp
495 Copy and paste from CVS, last updated
498 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/
499 convert-ly.txt?rev=HEAD&content-type=text/plain
501 NEW: not exactly copied; this list has been modified. Since we're
502 changing the bug system, it doesn't make sense to copy from
503 the bug CVS any more. I'll figure out something else. -gp
507 There are a few things that the convert-ly cannot handle. Here's a list of
509 that the community has complained about.
511 This bug report structure has been chosen because convert-ly has a structure
513 allow to smoothly implement all needed changes. Thus this is just a wishlist,
518 Doesn't always convert figured bass correctly, specifically things like {<
519 >}. Mats' comment on working around this:
520 To be able to run convert-ly
521 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
522 and similarly I replaced '>}' with '&}'. After the conversion, I could
523 then change back from '{ #' to '{ <' and from '& }' to '> }'.
524 Doesn't convert all text markup correctly. In the old markup syntax,
525 it was possible to group a number of markup commands together within
527 -#'((bold italic) "string")
528 This will incorrectly be converted into
529 -\markup{{\bold italic} "string"}
530 instead of the correct
531 -\markup{\bold \italic "string"}
533 Doesn't handle \partcombine
534 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
537 \magnify isn't changed to \fontsize.
538 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
539 remove-tag isn't changed.
540 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
541 first-page-number isn't changed.
542 - first-page-number no => print-first-page-number = ##f
543 Line breaks in header strings aren't converted.
544 - \\\\ as line break in \header strings => \markup \center-align <
545 "First Line" "Second Line" >
546 Crescendo and decrescendo terminators aren't converted.
550 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
553 \markup{ \center-align <{ ... }> } should be converted to:
554 \markup{ \center-align {\line { ... }} }
555 but now, \line is missing.
557 Special LaTeX characters such as $~$ in text are not converted to UTF8.
559 \score{} must now begin with a music expression. Anything else
560 (particularly \header{}) must come after the music.
565 @section Reporting bugs
568 @cindex reporting bugs
570 If you have input that results in a crash or an erroneous output, then
571 that is a bug. There is a list of current bugs on our google bug tracker,
573 @uref{http://code.google.com/p/lilypond/issues/list}
575 If you have discovered a bug which is not listed, please report the
576 bug by following the directions on
578 @uref{http://lilypond.org/web/devel/participating/bugs}
580 Please construct submit @ref{Minimal examples} of bug reports. We do not
581 have the resources to investigate reports which are not as small as possible.
585 @section Error messages
587 @cindex error messages
588 Different error messages can appear while compiling a file:
594 Something looks suspect. If you are requesting something out of the
595 ordinary then you will understand the message, and can ignore it.
596 However, warnings usually indicate that something is wrong with the
600 Something is definitely wrong. The current processing step (parsing,
601 interpreting, or formatting) will be finished, but the next step will
607 Something is definitely wrong, and LilyPond cannot continue. This
608 happens rarely. The most usual cause is misinstalled fonts.
610 @cindex trace, Scheme
614 Errors that occur while executing Scheme code are caught by the Scheme
615 interpreter. If running with the verbose option (@code{-V} or
616 @code{--verbose}) then a call trace of the offending
617 function call is printed.
619 @cindex Programming error
620 @item Programming error
621 There was some internal inconsistency. These error messages are
622 intended to help the programmers and debuggers. Usually, they can be
623 ignored. Sometimes, they come in such big quantities that they obscure
624 other output. In this case, file a bug-report.
626 @item Aborted (core dumped)
627 This signals a serious programming error that caused the program to
628 crash. Such errors are considered critical. If you stumble on one,
634 @cindex errors, message format
635 If warnings and errors can
636 be linked to some part of the input file, then error messages have the
640 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
641 @var{offending input line}
644 A line-break is inserted in the offending line to indicate the column
645 where the error was found. For example,
648 test.ly:2:19: error: not a duration: 5:
653 These locations are LilyPond's best guess about where the warning or
654 error occurred, but (by their very nature) warnings and errors occur
655 when something unexpected happens. If you can't see an error in the
656 indicated line of your input file, try checking one or two lines
657 above the indicated position.
661 @section Editor support
666 @cindex modes, editor
667 @cindex syntax coloring
668 @cindex coloring, syntax
670 There is support from different editors for LilyPond.
674 Emacs has a @file{lilypond-mode}, which provides keyword
675 autocompletion, indentation, LilyPond specific parenthesis matching
676 and syntax coloring, handy compile short-cuts and reading LilyPond
677 manuals using Info. If @file{lilypond-mode} is not installed on your
678 platform, then read the
680 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
683 installation instructions.
688 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
689 with syntax coloring tools. For more information, refer to the
691 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
694 installation instructions.
700 Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit} text
701 editor, LilyPondTool is the most feature-rich text-based tool for editing
702 LilyPond scores. Its features include a Document Wizard with lyrics
703 support to set up documents easier, and embedded PDF viewer with advanced
704 point-and-click support. For screenshots, demos and installation
705 instructions, visit @uref{http://lilypondtool@/.organum@/.hu}
709 All these editors can be made to jump into the input file to the source
710 of a symbol in the graphical output. See @ref{Point and click}.
713 @node Point and click
714 @section Point and click
715 @cindex point and click
718 Point and click lets you find notes in the input by clicking on them
719 in the PDF viewer. This makes it easier to find input that causes
720 some error in the sheet music.
722 When this functionality is active, LilyPond adds hyperlinks to the PDF
723 file. These hyperlinks are sent to the web-browser, which opens a
724 text-editor with the cursor in the right place.
726 To make this chain work, you should configure your PDF viewer to
727 follow hyperlinks using the @file{lilypond-invoke-editor} script
728 supplied with LilyPond.
730 For Xpdf on Unix, the following should be present in
731 @file{xpdfrc}@footnote{On unix, this file is found either in
732 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
735 urlCommand "lilypond-invoke-editor %s"
738 The program @file{lilypond-invoke-editor} is a small helper
739 program. It will invoke an editor for the special @code{textedit}
740 URIs, and run a web browser for others. It tests the environment
741 variable @code{EDITOR} for the following patterns,
747 emacsclient --no-wait +@var{line}:@var{column} @var{file}
752 gvim --remote +:@var{line}:norm@var{char} @var{file}
758 nc -noask +@var{line} @var{file}'
762 The environment variable @code{LYEDITOR} is used to override this. It
763 contains the command line to start the editor, where @code{%(file)s},
764 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
765 and line respectively. The setting
768 emacsclient --no-wait +%(line)s:%(column)s %(file)s
772 for @code{LYEDITOR} is equivalent to the standard emacsclient
776 @cindex file size, output
778 The point and click links enlarge the output files significantly. For
779 reducing the size of PDF and PS files, point and click may be switched
783 #(ly:set-option 'point-and-click #f)
787 in a @file{.ly} file. Alternately, you may pass this as an command-line
791 lilypond -dno-point-and-click file.ly