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}
104 @item -d,--define-default=@var{var}=@var{val}
105 This sets the internal program option @var{var} to the Scheme value
106 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
107 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
109 @cindex point and click, command line
118 -dpoint-and-click='#f'
121 Here are a few interesting options.
125 Running @code{lilypond -dhelp} will print all of the @code{-d} options
129 This option sets the default paper-size,
131 -dpaper-size=\"letter\"
135 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
139 Do not trust the @code{.ly} input.
141 When LilyPond formatting is available through a web server, either the
142 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
143 @code{--safe} option will prevent inline Scheme code from wreaking
150 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
155 The @code{-dsafe} option works by evaluating in-line Scheme
156 expressions in a special safe module. This safe module is derived from
157 GUILE @file{safe-r5rs} module, but adds a number of functions of the
158 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
160 In addition, safe mode disallows @code{\include} directives and
161 disables the use of backslashes in @TeX{} strings.
163 In safe mode, it is not possible to import LilyPond variables
166 safe does @emph{not} detect resource overuse. It is still possible to
167 make the program hang indefinitely, for example by feeding cyclic data
168 structures into the backend. Therefore, if using LilyPond on a
169 publicly accessible webserver, the process should be limited in both
170 CPU and memory usage.
172 The safe mode will prevent many useful LilyPond snippets from being
173 compiled. The @code{--jail} is a more secure alternative, but
174 requires more work to set up.
177 the output format to use for the back-end. Choices for @code{format} are
180 for @TeX{} output, to be processed with La@TeX{}. If present, the file
181 @file{file.textmetrics} is read to determine text extents.
183 dump text strings to @file{.texstr} file, which can be run through
184 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
185 extents of strings of text. @strong{Warning:} this functionality is
186 currently missing due to heavy restructuring of the source code.
189 @cindex PostScript output
191 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
192 these fonts is done. When using oriental character sets, this can
196 for encapsulated PostScript. This dumps every page (system) as a separate
197 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
198 all pages (systems) including fonts.
200 This mode is used by default by lilypond-book.
203 for SVG (Scalable Vector Graphics). This dumps every page as a separate
204 @file{SVG} file, with embedded fonts.
205 @cindex SVG (Scalable Vector Graphics)
206 You need a SVG viewer which supports embedded fonts, or a SVG
207 viewer which is able to replace the embedded fonts with OTF fonts.
208 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
209 (version 0.42 or later), after copying the OTF fonts in directory
210 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
212 for a dump of the raw, internal Scheme-based drawing commands.
216 Example: @code{lilypond -dbackend=svg filename.ly}
218 @cindex output format, setting
224 Show a summary of usage.
226 @item -H,--header=FIELD
227 Dump a header field to file BASENAME.FIELD
229 @item --include, -I=@var{directory}
230 Add @var{directory} to the search path for input files.
231 @cindex file searching
234 @item -i,--init=@var{file}
235 Set init file to @var{file} (default: @file{init.ly}).
237 @item -o,--output=@var{FILE}
238 Set the default output file to @var{FILE}. The appropriate
239 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
246 Generate DVI files. In this case, the @TeX{} backend should be
247 specified, i.e., @code{-b tex}.
250 Generate pictures of each page, in PNG format. This implies
251 @code{--ps}. The resolution in DPI of the image may be set with
257 Generate PDF. This implies @code{--ps}.
260 Generate an output file containing the titles and the first system
263 Do not generate the full pages. Useful in combination with
267 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
268 Run LilyPond in a chroot jail.
270 The @code{--jail} option provides a more flexible alternative to
271 @code{--safe} when LilyPond formatting is available through a web
272 server or whenever LilyPond executes externally provided
275 The @code{--jail} option works by changing the root of LilyPond to
276 @var{jail} just before starting the actual compilation process. The user
277 and group are then changed to match those provided, and the current
278 directory is changed to @var{dir}. This setup guarantees that it is not
279 possible (at least in theory) to escape from the jail. Note that for
280 @code{--jail} to work LilyPond must be run as root, which is usually
281 accomplished in a safe way using @command{sudo}.
283 Setting up a jail is a slightly delicate matter, as we must be sure that
284 LilyPond is able to find whatever it needs to compile the source
285 @emph{inside the jail}. A typical setup comprises the following items:
288 @item Setting up a separate filesystem
289 A separate filesystem should be created for LilyPond, so that it can be
290 mounted with safe options such as @code{noexec}, @code{nodev}, and
291 @code{nosuid}. In this way, it is impossible to run executables or to
292 write directly to a device from LilyPond. If you do not want to create a
293 separate partition, just create a file of reasonable size and use it to
294 mount a loop device. A separate filesystem also guarantees that LilyPond
295 cannot write more space than it is allowed.
297 @item Setting up a separate user
298 A separate user and group (say, @samp{lily}/@samp{lily}) with low
299 privileges should be used to run LilyPond inside the jail. There should
300 be a single directory writable by this user, which should be passed in
303 @item Preparing the jail
304 LilyPond needs to read a number of files while running. All these files
305 are to be copied into the jail, under the same path they appear in the
306 real root filesystem. The entire content of the LilyPond installation
307 (e.g., @file{/usr/share/lilypond})
310 If problems arise, the simplest way to trace them down is to run
311 LilyPond using @command{strace}, which will allow you to determine which
314 @item Running LilyPond
315 In a jail mounted with @code{noexec} it is impossible to execute any external
316 program. Therefore LilyPond must be run with a backend that does not
317 require any such program. As we already mentioned, it must be also run
318 with superuser privileges (which, of course, it will lose immediately),
319 possibly using @command{sudo}. It is a good idea to limit the number of
320 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
321 -t}), and, if your operating system supports it, the amount of memory
322 that can be allocated.
327 Show version information.
330 Be verbose: show full paths of all files read, and give timing
334 Show the warranty with which GNU LilyPond comes. (It comes with
335 @strong{NO WARRANTY}!)
339 @subsection Environment variables
343 @cindex LILYPOND_DATADIR
345 @code{Lilypond} recognizes the following environment variables:
347 @item LILYPOND_DATADIR
348 This specifies a directory where locale messages and
349 data files will be looked up by default. The directory should contain
350 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
353 This selects the language for the warning messages.
355 @item LILYPOND_GC_YIELD
356 With this variable the memory footprint and performance can be
357 adjusted. It is a percentage tunes memory management behavior. With
358 higher values, the program uses more memory, with smaller values, it
359 uses more CPU time. The default value is @code{70}.
364 @node Notes for the MacOS X app
365 @section Notes for the MacOS X app
367 The scripts (such as lilypond-book, convert-ly, abc2ly, and even
368 lilypond itself) are also
369 included inside MacOS X .app. They can be run from the command line by
370 invoking them directly, e.g.
373 @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond
377 The same is true of the other scripts in that directory, including
378 lilypond-book, convert-ly, abc2ly, etc.
380 Alternatively, you may create scripts which add the path
381 automatically. Create a directory to store these scripts,
388 Create a file called @code{lilypond} which contains
391 exec @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond "$@@"
394 Create similar files @code{lilypond-book}, @code{convert-ly}, and
395 any other helper programs you use (@code{abc2ly}, @code{midi2ly},
396 etc). Simply replace the @code{bin/lilypond} with
397 @code{bin/convert-ly} (or other program name) in the above file.
399 Make the file executable,
405 Now, add this directory to your path. Modify (or create)
406 a file called @code{.profile} in your home directory such that it contains
409 export PATH=$PATH:~/bin
413 This file should end with a blank line.
415 Note that @var{path/to} will generally be @code{/Applications/}.
418 @node Updating files with convert-ly
419 @section Updating with @command{convert-ly}
421 @cindex Updating a LilyPond file
424 The LilyPond input syntax is routinely changed to simplify it or improve
425 it in different ways. As a side effect of this, the LilyPond interpreter
426 often is no longer compatible with older input files. To remedy this,
427 the program @command{convert-ly} can be used to deal with most of the
428 syntax changes between LilyPond versions.
430 It uses @code{\version} statements in the input files to detect the
431 old version number. In most cases, to upgrade your input file it is
432 sufficient to run@footnote{MacOS X users may execute this command
433 under the menu entry @samp{Compile > Update syntax}.}
436 convert-ly -e myfile.ly
439 If there are no changes to myfile.ly and file called myfile.ly.NEW
440 is created, then myfile.ly is already updated.
442 @command{convert-ly} always converts up to the last syntax change handled by
443 it. This means that the @code{\version} number left in the file is
444 usually lower than the version of @command{convert-ly} itself.
446 To upgrade LilyPond fragments in texinfo files, use
449 convert-ly --from=... --to=... --no-version *.itely
452 To upgrade many files at once, combine @code{convert-ly} with
453 standard unix commands. This example will upgrade all @code{.ly}
454 files in the current directory
457 for f in *.ly; do convert-ly -e $f; done;
460 In general, the program is invoked as follows:
463 convert-ly [@var{option}]@dots{} @var{file}@dots{}
467 The following options can be given:
471 Do an inline edit of the input file. Overrides @code{--output}.
473 @item -f,--from=@var{from-patchlevel}
474 Set the version to convert from. If this is not set, @command{convert-ly}
475 will guess this, on the basis of @code{\version} strings in the file.
477 @item -n,--no-version
478 Normally, @command{convert-ly} adds a @code{\version} indicator
479 to the output. Specifying this option suppresses this.
481 @item -s, --show-rules
482 Show all known conversions and exit.
484 @item --to=@var{to-patchlevel}
485 Set the goal version of the conversion. It defaults to the latest
495 Not all language changes are handled. Only one output option can be
496 specified. Automatically updating scheme and lilypond scheme
497 interfaces is quite unlikely; be prepared to tweak scheme code
501 @c We might want to make this a completely new section, along with more
502 @c info about how to upgrade old input files. -gp
505 Copy and paste from CVS, last updated
508 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/
509 convert-ly.txt?rev=HEAD&content-type=text/plain
511 NEW: not exactly copied; this list has been modified. Since we're
512 changing the bug system, it doesn't make sense to copy from
513 the bug CVS any more. I'll figure out something else. -gp
517 There are a few things that the convert-ly cannot handle. Here's a list of
519 that the community has complained about.
521 This bug report structure has been chosen because convert-ly has a structure
523 allow to smoothly implement all needed changes. Thus this is just a wishlist,
528 Doesn't always convert figured bass correctly, specifically things like {<
529 >}. Mats' comment on working around this:
530 To be able to run convert-ly
531 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
532 and similarly I replaced '>}' with '&}'. After the conversion, I could
533 then change back from '{ #' to '{ <' and from '& }' to '> }'.
534 Doesn't convert all text markup correctly. In the old markup syntax,
535 it was possible to group a number of markup commands together within
537 -#'((bold italic) "string")
538 This will incorrectly be converted into
539 -\markup{{\bold italic} "string"}
540 instead of the correct
541 -\markup{\bold \italic "string"}
543 Doesn't handle \partcombine
544 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
547 \magnify isn't changed to \fontsize.
548 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
549 remove-tag isn't changed.
550 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
551 first-page-number isn't changed.
552 - first-page-number no => print-first-page-number = ##f
553 Line breaks in header strings aren't converted.
554 - \\\\ as line break in \header strings => \markup \center-align <
555 "First Line" "Second Line" >
556 Crescendo and decrescendo terminators aren't converted.
560 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
563 \markup{ \center-align <{ ... }> } should be converted to:
564 \markup{ \center-align {\line { ... }} }
565 but now, \line is missing.
567 Special LaTeX characters such as $~$ in text are not converted to UTF8.
569 \score{} must now begin with a music expression. Anything else
570 (particularly \header{}) must come after the music.
575 @section Reporting bugs
578 @cindex reporting bugs
580 If you have input that results in a crash or an erroneous output, then
581 that is a bug. There is a list of current bugs on our google bug tracker,
583 @uref{http://code.google.com/p/lilypond/issues/list}
585 If you have discovered a bug which is not listed, please report the
586 bug by following the directions on
588 @uref{http://lilypond.org/web/devel/participating/bugs}
590 Please construct submit @ref{Minimal examples} of bug reports. We do not
591 have the resources to investigate reports which are not as small as possible.
595 @section Error messages
597 @cindex error messages
598 Different error messages can appear while compiling a file:
604 Something looks suspect. If you are requesting something out of the
605 ordinary then you will understand the message, and can ignore it.
606 However, warnings usually indicate that something is wrong with the
610 Something is definitely wrong. The current processing step (parsing,
611 interpreting, or formatting) will be finished, but the next step will
617 Something is definitely wrong, and LilyPond cannot continue. This
618 happens rarely. The most usual cause is misinstalled fonts.
620 @cindex trace, Scheme
624 Errors that occur while executing Scheme code are caught by the Scheme
625 interpreter. If running with the verbose option (@code{-V} or
626 @code{--verbose}) then a call trace of the offending
627 function call is printed.
629 @cindex Programming error
630 @item Programming error
631 There was some internal inconsistency. These error messages are
632 intended to help the programmers and debuggers. Usually, they can be
633 ignored. Sometimes, they come in such big quantities that they obscure
634 other output. In this case, file a bug-report.
636 @item Aborted (core dumped)
637 This signals a serious programming error that caused the program to
638 crash. Such errors are considered critical. If you stumble on one,
644 @cindex errors, message format
645 If warnings and errors can
646 be linked to some part of the input file, then error messages have the
650 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
651 @var{offending input line}
654 A line-break is inserted in the offending line to indicate the column
655 where the error was found. For example,
658 test.ly:2:19: error: not a duration: 5:
663 These locations are LilyPond's best guess about where the warning or
664 error occurred, but (by their very nature) warnings and errors occur
665 when something unexpected happens. If you can't see an error in the
666 indicated line of your input file, try checking one or two lines
667 above the indicated position.
671 @section Editor support
676 @cindex modes, editor
677 @cindex syntax coloring
678 @cindex coloring, syntax
680 There is support from different editors for LilyPond.
684 Emacs has a @file{lilypond-mode}, which provides keyword
685 autocompletion, indentation, LilyPond specific parenthesis matching
686 and syntax coloring, handy compile short-cuts and reading LilyPond
687 manuals using Info. If @file{lilypond-mode} is not installed on your
688 platform, then read the
690 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
693 installation instructions.
698 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
699 with syntax coloring tools. For more information, refer to the
701 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
704 installation instructions.
710 Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit} text
711 editor, LilyPondTool is the most feature-rich text-based tool for editing
712 LilyPond scores. Its features include a Document Wizard with lyrics
713 support to set up documents easier, and embedded PDF viewer with advanced
714 point-and-click support. For screenshots, demos and installation
715 instructions, visit @uref{http://lilypondtool@/.organum@/.hu}
719 All these editors can be made to jump into the input file to the source
720 of a symbol in the graphical output. See @ref{Point and click}.
723 @node Point and click
724 @section Point and click
725 @cindex point and click
728 Point and click lets you find notes in the input by clicking on them
729 in the PDF viewer. This makes it easier to find input that causes
730 some error in the sheet music.
732 When this functionality is active, LilyPond adds hyperlinks to the PDF
733 file. These hyperlinks are sent to the web-browser, which opens a
734 text-editor with the cursor in the right place.
736 To make this chain work, you should configure your PDF viewer to
737 follow hyperlinks using the @file{lilypond-invoke-editor} script
738 supplied with LilyPond.
740 For Xpdf on Unix, the following should be present in
741 @file{xpdfrc}@footnote{On unix, this file is found either in
742 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
745 urlCommand "lilypond-invoke-editor %s"
748 The program @file{lilypond-invoke-editor} is a small helper
749 program. It will invoke an editor for the special @code{textedit}
750 URIs, and run a web browser for others. It tests the environment
751 variable @code{EDITOR} for the following patterns,
757 emacsclient --no-wait +@var{line}:@var{column} @var{file}
762 gvim --remote +:@var{line}:norm@var{char} @var{file}
768 nc -noask +@var{line} @var{file}'
772 The environment variable @code{LYEDITOR} is used to override this. It
773 contains the command line to start the editor, where @code{%(file)s},
774 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
775 and line respectively. The setting
778 emacsclient --no-wait +%(line)s:%(column)s %(file)s
782 for @code{LYEDITOR} is equivalent to the standard emacsclient
786 @cindex file size, output
788 The point and click links enlarge the output files significantly. For
789 reducing the size of PDF and PS files, point and click may be switched
793 #(ly:set-option 'point-and-click #f)
797 in a @file{.ly} file. Alternately, you may pass this as an command-line
801 lilypond -dno-point-and-click file.ly