X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Frunning.itely;h=4abfcf09b13b677717081af5facce9cb36bb5fad;hb=588b4b5c23b6c8a0519d6f6c0540b7bb88294782;hp=1f79d36536c1999500e05ec4eb9c9f0ae46ecb80;hpb=eabaea3732b3c8cfa3b0324aeaca2c5bb39c4be7;p=lilypond.git diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely index 1f79d36536..4abfcf09b1 100644 --- a/Documentation/usage/running.itely +++ b/Documentation/usage/running.itely @@ -4,10 +4,11 @@ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH When revising a translation, copy the HEAD committish of the - version that you are working on. See TRANSLATION for details. + version that you are working on. For details, see the Contributors' + Guide, node Updating translation committishes.. @end ignore -@c \version "2.12.0" +@c \version "2.15.18" @node Running lilypond @@ -20,8 +21,6 @@ This chapter details the technicalities of running LilyPond. * Command-line usage:: * Error messages:: * Common errors:: -* Point and click:: -* Text editor support:: @end menu @@ -56,6 +55,7 @@ if you are unfamiliar with the command-line. * Invoking lilypond:: * Command line options for lilypond:: * Environment variables:: +* LilyPond in chroot jail:: @end menu @node Invoking lilypond @@ -97,6 +97,30 @@ will output @var{base}@file{-violin.pdf} and @var{base}@file{-cello-1.pdf}. +@unnumberedsubsubsec Standard shell commands + +If your shell (i.e. command window) supports normal redirects, +then you might find it useful to use the following commands to +redirect console output to a file: + +@itemize + +@item +@code{lilypond file.ly 1>stdout.log} to redirect normal output + +@item +@code{lilypond file.ly 2>stderr.log} to redirect error messages + +@item +@code{lilypond file.ly &>all.log} to redirect all output + +@end itemize + +Consult the documentation for your shell to see if it supports these +options, or if the syntax is different. Note that these are shell +commands and have nothing to do with lilypond. + + @node Command line options for lilypond @unnumberedsubsec Command line options for @command{lilypond} @@ -111,7 +135,7 @@ The following options are supported: @item -e,--evaluate=@var{expr} Evaluate the Scheme @var{expr} before parsing any @file{.ly} files. -Multiple @code{-e} options may be given, they will be evaluated +Multiple @option{-e} options may be given, they will be evaluated sequentially. The expression will be evaluated in the @code{guile-user} module, so @@ -133,7 +157,7 @@ at the top of the @code{.ly} file. @item -f,--format=@var{format} which formats should be written. Choices for @code{format} are -@code{svg}, @code{ps}, @code{pdf}, and @code{png}. +@code{ps}, @code{pdf}, and @code{png}. Example: @code{lilypond -fpng @var{filename}.ly} @@ -162,7 +186,7 @@ Here are a few interesting options. @table @samp @item help -Running @code{lilypond -dhelp} will print all of the @code{-d} options +Running @code{lilypond -dhelp} will print all of the @option{-d} options available. @cindex paper-size, command line @@ -183,23 +207,23 @@ Note that the string must be enclosed in escaped quotes ( @code{\"} ). Do not trust the @code{.ly} input. When LilyPond formatting is available through a web server, either the -@code{--safe} or the @code{--jail} option @b{MUST} be passed. The -@code{--safe} option will prevent inline Scheme code from wreaking +@option{--safe} or the @option{--jail} option @b{MUST} be passed. The +@option{--safe} option will prevent inline Scheme code from wreaking havoc, for example @quotation @verbatim #(system "rm -rf /") { - c4^#(ly:export (ly:gulp-file "/etc/passwd")) + c4^$(ly:gulp-file "/etc/passwd") } @end verbatim @end quotation -The @code{-dsafe} option works by evaluating in-line Scheme +The @option{-dsafe} option works by evaluating in-line Scheme expressions in a special safe module. This safe module is derived from GUILE @file{safe-r5rs} module, but adds a number of functions of the -LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}. +LilyPond API. These functions are listed in @file{scm/safe-lily.scm}. In addition, safe mode disallows @code{\include} directives and disables the use of backslashes in @TeX{} strings. @@ -207,14 +231,14 @@ disables the use of backslashes in @TeX{} strings. In safe mode, it is not possible to import LilyPond variables into Scheme. -@code{-dsafe} does @emph{not} detect resource overuse. It is still possible to +@option{-dsafe} does @emph{not} detect resource overuse. It is still possible to make the program hang indefinitely, for example by feeding cyclic data structures into the backend. Therefore, if using LilyPond on a publicly accessible webserver, the process should be limited in both CPU and memory usage. The safe mode will prevent many useful LilyPond snippets from being -compiled. The @code{--jail} is a more secure alternative, but +compiled. The @option{--jail} is a more secure alternative, but requires more work to set up. @cindex output format, setting @@ -231,7 +255,7 @@ the output format to use for the back-end. Choices for @code{format} are @item eps -@cindex Postscript, encapulated +@cindex Postscript, encapsulated @cindex EPS (Encapsulated PostScript) for encapsulated PostScript. This dumps every page (system) as a separate @@ -262,7 +286,7 @@ This mode is used by default by @command{lilypond-book}. for a dump of the raw, internal Scheme-based drawing commands. @item null - do not output a printed score; has the same effect as @code{-dno-print-pages}. + do not output a printed score; has the same effect as @option{-dno-print-pages}. @end table Example: @code{lilypond -dbackend=svg @var{filename}.ly} @@ -270,10 +294,24 @@ Example: @code{lilypond -dbackend=svg @var{filename}.ly} @item preview @cindex preview, command line Generate an output file containing the titles and the first system +of music. If @code{\bookpart} blocks are used, the titles and +first system of every @code{\bookpart} will appear in the output. +The @code{ps}, @code{eps}, and @code{svg} backends support this +option. + +@item gui +Runs silently and redirect all output to a log file. + +Note to Windows users: By default @code{lilypond.exe} outputs all +progress information to the command window, @code{lilypond-windows.exe} +does not and returns a prompt, with no progress information, immediately +at the command line. The @option{-dgui} option can be used in this case +to redirect output to a log file. + @item print-pages -Generate the full pages, the default. @code{-dno-print-pages} is -useful in combination with @code{-dpreview}. +Generate the full pages, the default. @option{-dno-print-pages} is +useful in combination with @option{-dpreview}. @end table @@ -285,17 +323,56 @@ Show a summary of usage. @item -H,--header=@var{FIELD} Dump a header field to file @file{BASENAME.@var{FIELD}}. -@item --include, -I=@var{directory} -Add @var{directory} to the search path for input files. @cindex file searching @cindex search path +@item --include, -I=@var{directory} +Add @var{directory} to the search path for input files. + +Multiple -I options may be given. The search will start in the +first defined directory, and if the file to be included is not +found the search will continue in subsequent directories. @item -i,--init=@var{file} Set init file to @var{file} (default: @file{init.ly}). -@item -o,--output=@var{FILE} -Set the default output file to @var{FILE}. The appropriate -suffix will be added (e.g. @code{.pdf} for pdf) +@cindex loglevel +@cindex output verbosity, setting + +@item -l,--loglevel=@var{LEVEL} +Set the verbosity of the console output to @var{LEVEL}. Possible values are: +@table @code +@item NONE +No output at all, not even error messages. + +@item ERROR +Only error messages, no warnings or progress messages. + +@item WARN +Warnings and error messages, no progress. + +@item BASIC_PROGRESS +Basic progress messages (success), warnings and errors. + +@item PROGRESS +All progress messages, warnings and errors. + +@item INFO (default) +Progress messages, warnings, errors and further execution information. + +@item DEBUG +All possible messages, including verbose debug output. +@end table + + +@cindex folder, directing output to +@cindex output filename, setting + +@item -o,--output=@var{FILE} or @var{FOLDER} +Set the default output file to @var{FILE} or, if a folder with +that name exists, direct the output to @var{FOLDER}, taking the +file name from the input file. The appropriate suffix will be +added (e.g. @code{.pdf} for pdf) in both cases. + @cindex PostScript output @@ -306,7 +383,7 @@ Generate PostScript. @item --png Generate pictures of each page, in PNG format. This implies -@code{--ps}. The resolution in DPI of the image may be set with +@option{--ps}. The resolution in DPI of the image may be set with @example -dresolution=110 @end example @@ -314,24 +391,24 @@ Generate pictures of each page, in PNG format. This implies @cindex Portable Document Format (PDF) output @item --pdf -Generate PDF. This implies @code{--ps}. +Generate PDF. This implies @option{--ps}. @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir} Run @command{lilypond} in a chroot jail. -The @code{--jail} option provides a more flexible alternative to -@code{--safe} when LilyPond formatting is available through a web +The @option{--jail} option provides a more flexible alternative to +@option{--safe} when LilyPond formatting is available through a web server or whenever LilyPond executes externally provided sources. -The @code{--jail} option works by changing the root of @command{lilypond} to +The @option{--jail} option works by changing the root of @command{lilypond} to @var{jail} just before starting the actual compilation process. The user and group are then changed to match those provided, and the current directory is changed to @var{dir}. This setup guarantees that it is not possible (at least in theory) to escape from the jail. Note that for -@code{--jail} to work @command{lilypond} must be run as root, which is usually +@option{--jail} to work @command{lilypond} must be run as root, which is usually accomplished in a safe way using @command{sudo}. Setting up a jail is a slightly delicate matter, as we must be sure that @@ -385,10 +462,11 @@ Be verbose: show full paths of all files read, and give timing information. @item -w,--warranty -Show the warranty with which GNU LilyPond comes. (It comes with +Show the warranty with which GNU LilyPond comes. (It comes with @strong{NO WARRANTY}!) @end table + @node Environment variables @unnumberedsubsec Environment variables @@ -406,15 +484,136 @@ subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc. @item LANG This selects the language for the warning messages. +@item LILYPOND_LOGLEVEL +The default loglevel. If LilyPond is called without an explicit loglevel (i.e. +no @option{--loglevel} command line option), this value is used. + @item LILYPOND_GC_YIELD -With this variable the memory footprint and performance can be -adjusted. It is a percentage tunes memory management behavior. With -higher values, the program uses more memory, with smaller values, it -uses more CPU time. The default value is @code{70}. +A variable, as a percentage, that tunes memory management +behavior. A higher values means the program uses more memory, a +smaller value means more CPU time is used. The default value is +@code{70}. @end table +@node LilyPond in chroot jail +@unnumberedsubsec LilyPond in chroot jail + +Setting up the server to run LilyPond in a chroot jail is a complicated +task. The steps are listed below. Examples in the steps are from +Ubuntu Linux, and may require the use of @code{sudo} as appropriate. + +@itemize + +@item Install the necessary packages: LilyPond, GhostScript, and ImageMagick. + +@item Create a new user by the name of @code{lily}: + +@example +adduser lily +@end example + +@noindent +This will create a new group for the @code{lily} user as well, and a home folder, +@code{/home/lily} + +@item In the home folder of the @code{lily} user create a file to use as a +separate filesystem: + +@example +dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000 +@end example + +@noindent +This example creates a 200MB file for use as the jail filesystem. + +@item Create a loop device, make a file system and mount it, then create +a folder that can be written by the @code{lily} user: + +@example +mkdir /mnt/lilyloop +losetup /dev/loop0 /home/lily/loopfile +mkfs -t ext3 /dev/loop0 200000 +mount -t ext3 /dev/loop0 /mnt/lilyloop +mkdir /mnt/lilyloop/lilyhome +chown lily /mnt/lilyloop/lilyhome +@end example + +@item In the configuration of the servers, the JAIL will be @code{/mnt/lilyloop} +and the DIR will be @code{/lilyhome}. + +@item Create a big directory tree in the jail by copying the necessary files, as +shown in the sample script below. + +You can use @code{sed} to create the necessary copy commands for a given +executable: + +@example +for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/; \ + do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& \ + cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \ + \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done +@end example + +@end itemize + +@subheading Example script for 32-bit Ubuntu 8.04 + +@example +#!/bin/sh +## defaults set here + +username=lily +home=/home +loopdevice=/dev/loop0 +jaildir=/mnt/lilyloop +# the prefix (without the leading slash!) +lilyprefix=usr/local +# the directory where lilypond is installed on the system +lilydir=/$lilyprefix/lilypond/ + +userhome=$home/$username +loopfile=$userhome/loopfile +adduser $username +dd if=/dev/zero of=$loopfile bs=1k count=200000 +mkdir $jaildir +losetup $loopdevice $loopfile +mkfs -t ext3 $loopdevice 200000 +mount -t ext3 $loopdevice $jaildir +mkdir $jaildir/lilyhome +chown $username $jaildir/lilyhome +cd $jaildir + +mkdir -p bin usr/bin usr/share usr/lib usr/share/fonts $lilyprefix tmp +chmod a+w tmp + +cp -r -L $lilydir $lilyprefix +cp -L /bin/sh /bin/rm bin +cp -L /usr/bin/convert /usr/bin/gs usr/bin +cp -L /usr/share/fonts/truetype usr/share/fonts + +# Now the library copying magic +for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh" \ + "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=> \ + \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed \ + 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' \ + | sed '/.*=>.*/d'; done | sh -s + +# The shared files for ghostscript... + cp -L -r /usr/share/ghostscript usr/share +# The shared files for ImageMagick + cp -L -r /usr/lib/ImageMagick* usr/lib + +### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome, +### you should be able to run: +### Note that /$lilyprefix/bin/lilypond is a script, which sets the +### LD_LIBRARY_PATH - this is crucial + /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly +@end example + +@c " keep quote signs balanced for context-sensitive editors + @node Error messages @section Error messages @@ -446,8 +645,8 @@ happens rarely. The most usual cause is misinstalled fonts. @cindex call trace @cindex Scheme error Errors that occur while executing Scheme code are caught by the Scheme -interpreter. If running with the verbose option (@code{-V} or -@code{--verbose}) then a call trace of the offending +interpreter. If running with the verbose option (@option{-V} or +@option{--verbose}) then a call trace of the offending function call is printed. @item Programming error @@ -506,6 +705,7 @@ are easily handled. * Apparent error in ../ly/init.ly:: * Error message Unbound variable %:: * Error message FT_Get_Glyph_Name:: +* Warning staff affinities should only decrease:: @end menu @node Music runs off the page @@ -537,17 +737,17 @@ line to break. For details, see @ruser{Bar lines}. @node An extra staff appears @unnumberedsubsec An extra staff appears -If contexts are not created explicitly with @code{\new} they will be -silently created as soon as a command is encountered which cannot -be applied to an existing context. In simple scores the automatic -creation of contexts is useful, and most of the examples in the -LilyPond manuals take advantage of this simplification. But -occasionally the silent creation of contexts can give rise to -unexpected new staves or scores. For example, it might be expected -that the following code would cause all note heads within the -following staff to be colored red, but in fact it results in two -staves with the note heads remaining the default black in the lower -staff. +If contexts are not created explicitly with @code{\new} or +@code{\context}, they will be silently created as soon as a +command is encountered which cannot be applied to an existing +context. In simple scores the automatic creation of contexts is +useful, and most of the examples in the LilyPond manuals take +advantage of this simplification. But occasionally the silent +creation of contexts can give rise to unexpected new staves or +scores. For example, it might be expected that the following code +would cause all note heads within the following staff to be +colored red, but in fact it results in two staves with the note +heads remaining the default black in the lower staff. @lilypond[quote,verbatim,relative=2] \override Staff.NoteHead #'color = #red @@ -568,23 +768,25 @@ correct code to color all note heads red is @end lilypond As a second example, if a @code{\relative} command is placed inside -a @code{\repeat} command two staves result, the second offset from +a @code{\repeat} command, two staves result, the second offset from the first, because the @code{\repeat} command generates two @code{\relative} blocks, which each implicitly create @code{Staff} and @code{Voice} blocks. @lilypond[quote,verbatim] \repeat unfold 2 { - \relative c' { c d e f } + \relative c' { c4 d e f } } @end lilypond -The correct way is to reverse the @code{\repeat} and -@code{\relative} commands, like this: +Explicitly instantiating the @code{Voice} context fixes the +problem: @lilypond[quote,verbatim] -\relative c' { - \repeat unfold 2 { c d e f } +\new Voice { + \repeat unfold 2 { + \relative c' { c4 d e f } + } } @end lilypond @@ -593,7 +795,7 @@ The correct way is to reverse the @code{\repeat} and @unnumberedsubsec Apparent error in @code{../ly/init.ly} Various obscure error messages may appear about syntax errors in -@code{../ly/init.ly} if the input file is not correctly formed, +@file{../ly/init.ly} if the input file is not correctly formed, for example, if it does not contain correctly matched braces or quote signs. @@ -609,7 +811,7 @@ of a lyrics block and the terminating brace, (@code{@}}). Without this separation the brace is taken to be part of the syllable. It is always advisable to ensure there is white space before and after @emph{every} brace. For the importance of this when using lyrics, -see @ruser{Lyrics explained}. +see @ruser{Entering lyrics}. This error message can also appear if a terminating quote sign, (@code{"}), is omitted. In this case an accompanying error message @@ -621,7 +823,7 @@ mismatched quote will usually be on the line one or two above. @unnumberedsubsec Error message Unbound variable % This error message will appear at the bottom of the console -output or log file together with a @qq{GUILE signalled an error ...} +output or log file together with a @qq{GUILE signalled an error @dots{}} message every time a Scheme routine is called which (invalidly) contains a @emph{LilyPond} rather than a @emph{Scheme} comment. @@ -637,182 +839,18 @@ an input file contains a non-ASCII character and was not saved in UTF-8 encoding. For details, see @ruser{Text encoding}. -@node Point and click -@section Point and click - -@cindex point and click - -Point and click lets you find notes in the input by clicking on them -in the PDF viewer. This makes it easier to find input that causes -some error in the sheet music. - -When this functionality is active, LilyPond adds hyperlinks to the PDF -file. These hyperlinks are sent to the web-browser, which opens a -text-editor with the cursor in the right place. - -To make this chain work, you should configure your PDF viewer to -follow hyperlinks using the @file{lilypond-invoke-editor} script -supplied with LilyPond. - -For Xpdf on UNIX, the following should be present in -@file{xpdfrc}@footnote{On UNIX, this file is found either in -@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.} - -@example -urlCommand "lilypond-invoke-editor %s" -@end example - -The program @file{lilypond-invoke-editor} is a small helper -program. It will invoke an editor for the special @code{textedit} -URIs, and run a web browser for others. It tests the environment -variable @code{EDITOR} for the following patterns, - -@table @code -@item emacs - this will invoke -@example -emacsclient --no-wait +@var{line}:@var{column} @var{file} -@end example -@item gvim - this will invoke -@example -gvim --remote +:@var{line}:norm@var{column} @var{file} -@end example - -@item nedit -this will invoke -@example - nc -noask +@var{line} @var{file}' -@end example -@end table - -The environment variable @code{LYEDITOR} is used to override this. It -contains the command line to start the editor, where @code{%(file)s}, -@code{%(column)s}, @code{%(line)s} is replaced with the file, column -and line respectively. The setting - -@example -emacsclient --no-wait +%(line)s:%(column)s %(file)s -@end example - -@noindent -for @code{LYEDITOR} is equivalent to the standard emacsclient -invocation. - - -@cindex file size, output - -The point and click links enlarge the output files significantly. For -reducing the size of PDF and PS files, point and click may be switched -off by issuing - -@example -\pointAndClickOff -@end example - -@noindent -in a @file{.ly} file. Point and click may be explicitly enabled with - -@example -\pointAndClickOn -@end example - -Alternately, you may disable point and click with a command-line -option: +@node Warning staff affinities should only decrease +@unnumberedsubsec Warning staff affinities should only decrease +This warning can appear if there are no staves in the printed +output, for example if there are just a @code{ChordName} context +and a @code{Lyrics} context as in a lead sheet. The warning +messages can be avoided by making one of the contexts behave as a +staff by inserting @example -lilypond -dno-point-and-click file.ly -@end example - -@warning{You should always turn off point and click in any LilyPond -files to be distributed to avoid including path information about -your computer in the .pdf file, which can pose a security risk.} -@node Text editor support -@section Text editor support - -@cindex editors -@cindex vim -@cindex emacs -@cindex modes, editor -@cindex syntax coloring -@cindex coloring, syntax - -There is support for different text editors for LilyPond. - -@menu -* Emacs mode:: -* Vim mode:: -* Other editors:: -@end menu - -@node Emacs mode -@unnumberedsubsec Emacs mode - -Emacs has a @file{lilypond-mode}, which provides keyword -autocompletion, indentation, LilyPond specific parenthesis matching -and syntax coloring, handy compile short-cuts and reading LilyPond -manuals using Info. If @file{lilypond-mode} is not installed on your -platform, see below. - -An Emacs mode for entering music and running LilyPond is contained in -the source archive in the @file{elisp} directory. Do @command{make -install} to install it to @var{elispdir}. The file @file{lilypond-init.el} -should be placed to @var{load-path}@file{/site-start.d/} or appended -to your @file{~/.emacs} or @file{~/.emacs.el}. - -As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to -your @var{load-path} by appending the following line (as modified) to your -@file{~/.emacs} - -@c any reason we do not advise: (push "~/site-lisp" load-path) -@example -(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path)) -@end example - - -@node Vim mode -@unnumberedsubsec Vim mode - -For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, -along with syntax coloring tools. A Vim mode for entering music and -running LilyPond is contained in the source archive in @code{$VIM} -directory. - -The LilyPond file type is detected if the file -@file{~/.vim/filetype.vim} has the following content - -@example -if exists("did_load_filetypes") - finish -endif -augroup filetypedetect - au! BufNewFile,BufRead *.ly,*.ily setf lilypond -augroup END -@end example - -Please include this path by appending the following line to your -@file{~/.vimrc} - -@example -set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/ +\override VerticalAxisGroup #'staff-affinity = ##f @end example @noindent -where $@{LILYPOND_VERSION@} is your LilyPond version. If LilyPond was not -installed in @file{/usr/local/}, then change this path accordingly. -The path may differ significantly. In Fedora the path leads to the -current version of Vim instead of Lilypond: - -@example -set runtimepath+=/usr/share/vim/vim72/ -@end example - - -@node Other editors -@unnumberedsubsec Other editors - -Other editors (both text and graphical) support LilyPond, but -their special configuration files are not distributed with -LilyPond. Consult their documentation for more information. Such -editors are listed in @rweb{Alternate editors}. - +at its start. For details, see @qq{Spacing of non-staff lines} in +@ruser{Flexible vertical spacing within systems}.