1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-program.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 * Updating files with convert-ly::
38 @node Invoking lilypond
39 @section Invoking lilypond
40 @cindex Invoking LilyPond
41 @cindex command line options
42 @cindex options, command line
46 The @code{lilypond} executable may be called as follows from the command line.
49 lilypond [@var{option}]@dots{} @var{file}@dots{}
53 When invoked with a filename that has no extension, the @file{.ly}
54 extension is tried first. To read input from stdin, use a
55 dash (@code{-}) for @var{file}.
57 When @file{filename.ly} is processed it will produce
58 @file{filename.tex} as output (or @file{filename.ps} for PostScript
59 output). If @file{filename.ly} contains more than one @code{\score}
60 block, then the rest of the scores will be output in numbered files,
61 starting with @file{filename-1.tex}. Several files can be specified;
62 they will each be processed independently. @footnote{The status of
63 GUILE is not reset after processing a @code{.ly} file, so be careful
64 not to change any system defaults from within Scheme.}
67 @subsection Command line options
69 The following options are supported:
73 @item -e,--evaluate=@var{expr}
74 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
75 Multiple @code{-e} options may be given, they will be evaluated
78 The expression will be evaluated in the @code{guile-user} module, so
79 if you want to use definitions in @var{expr}, use
82 lilypond -e '(define-public a 42)'
86 on the command-line, and include
89 #(use-modules (guile-user))
93 at the top of the @code{.ly} file.
95 @item -f,--format=@var{format}
96 which formats should be written. Choices for @code{format} are
97 @code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
99 Example: @code{lilypond -fpng filename.ly}
103 @item -d,--define-default=@var{var}=@var{val}
104 This sets the internal program option @var{var} to the Scheme value
105 @var{val}. If @var{val} is not supplied, then @var{#t} is used. To
106 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
108 @cindex point and click, command line
117 -dpoint-and-click='#f'
120 Here are a few interesting options.
124 Running @code{lilypond -dhelp} will print all of the @code{-d} options
128 This option sets the default paper-size,
130 -dpaper-size=\"letter\"
134 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
138 Do not trust the @code{.ly} input.
140 When LilyPond formatting is available through a web server, either the
141 @code{--safe} or the @code{--jail} option @b{MUST} be passed. The
142 @code{--safe} option will prevent inline Scheme code from wreaking
149 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
154 The @code{-dsafe} option works by evaluating in-line Scheme
155 expressions in a special safe module. This safe module is derived from
156 GUILE @file{safe-r5rs} module, but adds a number of functions of the
157 LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
159 In addition, safe mode disallows @code{\include} directives and
160 disables the use of backslashes in @TeX{} strings.
162 In safe mode, it is not possible to import LilyPond variables
165 safe does @emph{not} detect resource overuse. It is still possible to
166 make the program hang indefinitely, for example by feeding cyclic data
167 structures into the backend. Therefore, if using LilyPond on a
168 publicly accessible webserver, the process should be limited in both
169 CPU and memory usage.
171 The safe mode will prevent many useful LilyPond snippets from being
172 compiled. The @code{--jail} is a more secure alternative, but
173 requires more work to set up.
176 the output format to use for the back-end. Choices for @code{format} are
179 for @TeX{} output, to be processed with La@TeX{}. If present, the file
180 @file{file.textmetrics} is read to determine text extents.
182 dump text strings to @file{.texstr} file, which can be run through
183 (La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
184 extents of strings of text. @strong{Warning:} this functionality is
185 currently missing due to heavy restructuring of the source code.
188 @cindex PostScript output
190 Postscript files include TTF, Type1 and OTF fonts. No subsetting of
191 these fonts is done. When using oriental character sets, this can
195 for encapsulated PostScript. This dumps every page (system) as a separate
196 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
197 all pages (systems) including fonts.
199 This mode is used by default by lilypond-book.
202 for SVG (Scalable Vector Graphics). This dumps every page as a separate
203 @file{SVG} file, with embedded fonts.
204 @cindex SVG (Scalable Vector Graphics)
205 You need a SVG viewer which supports embedded fonts, or a SVG
206 viewer which is able to replace the embedded fonts with OTF fonts.
207 Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
208 (version 0.42 or later), after copying the OTF fonts in directory
209 @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
211 for a dump of the raw, internal Scheme-based drawing commands.
215 Example: @code{lilypond -dbackend=svg filename.ly}
217 @cindex output format, setting
220 Generate an output file containing the titles and the first system
223 Generate the full pages, the default. @code{-dno-print-pages} is
224 useful in combination with @code{-dpreview}.
231 Show a summary of usage.
233 @item -H,--header=FIELD
234 Dump a header field to file BASENAME.FIELD
236 @item --include, -I=@var{directory}
237 Add @var{directory} to the search path for input files.
238 @cindex file searching
241 @item -i,--init=@var{file}
242 Set init file to @var{file} (default: @file{init.ly}).
244 @item -o,--output=@var{FILE}
245 Set the default output file to @var{FILE}. The appropriate
246 suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
253 Generate DVI files. In this case, the @TeX{} backend should be
254 specified, i.e., @code{-dbackend=tex}.
257 Generate pictures of each page, in PNG format. This implies
258 @code{--ps}. The resolution in DPI of the image may be set with
264 Generate PDF. This implies @code{--ps}.
268 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
269 Run LilyPond in a chroot jail.
271 The @code{--jail} option provides a more flexible alternative to
272 @code{--safe} when LilyPond formatting is available through a web
273 server or whenever LilyPond executes externally provided
276 The @code{--jail} option works by changing the root of LilyPond to
277 @var{jail} just before starting the actual compilation process. The user
278 and group are then changed to match those provided, and the current
279 directory is changed to @var{dir}. This setup guarantees that it is not
280 possible (at least in theory) to escape from the jail. Note that for
281 @code{--jail} to work LilyPond must be run as root, which is usually
282 accomplished in a safe way using @command{sudo}.
284 Setting up a jail is a slightly delicate matter, as we must be sure that
285 LilyPond is able to find whatever it needs to compile the source
286 @emph{inside the jail}. A typical setup comprises the following items:
289 @item Setting up a separate filesystem
290 A separate filesystem should be created for LilyPond, so that it can be
291 mounted with safe options such as @code{noexec}, @code{nodev}, and
292 @code{nosuid}. In this way, it is impossible to run executables or to
293 write directly to a device from LilyPond. If you do not want to create a
294 separate partition, just create a file of reasonable size and use it to
295 mount a loop device. A separate filesystem also guarantees that LilyPond
296 cannot write more space than it is allowed.
298 @item Setting up a separate user
299 A separate user and group (say, @samp{lily}/@samp{lily}) with low
300 privileges should be used to run LilyPond inside the jail. There should
301 be a single directory writable by this user, which should be passed in
304 @item Preparing the jail
305 LilyPond needs to read a number of files while running. All these files
306 are to be copied into the jail, under the same path they appear in the
307 real root filesystem. The entire content of the LilyPond installation
308 (e.g., @file{/usr/share/lilypond})
311 If problems arise, the simplest way to trace them down is to run
312 LilyPond using @command{strace}, which will allow you to determine which
315 @item Running LilyPond
316 In a jail mounted with @code{noexec} it is impossible to execute any external
317 program. Therefore LilyPond must be run with a backend that does not
318 require any such program. As we already mentioned, it must be also run
319 with superuser privileges (which, of course, it will lose immediately),
320 possibly using @command{sudo}. It is a good idea to limit the number of
321 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
322 -t}), and, if your operating system supports it, the amount of memory
323 that can be allocated.
328 Show version information.
331 Be verbose: show full paths of all files read, and give timing
335 Show the warranty with which GNU LilyPond comes. (It comes with
336 @strong{NO WARRANTY}!)
340 @subsection Environment variables
344 @cindex LILYPOND_DATADIR
346 @code{Lilypond} recognizes the following environment variables:
348 @item LILYPOND_DATADIR
349 This specifies a directory where locale messages and
350 data files will be looked up by default. The directory should contain
351 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
354 This selects the language for the warning messages.
356 @item LILYPOND_GC_YIELD
357 With this variable the memory footprint and performance can be
358 adjusted. It is a percentage tunes memory management behavior. With
359 higher values, the program uses more memory, with smaller values, it
360 uses more CPU time. The default value is @code{70}.
365 @node Updating files with convert-ly
366 @section Updating with @command{convert-ly}
368 @cindex Updating a LilyPond file
371 The LilyPond input syntax is routinely changed to simplify it or improve
372 it in different ways. As a side effect of this, the LilyPond interpreter
373 often is no longer compatible with older input files. To remedy this,
374 the program @command{convert-ly} can be used to deal with most of the
375 syntax changes between LilyPond versions.
377 It uses @code{\version} statements in the input files to detect the
378 old version number. In most cases, to upgrade your input file it is
379 sufficient to run@footnote{MacOS X users may execute this command
380 under the menu entry @samp{Compile > Update syntax}.}
383 convert-ly -e myfile.ly
386 If there are no changes to myfile.ly and file called myfile.ly.NEW
387 is created, then myfile.ly is already updated.
389 @command{convert-ly} always converts up to the last syntax change handled by
390 it. This means that the @code{\version} number left in the file is
391 usually lower than the version of @command{convert-ly} itself.
393 To upgrade LilyPond fragments in texinfo files, use
396 convert-ly --from=... --to=... --no-version *.itely
399 To see the changes in the LilyPond syntax between two versions, use
402 convert-ly --from=... --to=... -s
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. There is a list of current bugs on our google bug tracker,
536 @uref{http://code.google.com/p/lilypond/issues/list}
538 If you have discovered a bug which is not listed, please report the
539 bug by following the directions on
541 @uref{http://lilypond.org/web/devel/participating/bugs}
543 Please construct submit @ruser{Minimal examples}, of bug reports. We do not
544 have the resources to investigate reports which are not as small as possible.
548 @section Error messages
550 @cindex error messages
551 Different error messages can appear while compiling a file:
557 Something looks suspect. If you are requesting something out of the
558 ordinary then you will understand the message, and can ignore it.
559 However, warnings usually indicate that something is wrong with the
563 Something is definitely wrong. The current processing step (parsing,
564 interpreting, or formatting) will be finished, but the next step will
570 Something is definitely wrong, and LilyPond cannot continue. This
571 happens rarely. The most usual cause is misinstalled fonts.
573 @cindex trace, Scheme
577 Errors that occur while executing Scheme code are caught by the Scheme
578 interpreter. If running with the verbose option (@code{-V} or
579 @code{--verbose}) then a call trace of the offending
580 function call is printed.
582 @cindex Programming error
583 @item Programming error
584 There was some internal inconsistency. These error messages are
585 intended to help the programmers and debuggers. Usually, they can be
586 ignored. Sometimes, they come in such big quantities that they obscure
587 other output. In this case, file a bug-report.
589 @item Aborted (core dumped)
590 This signals a serious programming error that caused the program to
591 crash. Such errors are considered critical. If you stumble on one,
597 @cindex errors, message format
598 If warnings and errors can
599 be linked to some part of the input file, then error messages have the
603 @var{filename}:@var{lineno}:@var{columnno}: @var{message}
604 @var{offending input line}
607 A line-break is inserted in the offending line to indicate the column
608 where the error was found. For example,
611 test.ly:2:19: error: not a duration: 5:
616 These locations are LilyPond's best guess about where the warning or
617 error occurred, but (by their very nature) warnings and errors occur
618 when something unexpected happens. If you can't see an error in the
619 indicated line of your input file, try checking one or two lines
620 above the indicated position.
624 @section Editor support
629 @cindex modes, editor
630 @cindex syntax coloring
631 @cindex coloring, syntax
633 There is support from different editors for LilyPond.
637 Emacs has a @file{lilypond-mode}, which provides keyword
638 autocompletion, indentation, LilyPond specific parenthesis matching
639 and syntax coloring, handy compile short-cuts and reading LilyPond
640 manuals using Info. If @file{lilypond-mode} is not installed on your
641 platform, then read the
643 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
646 installation instructions.
651 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
652 with syntax coloring tools. For more information, refer to the
654 @uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
657 installation instructions.
663 Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit} text
664 editor, LilyPondTool is the most feature-rich text-based tool for editing
665 LilyPond scores. Its features include a Document Wizard with lyrics
666 support to set up documents easier, and embedded PDF viewer with advanced
667 point-and-click support. For screenshots, demos and installation
668 instructions, visit @uref{http://lilypondtool@/.organum@/.hu}
672 All these editors can be made to jump into the input file to the source
673 of a symbol in the graphical output. See @ref{Point and click}.
675 In addition, several other text editors provide some support for
680 The @uref{http://@/www@/.uoregon@/.edu/~koch/texshop/index@/.html,TexShop}
681 editor for Mac OS X can be extended to run LilyPond, lilypond-book and
682 convert-ly from within the editor, using the extensions available at
683 @uref{http://@/www@/.dimi@/.uniud@/.it/vitacolo/freesoftware@/.html}.
688 @node Point and click
689 @section Point and click
690 @cindex point and click
693 Point and click lets you find notes in the input by clicking on them
694 in the PDF viewer. This makes it easier to find input that causes
695 some error in the sheet music.
697 When this functionality is active, LilyPond adds hyperlinks to the PDF
698 file. These hyperlinks are sent to the web-browser, which opens a
699 text-editor with the cursor in the right place.
701 To make this chain work, you should configure your PDF viewer to
702 follow hyperlinks using the @file{lilypond-invoke-editor} script
703 supplied with LilyPond.
705 For Xpdf on Unix, the following should be present in
706 @file{xpdfrc}@footnote{On unix, this file is found either in
707 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
710 urlCommand "lilypond-invoke-editor %s"
713 The program @file{lilypond-invoke-editor} is a small helper
714 program. It will invoke an editor for the special @code{textedit}
715 URIs, and run a web browser for others. It tests the environment
716 variable @code{EDITOR} for the following patterns,
722 emacsclient --no-wait +@var{line}:@var{column} @var{file}
727 gvim --remote +:@var{line}:norm@var{char} @var{file}
733 nc -noask +@var{line} @var{file}'
737 The environment variable @code{LYEDITOR} is used to override this. It
738 contains the command line to start the editor, where @code{%(file)s},
739 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
740 and line respectively. The setting
743 emacsclient --no-wait +%(line)s:%(column)s %(file)s
747 for @code{LYEDITOR} is equivalent to the standard emacsclient
751 @cindex file size, output
753 The point and click links enlarge the output files significantly. For
754 reducing the size of PDF and PS files, point and click may be switched
758 #(ly:set-option 'point-and-click #f)
762 in a @file{.ly} file. Alternately, you may pass this as an command-line
766 lilypond -dno-point-and-click file.ly