X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Frunning.itely;h=7522cec85b74b3aca677cd51454e89a81e985751;hb=38e1cad48d14f0b0f9286b4bb8891051a5f82d1e;hp=263a7e8c9b76a8489a3a496cc5480c679f82d4fa;hpb=199c0c3722ab9920ee941d7086e81b1f887b14bf;p=lilypond.git diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely index 263a7e8c9b..7522cec85b 100644 --- a/Documentation/usage/running.itely +++ b/Documentation/usage/running.itely @@ -8,7 +8,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.12.0" +@c \version "2.15.18" @node Running lilypond @@ -53,7 +53,8 @@ if you are unfamiliar with the command-line. @menu * Invoking lilypond:: -* Command line options for lilypond:: +* Basic command line options for LilyPond:: +* Advanced command line options for LilyPond:: * Environment variables:: * LilyPond in chroot jail:: @end menu @@ -97,8 +98,32 @@ will output @var{base}@file{-violin.pdf} and @var{base}@file{-cello-1.pdf}. -@node Command line options for lilypond -@unnumberedsubsec Command line options for @command{lilypond} +@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 Basic command line options for LilyPond +@unnumberedsubsec Basic command line options for LilyPond @cindex Invoking @command{lilypond} @cindex command line options for @command{lilypond} @@ -109,9 +134,15 @@ The following options are supported: @table @code +@item -d,--define-default=@var{var}=@var{val} +See @ref{Advanced command line options for LilyPond}. + +@cindex Scheme, expression evaluation +@cindex expression evaluation, Scheme + @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 @@ -131,283 +162,534 @@ on the command-line, and include @noindent at the top of the @code{.ly} file. +@warning{Windows users must use double quotes instead of single quotes.} + +@cindex output, format +@cindex format, output + @item -f,--format=@var{format} which formats should be written. Choices for @code{format} are @code{ps}, @code{pdf}, and @code{png}. Example: @code{lilypond -fpng @var{filename}.ly} +@item -h,--help +Show a summary of usage. +@item -H,--header=@var{FIELD} +Dump a header field to file @file{BASENAME.@var{FIELD}}. -@item -d,--define-default=@var{var}=@var{val} -This sets the internal program option @var{var} to the Scheme value -@var{val}. If @var{val} is not supplied, then @var{#t} is used. To -switch off an option, @code{no-} may be prefixed to @var{var}, e.g. - -@cindex point and click, command line - -@example --dno-point-and-click -@end example - -@noindent -is the same as -@example --dpoint-and-click='#f' -@end example +@item -i,--init=@var{file} +Set init file to @var{file} (default: @file{init.ly}). -Here are a few interesting options. +@cindex file searching +@cindex search path -@cindex help, command line +@item -I, --include=@var{directory} +Add @var{directory} to the search path for input files. -@table @samp -@item help -Running @code{lilypond -dhelp} will print all of the @code{-d} options -available. +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. -@cindex paper-size, command line +@cindex chroot jail, running inside -@item paper-size -This option sets the default paper-size, -@example --dpaper-size=\"letter\" -@end example +@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir} +Run @command{lilypond} in a chroot jail. -@noindent -Note that the string must be enclosed in escaped quotes ( @code{\"} ). -@c Match " in previous line to help context-sensitive editors +The @option{--jail} option provides a more flexible alternative to +@option{-dsafe}, when LilyPond formatting is being provided via a web +server, or whenever LilyPond executes commands sent by external sources +(see @ref{Advanced command line options for LilyPond}). + +It 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 @option{--jail} +to work, @command{lilypond} must be run as root, which is usually +accomplished in a safe way using @command{sudo}. -@cindex safe, command line +Setting up a jail can be a relatively complex matter, as we must be sure +that LilyPond is able to find whatever it needs to compile the source +@emph{inside} the jail itself. A typical chroot jail will comprise the +following steps: -@item safe -Do not trust the @code{.ly} input. +@table @asis -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 -havoc, for example +@item Setting up a separate filesystem +A separate filesystem should be created for LilyPond, so that it can be +mounted with safe options such as @code{noexec}, @code{nodev}, and +@code{nosuid}. In this way, it is impossible to run executables or to +write directly to a device from LilyPond. If you do not want to create a +separate partition, just create a file of reasonable size and use it to +mount a loop device. A separate filesystem also guarantees that LilyPond +cannot write more space than it is allowed. -@quotation -@verbatim -#(system "rm -rf /") -{ - c4^#(ly:export (ly:gulp-file "/etc/passwd")) -} -@end verbatim -@end quotation +@item Setting up a separate user +A separate user and group (say, @code{lily}/@code{lily}) with low +privileges should be used to run LilyPond inside the jail. There should +be a single directory writable by this user, which should be passed in +@var{dir}. -The @code{-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}. +@item Preparing the jail +LilyPond needs to read a number of files while running. All these files +are to be copied into the jail, under the same path they appear in the +real root filesystem. The entire content of the LilyPond installation +(e.g., @file{/usr/share/lilypond}) should be copied. -In addition, safe mode disallows @code{\include} directives and -disables the use of backslashes in @TeX{} strings. +If problems arise, the simplest way to trace them down is to run +LilyPond using @command{strace}, which will allow you to determine which +files are missing. -In safe mode, it is not possible to import LilyPond variables -into Scheme. +@item Running LilyPond +In a jail mounted with @code{noexec} it is impossible to execute any +external program. Therefore LilyPond must be run with a backend that +does not require any such program. As we have already mentioned, it +must be run with superuser privileges (which, of course, it will lose +immediately), possibly using @command{sudo}. It is also good practice +to limit the number of seconds of CPU time LilyPond can use (e.g., using +@command{ulimit@tie{}-t}), and, if your operating system supports it, +the amount of memory that can be allocated. Also see +@ref{LilyPond in chroot jail}. +@end table -@code{-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. +@cindex loglevel +@cindex output, verbosity -The safe mode will prevent many useful LilyPond snippets from being -compiled. The @code{--jail} is a more secure alternative, but -requires more work to set up. +@item -l,--loglevel=@var{LEVEL} +Set the verbosity of the console output to @var{LEVEL}. Possible values +are: -@cindex output format, setting -@item backend -the output format to use for the back-end. Choices for @code{format} are @table @code -@item ps -@cindex PostScript output - for PostScript. - - Postscript files include TTF, Type1 and OTF fonts. No subsetting of - these fonts is done. When using oriental character sets, this can - lead to huge files. -@item eps +@item NONE +No output at all, not even error messages. -@cindex Postscript, encapsulated -@cindex EPS (Encapsulated PostScript) +@item ERROR +Only error messages, no warnings or progress messages. - for encapsulated PostScript. This dumps every page (system) as a separate -@file{EPS} file, without fonts, and as one collated @file{EPS} file with -all pages (systems) including fonts. +@item WARN +Warnings and error messages, no progress. -This mode is used by default by @command{lilypond-book}. +@item BASIC_PROGRESS +Basic progress messages (success), warnings and errors. -@item svg +@item PROGRESS +All progress messages, warnings and errors. -@cindex SVG (Scalable Vector Graphics) +@item INFO (default) +Progress messages, warnings, errors and further execution information. - for SVG (Scalable Vector Graphics). +@item DEBUG +All possible messages, including verbose debug output. - This creates a single SVG file, without embedded fonts, for every - page of output. It is recommended to install the Century - Schoolbook fonts, included with your LilyPond installation, for - optimal rendering. Under UNIX, simply copy these fonts from the - LilyPond directory (typically - @file{/usr/share/lilypond/VERSION/fonts/otf/}) to - @file{~/.fonts/}. The SVG output should be compatible with any - SVG editor or user agent. +@end table -@item scm +@cindex directory, redirect output +@cindex output, setting filename +@cindex output, directory -@cindex Scheme dump +@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. - for a dump of the raw, internal Scheme-based drawing commands. +@cindex PS (Postscript), output +@cindex Postscript (PS), output +@cindex output, PS (Postscript) -@item null - do not output a printed score; has the same effect as @code{-dno-print-pages}. -@end table +@item --ps +Generate PostScript. -Example: @code{lilypond -dbackend=svg @var{filename}.ly} +@cindex PNG (Portable Network Graphics), output +@cindex output, PNG (Portable Network Graphics) -@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 --png +Generate pictures of each page, in PNG format. This implies +@option{--ps}. The resolution in DPI of the image may be set with +@example +-dresolution=110 +@end example -@item print-pages -Generate the full pages, the default. @code{-dno-print-pages} is -useful in combination with @code{-dpreview}. +@cindex PDF (Portable Document Format), output +@cindex output, PDF (Portable Document Format) -@end table +@item --pdf +Generate PDF. This implies @option{--ps}. +@item -v,--version +Show version information. +@item -V,--verbose +Be verbose: show full paths of all files read, and give timing +information. -@item -h,--help -Show a summary of usage. +@item -w,--warranty +Show the warranty with which GNU LilyPond comes. (It comes with +@strong{NO WARRANTY}!) -@item -H,--header=@var{FIELD} -Dump a header field to file @file{BASENAME.@var{FIELD}}. +@end table -@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. +@node Advanced command line options for LilyPond +@unnumberedsubsec Advanced command line options for LilyPond -@item -i,--init=@var{file} -Set init file to @var{file} (default: @file{init.ly}). +@table @code -@cindex folder, directing output to -@cindex output filename, setting +@item -d@var{[option-name]}=@var{[value]},--define-default=@var{[option-name]}=@var{[value]} +This sets the equivalent internal Scheme function to @var{value}. If a +@var{value} is not supplied, then the default value is used. The prefix +@code{no-} may be added to @var{option-name} to switch @q{off} an +option, e.g. -@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 point and click, command line +@example +-dpoint-and-click=#f +@end example -@cindex PostScript output +@noindent +is the same as +@example +-dno-point-and-click +@end example +@end table -@item --ps -Generate PostScript. +@noindent The following are supported along with their respective +default values: + +@multitable @columnfractions .33 .16 .51 +@item @strong{Symbol} +@tab @strong{Value} +@tab @strong{Explanation/Options} + +@item @code{anti-alias-factor} +@tab @code{1} +@tab Render at higher resolution (using given factor) and scale down +result to prevent @q{jaggies} in @code{PNG} images. + +@item @code{aux-files} +@tab @code{#t} +@tab Create @code{.tex}, @code{.texi}, @code{.count} files in the +@code{EPS} backend. + +@item @code{backend} +@tab @code{'ps} +@tab Select backend. Postscript files (default) include @code{TTF}, +@code{Type1} and @code{OTF} fonts. No subsetting of these fonts is +done. Using @q{oriental} character sets can lead to very large files. + +@item +@tab @code{'eps} +@tab Encapsulated PostScript. This dumps every page (system) as a +separate @file{EPS} file, without fonts, and as one collated @file{EPS} +file with all pages (systems) including fonts. Used as default by +@command{lilypond-book}. + +@item +@tab @code{'null} +@tab Do not output a printed score; has the same effect as +@code{-dno-print-pages}. + +@item +@tab @code{'svg} +@tab Scalable Vector Graphics. This creates a single @code{SVG} file, +without embedded fonts, for every page of output. It is recommended to +install the Century Schoolbook fonts, included with your LilyPond +installation, for optimal rendering. Under UNIX, simply copy these +fonts from the LilyPond directory (typically +@file{/usr/share/lilypond/VERSION/fonts/otf/}) to @file{~/.fonts/}. The +@code{SVG} output should be compatible with any SVG editor or user +agent. There is also an option @code{svg-woff} (below) for use of woff +font files in the SVG backend. + +@item +@tab @code{'scm} +@tab Dump of the raw, internal Scheme-based drawing commands. + +@item @code{check-internal-types} +@tab @code{#f} +@tab Check every property assignment for types. + +@item @code{clip-systems} +@tab @code{#f} +@tab Generate cut-out snippets of a score. + +@item @code{datadir} +@tab +@tab Prefix for data files (read-only). + +@item @code{debug-gc} +@tab @code{#f} +@tab Dump memory debugging statistics. + +@item @code{debug-gc-assert-parsed-dead} +@tab @code{#f} +@tab For memory debugging: Ensure that all references to parsed objects +are dead. This is an internal option, and is switched on automatically +for @code{`-ddebug-gc'}. + +@item @code{debug-lexer} +@tab @code{#f} +@tab Debug the flex lexer. + +@item @code{debug-page-breaking-scoring} +@tab @code{#f} +@tab Dump scores for many different page breaking configurations. + +@item @code{debug-parser} +@tab @code{#f} +@tab Debug the bison parser. + +@item @code{debug-property-callbacks} +@tab @code{#f} +@tab Debug cyclic callback chains. + +@item @code{debug-skylines} +@tab @code{#f} +@tab Debug skylines. + +@item @code{delete-intermediate-files} +@tab @code{#t} +@tab Delete the unusable, intermediate @code{.ps} files created during +compilation. + +@item @code{dump-cpu-profile} +@tab @code{#f} +@tab Dump timing information (system-dependent). + +@item @code{dump-profile} +@tab @code{#f} +@tab Dump memory and time information for each file. + +@item @code{dump-signatures} +@tab @code{#f} +@tab Dump output signatures of each system. Used for regression testing. + +@item @code{eps-box-padding} +@tab @code{#f} +@tab Pad left edge of the output EPS bounding box by the given amount +(in mm). + +@item @code{gs-load-fonts} +@tab @code{#f} +@tab Load fonts via Ghostscript. + +@item @code{gs-load-lily-fonts} +@tab @code{#f} +@tab Load only the LilyPond fonts via Ghostscript. + +@item @code{gui} +@tab @code{#f} +@tab Runs silently and redirect all output to a log file. +@end multitable -@cindex Portable Network Graphics (PNG) output +@noindent +@strong{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. + +@multitable @columnfractions .33 .16 .51 +@item @code{help} +@tab @code{#f} +@tab Show this help. + +@item @code{include-book-title-preview} +@tab @code{#t} +@tab Include book titles in preview images. + +@item @code{include-eps-fonts} +@tab @code{#t} +@tab Include fonts in separate-system EPS files. + +@item @code{include-settings} +@tab @code{#f} +@tab Include file for global settings, this is included before the score +is processed. + +@item @code{job-count} +@tab @code{#f} +@tab Process in parallel, using the given number of jobs. + +@item @code{log-file} +@tab @code{#f [file]} +@tab If string @code{FOO} is given as a second argument, +redirect output to the log file @code{FOO.log}. + +@item @code{max-markup-depth} +@tab @code{1024} +@tab Maximum depth for the markup tree. If a markup has more levels, +assume it will not terminate on its own, print a warning and return a +null markup instead. + +@item @code{midi-extension} +@tab @code{"midi"} +@tab Set the default file extension for MIDI output file to given +string. + +@item @code{music-strings-to-paths} +@tab @code{#f} +@tab Convert text strings to paths when glyphs belong to a music font. + +@item @code{old-relative} +@tab @code{#f} +@tab Make @code{\relative} mode for simultaneous music work similar to +chord syntax. + +@item @code{paper-size} +@tab @code{\"a4\"} +@tab Set default paper size. Note the string must be enclosed in +escaped double quotes. + +@item @code{pixmap-format} +@tab @code{png16m} +@tab Set GhostScript's output format for pixel images. + +@item @code{point-and-click} +@tab @code{#f} +@tab Add @q{point & click} links to @code{PDF} output. See +@ref{Point and click}. + +@item @code{preview} +@tab @code{#f} +@tab Create preview images in addition to normal output. +@end multitable -@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 -@example --dresolution=110 -@end example +@noindent +This option is supported by all backends; @code{pdf}, @code{png}, +@code{ps}, @code{eps} and @code{svg}, but not @code{scm}. It generates +an output file, in the form @code{myFile.preview.extension}, containing +the titles and the first system of music. If @code{\book} or +@code{\bookpart} blocks are used, the titles of @code{\book}, +@code{\bookpart} or @code{\score} will appear in the output, including +the first system of every @code{\score} block if the @code{\paper} +variable @code{print-all-headers} is set to @code{#t}. + +To suppress the usual output, use the @option{-dprint-pages} or +@option{-dno-print-pages} options according to your requirements. + +@multitable @columnfractions .33 .16 .51 +@item @code{print-pages} +@tab @code{#t} +@tab Generate full pages, the default. @option{-dno-print-pages} is +useful in combination with @option{-dpreview}. + +@item @code{profile-property-accesses} +@tab @code{#f} +@tab Keep statistics of @code{get_property()} function calls. + +@item @code{protected-scheme-parsing} +@tab @code{#t} +@tab Continue when errors in inline scheme are caught in the parser. If +set to @code{#f}, halt on errors and print a stack trace. + +@item @code{read-file-list} +@tab @code{#f [file]} +@tab Specify name of a file which contains a list of input files to be +processed. + +@item @code{relative-includes} +@tab @code{#f} +@tab When processing an @code{\include} command, look for the included +file relative to the current file (instead of the root file). + +@item @code{resolution} +@tab @code{101} +@tab Set resolution for generating @code{PNG} pixmaps to given value (in +dpi). + +@item @code{safe} +@tab @code{#f} +@tab Do not trust the @code{.ly} input. +@end multitable -@cindex Portable Document Format (PDF) output +@noindent +When LilyPond formatting is available through a web server, either the +@option{--safe} or the @option{--jail} option @b{MUST} be passed. The +@option{--safe} option will prevent inline Scheme code from wreaking +havoc, e.g, -@item --pdf -Generate PDF. This implies @code{--ps}. +@quotation +@verbatim +#(system "rm -rf /") +{ + c4^$(ly:gulp-file "/etc/passwd") +} +@end verbatim +@end quotation +The @option{-dsafe} option works by evaluating in-line Scheme +expressions in a special safe module. This is derived from GUILE +@file{safe-r5rs} module, but also adds a number of functions of the +LilyPond API which 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. It is also not +possible to import LilyPond variables into Scheme while in safe mode. -@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir} -Run @command{lilypond} in a chroot jail. +@option{-dsafe} does @emph{not} detect resource overuse, so 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 @code{--jail} option provides a more flexible alternative to -@code{--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 -@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 -accomplished in a safe way using @command{sudo}. +Safe mode will prevent many useful LilyPond snippets from being +compiled. -Setting up a jail is a slightly delicate matter, as we must be sure that -LilyPond is able to find whatever it needs to compile the source -@emph{inside the jail}. A typical setup comprises the following items: +The @option{--jail} is an even more secure alternative, but requires +more work to set up. See @ref{Basic command line options for LilyPond}. -@table @asis -@item Setting up a separate filesystem -A separate filesystem should be created for LilyPond, so that it can be -mounted with safe options such as @code{noexec}, @code{nodev}, and -@code{nosuid}. In this way, it is impossible to run executables or to -write directly to a device from LilyPond. If you do not want to create a -separate partition, just create a file of reasonable size and use it to -mount a loop device. A separate filesystem also guarantees that LilyPond -cannot write more space than it is allowed. +@multitable @columnfractions .33 .16 .51 +@item @code{separate-log-files} +@tab @code{#f} +@tab For input files @code{FILE1.ly}, @code{FILE2.ly}, etc. output log +data to files @code{FILE1.log}, @code{FILE2.log}, ... -@item Setting up a separate user -A separate user and group (say, @code{lily}/@code{lily}) with low -privileges should be used to run LilyPond inside the jail. There should -be a single directory writable by this user, which should be passed in -@var{dir}. +@item @code{show-available-fonts} +@tab @code{#f} +@tab List available font names. -@item Preparing the jail -LilyPond needs to read a number of files while running. All these files -are to be copied into the jail, under the same path they appear in the -real root filesystem. The entire content of the LilyPond installation -(e.g., @file{/usr/share/lilypond}) -should be copied. +@item @code{strict-infinity-checking} +@tab @code{#f} +@tab Force a crash on encountering @code{Inf} and @code{NaN} floating +point exceptions. -If problems arise, the simplest way to trace them down is to run -LilyPond using @command{strace}, which will allow you to determine which -files are missing. +@item @code{strip-output-dir} +@tab @code{#t} +@tab Don't use directories from input files while constructing output +file names. -@item Running LilyPond -In a jail mounted with @code{noexec} it is impossible to execute any external -program. Therefore LilyPond must be run with a backend that does not -require any such program. As we already mentioned, it must be also run -with superuser privileges (which, of course, it will lose immediately), -possibly using @command{sudo}. It is a good idea to limit the number of -seconds of CPU time LilyPond can use (e.g., using @command{ulimit --t}), and, if your operating system supports it, the amount of memory -that can be allocated. -@end table +@item @code{svg-woff} +@tab @code{#f} +@tab Use woff font files in SVG backend. +@item @code{trace-memory-frequency} +@tab @code{#f} +@tab Record Scheme cell usage this many times per second. Dump the +results to @code{FILE.stacks} and @code{FILE.graph}. -@item -v,--version -Show version information. +@item @code{trace-scheme-coverage} +@tab @code{#f} +@tab Record coverage of Scheme files in @code{FILE.cov}. -@item -V,--verbose -Be verbose: show full paths of all files read, and give timing -information. +@item @code{verbose} +@tab @code{#f} +@tab Verbose output, i.e. loglevel at DEBUG (read-only). -@item -w,--warranty -Show the warranty with which GNU LilyPond comes. (It comes with -@strong{NO WARRANTY}!) -@end table +@item @code{warning-as-error} +@tab @code{#f} +@tab Change all warning and @q{programming error} messages into errors. +@end multitable @node Environment variables @unnumberedsubsec Environment variables - @cindex LANG @cindex LILYPOND_DATADIR @@ -421,11 +703,15 @@ 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 @@ -448,8 +734,8 @@ 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} +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: @@ -483,7 +769,10 @@ 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 +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 @@ -524,18 +813,25 @@ 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 +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 +### 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 @@ -568,8 +864,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 @@ -587,9 +883,8 @@ send a bug-report. @end table @cindex errors, message format -If warnings and errors can -be linked to some part of the input file, then error messages have the -following form +If warnings and errors can be linked to some part of the input file, +then error messages have the following form @example @var{filename}:@var{lineno}:@var{columnno}: @var{message} @@ -628,6 +923,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 @@ -717,7 +1013,7 @@ problem: @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. @@ -733,7 +1029,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 @@ -745,7 +1041,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. @@ -761,4 +1057,18 @@ an input file contains a non-ASCII character and was not saved in UTF-8 encoding. For details, see @ruser{Text encoding}. +@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 +\override VerticalAxisGroup #'staff-affinity = ##f +@end example + +@noindent +at its start. For details, see @qq{Spacing of non-staff lines} in +@ruser{Flexible vertical spacing within systems}.