X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Frunning.itely;h=01784ab75ab750ac588833982d77c9d254097fe6;hb=0b58c7d1f556ce0a62c3bcdce172e0f4fe9d19f0;hp=c14d8c51b65e39966d003dcfe37b54f35cab011c;hpb=0036a17de19acc4314771a6c745c5786f3b2b41f;p=lilypond.git diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely index c14d8c51b6..01784ab75a 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.14.0" +@c \version "2.17.6" @node Running lilypond @@ -52,13 +52,14 @@ scope of this manual; please consult other documentation on this topic if you are unfamiliar with the command-line. @menu -* Invoking lilypond:: -* Command line options for lilypond:: +* Invoking LilyPond:: +* Basic command line options for LilyPond:: +* Advanced command line options for LilyPond:: * Environment variables:: * LilyPond in chroot jail:: @end menu -@node Invoking lilypond +@node Invoking LilyPond @unnumberedsubsec Invoking @command{lilypond} The @command{lilypond} executable may be called as follows from @@ -68,7 +69,6 @@ the command line. lilypond [@var{option}]@dots{} @var{file}@dots{} @end example - When invoked with a filename that has no extension, the @file{.ly} extension is tried first. To read input from stdin, use a dash (@code{-}) for @var{file}. @@ -97,250 +97,217 @@ 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} - -@cindex Invoking @command{lilypond} -@cindex command line options for @command{lilypond} -@cindex options, command line -@cindex switches - -The following options are supported: +@unnumberedsubsubsec Using LilyPond with standard shell features -@table @code +Since LilyPond is a command line application, features of the @q{shell} +used for calling LilyPond can also be put to good use. -@item -e,--evaluate=@var{expr} -Evaluate the Scheme @var{expr} before parsing any @file{.ly} files. -Multiple @option{-e} options may be given, they will be evaluated -sequentially. - -The expression will be evaluated in the @code{guile-user} module, so -if you want to use definitions in @var{expr}, use +For example: @example -lilypond -e '(define-public a 42)' +lilypond *.ly @end example @noindent -on the command-line, and include +will process all LilyPond files in the current directory. -@example -#(use-modules (guile-user)) -@end example +Redirecting the console output (e.g. to a file) may also be useful: -@noindent -at the top of the @code{.ly} file. - -@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} +@example +lilypond file.ly 1> stdout.txt +lilypond file.ly 2> stderr.txt +lilypond file.ly &> all.txt +@end example -@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. +@noindent +Redirects @q{normal} output, @q{errors} only or @q{everything}, +respectively, to a text file. Consult the documentation for your +particular shell, Command (Windows), Terminal or Console +applications (MacOS X) to see if output redirection is supported or if +the syntax is different. -@cindex point and click, command line +The following example searches and processes all input files in the +current directory and all directories below it recursively. The output +files will be located in the same directory that the command was run in, +rather than in the same directories as the original input files. @example --dno-point-and-click +find . -name '*.ly' -exec lilypond '@{@}' \; @end example @noindent -is the same as -@example --dpoint-and-click='#f' -@end example - -Here are a few interesting options. - -@cindex help, command line +This should also work for MacOS@tie{}X users. -@table @samp -@item help -Running @code{lilypond -dhelp} will print all of the @option{-d} options -available. +A Windows user would run; -@cindex paper-size, command line - -@item paper-size -This option sets the default paper-size, @example --dpaper-size=\"letter\" +forfiles /s /M *.ly /c "cmd /c lilypond @@file" @end example @noindent -Note that the string must be enclosed in escaped quotes ( @code{\"} ). -@c Match " in previous line to help context-sensitive editors - -@cindex safe, command line +entering these commands in a @code{command prompt} usually found under +@code{Start > Accessories > Command Prompt} or for version 8 users, +by typing in the search window @q{command prompt}. -@item safe -Do not trust the @code{.ly} input. +Alternatively, an explicit path to the top-level of your folder +containing all the sub-folders that have input files in them can be +stated using the @code{/p} option; -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, for example +@example +forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c lilypond @@file" +@end example -@quotation -@verbatim -#(system "rm -rf /") -{ - c4^#(ly:export (ly:gulp-file "/etc/passwd")) -} -@end verbatim -@end quotation +If there are spaces in the path to the top-level folder, then the whole +path needs to be inside double quotes; -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}. +@example +forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c lilypond @@file" +@end example -In addition, safe mode disallows @code{\include} directives and -disables the use of backslashes in @TeX{} strings. -In safe mode, it is not possible to import LilyPond variables -into Scheme. +@node Basic command line options for LilyPond +@unnumberedsubsec Basic command line options for LilyPond -@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. +@cindex Invoking @command{lilypond} +@cindex command line options for @command{lilypond} +@cindex options, command line +@cindex switches -The safe mode will prevent many useful LilyPond snippets from being -compiled. The @option{--jail} is a more secure alternative, but -requires more work to set up. +The following options are supported: -@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 -d, --define-default=@var{var}=@var{val} +See @ref{Advanced command line options for LilyPond}. -@item eps +@cindex Scheme, expression evaluation +@cindex expression evaluation, Scheme -@cindex Postscript, encapsulated -@cindex EPS (Encapsulated PostScript) +@item -e, --evaluate=@var{expr} +Evaluate the Scheme @var{expr} before parsing any @file{.ly} files. +Multiple @option{-e} options may be given, they will be evaluated +sequentially. - 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. +The expression will be evaluated in the @code{guile-user} module, so +if you want to use definitions in @var{expr}, use -This mode is used by default by @command{lilypond-book}. +@example +lilypond -e '(define-public a 42)' +@end example -@item svg +@noindent +on the command-line, and include -@cindex SVG (Scalable Vector Graphics) +@example +#(use-modules (guile-user)) +@end example - for SVG (Scalable Vector Graphics). +@noindent +at the top of the @code{.ly} file. - 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. +@warning{Windows users must use double quotes instead of single quotes.} -@item scm +@cindex output, format +@cindex format, output -@cindex Scheme dump +@item -f, --format=@var{format} +which formats should be written. Choices for @code{format} are +@code{ps}, @code{pdf}, and @code{png}. - for a dump of the raw, internal Scheme-based drawing commands. +Example: @code{lilypond -fpng @var{filename}.ly} -@item null - do not output a printed score; has the same effect as @option{-dno-print-pages}. -@end table +@item -h, --help +Show a summary of usage. -Example: @code{lilypond -dbackend=svg @var{filename}.ly} +@item -H, --header=@var{FIELD} +Dump a header field to file @file{BASENAME.@var{FIELD}}. -@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 -i, --init=@var{file} +Set init file to @var{file} (default: @file{init.ly}). -@item gui -Runs silently and redirect all output to a log file. +@cindex file searching +@cindex search path -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 -I, --include=@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 print-pages -Generate the full pages, the default. @option{-dno-print-pages} is -useful in combination with @option{-dpreview}. +@cindex chroot jail, running inside -@end table +@item -j, --jail=@var{user},@var{group},@var{jail},@var{dir} +Run @command{lilypond} in a chroot jail. +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}. +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 -h,--help -Show a summary of usage. +@table @asis -@item -H,--header=@var{FIELD} -Dump a header field to file @file{BASENAME.@var{FIELD}}. +@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. -@cindex file searching -@cindex search path -@item --include, -I=@var{directory} -Add @var{directory} to the search path for input files. +@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 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. -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. +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 -i,--init=@var{file} -Set init file to @var{file} (default: @file{init.ly}). +@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 @cindex loglevel -@cindex output verbosity, setting +@cindex output, verbosity + +@item -l, --loglevel=@var{LEVEL} +Set the verbosity of the console output to @var{LEVEL}. Possible values +are: -@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. @@ -361,25 +328,28 @@ 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 +@end table -@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 directory, redirect output +@cindex output, setting filename +@cindex output, directory +@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 +@cindex PS (Postscript), output +@cindex Postscript (PS), output +@cindex output, PS (Postscript) @item --ps Generate PostScript. -@cindex Portable Network Graphics (PNG) output +@cindex PNG (Portable Network Graphics), output +@cindex output, PNG (Portable Network Graphics) @item --png Generate pictures of each page, in PNG format. This implies @@ -388,89 +358,395 @@ Generate pictures of each page, in PNG format. This implies -dresolution=110 @end example -@cindex Portable Document Format (PDF) output +@cindex PDF (Portable Document Format), output +@cindex output, PDF (Portable Document Format) @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 -j,--jail=@var{user},@var{group},@var{jail},@var{dir} -Run @command{lilypond} in a chroot jail. +@item -w, --warranty +Show the warranty with which GNU LilyPond comes. (It comes with +@strong{NO WARRANTY}!) -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 @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 -@option{--jail} to work @command{lilypond} must be run as root, which is usually -accomplished in a safe way using @command{sudo}. +@end table -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: -@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. +@node Advanced command line options for LilyPond +@unnumberedsubsec Advanced command line options for LilyPond -@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}. +@table @code -@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 -d@var{[option-name]}=@var{[value]},--define-default=@var{[option-name]}=@var{[value]} +This sets the equivalent internal Scheme function to @var{value}. -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. +@example +-dbackend=svg +@end example -@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. +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. + +@cindex point and click, command line + +@example +-dpoint-and-click=#f +@end example + +@noindent +is the same as +@example +-dno-point-and-click +@end example @end table +@noindent The following are supported along with their respective +default values: -@item -v,--version -Show version information. +@multitable @columnfractions .33 .16 .51 +@item @strong{Symbol} +@tab @strong{Value} +@tab @strong{Explanation/Options} -@item -V,--verbose -Be verbose: show full paths of all files read, and give timing -information. +@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 -w,--warranty -Show the warranty with which GNU LilyPond comes. (It comes with -@strong{NO WARRANTY}!) -@end table +@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 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/}. +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 Extract music fragments out of a score. This requires that the +@code{clip-regions} function has been defined within the @code{\layout} +block. See @ruser{Extracting fragments of music}. No fragments are +extracted though if used with the @option{-dno-print-pages} option. + +@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 + +@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{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{#t} +@tab Add @q{point & click} links to PDF and SVG output. +See @ref{Point and click}. + +@item @code{preview} +@tab @code{#f} +@tab Create preview images in addition to normal output. +@end multitable + +@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 + +@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, + +@quotation +@verbatim +#(s ystem "rm -rf /") % too dangerous to write correctly +{ + c4^$(ly:gulp-file "/etc/passwd") % malicious but not destructive +} +@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. + +@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. + +Safe mode will prevent many useful LilyPond snippets from being +compiled. + +The @option{--jail} is an even more secure alternative, but requires +more work to set up. See @ref{Basic command line options for LilyPond}. + +@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}@dots{} + +@item @code{show-available-fonts} +@tab @code{#f} +@tab List available font names. + +@item @code{strict-infinity-checking} +@tab @code{#f} +@tab Force a crash on encountering @code{Inf} and @code{NaN} floating +point exceptions. + +@item @code{strip-output-dir} +@tab @code{#t} +@tab Don't use directories from input files while constructing output +file names. + +@item @code{strokeadjust} +@tab @code{#f} +@tab Force PostScript stroke adjustment. This option is mostly +relevant when a PDF is generated from PostScript output (stroke +adjustment is usually enabled automatically for low-resolution bitmap +devices). Without this option, PDF previewers tend to produce widely +inconsistent stem widths at resolutions typical for screen display. The +option does not noticeably affect print quality and causes large file +size increases in PDF files. + +@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 @code{trace-scheme-coverage} +@tab @code{#f} +@tab Record coverage of Scheme files in @code{FILE.cov}. + +@item @code{verbose} +@tab @code{#f} +@tab Verbose output, i.e. loglevel at DEBUG (read-only). + +@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 @@ -485,8 +761,8 @@ subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc. 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. +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 A variable, as a percentage, that tunes memory management @@ -502,7 +778,7 @@ smaller value means more CPU time is used. The default value is 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. +Ubuntu GNU/Linux, and may require the use of @code{sudo} as appropriate. @itemize @@ -515,8 +791,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: @@ -664,9 +940,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} @@ -688,6 +963,13 @@ when something unexpected happens. If you can't see an error in the indicated line of your input file, try checking one or two lines above the indicated position. +Please note that diagnostics can be triggered at any point during the +many stages of processing. For example if there are parts of the input +that are processed multiple times (i.e. in midi and layout output), or +if the same music variable is used in multiple contexts the same message +may appear several times. Diagnostics produced at a @q{late} stage (i.e +bar checks) might also be issued multiple times. + More information about errors is given in @ref{Common errors}. @@ -702,10 +984,11 @@ are easily handled. @menu * Music runs off the page:: * An extra staff appears:: -* Apparent error in ../ly/init.ly:: * Error message Unbound variable %:: * Error message FT_Get_Glyph_Name:: * Warning staff affinities should only decrease:: +* Error message unexpected new:: +* Warning ignoring too many clashing note columns:: @end menu @node Music runs off the page @@ -750,7 +1033,7 @@ 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 +\override Staff.NoteHead.color = #red \new Staff { a } @end lilypond @@ -762,63 +1045,11 @@ correct code to color all note heads red is @lilypond[quote,verbatim,relative=2] \new Staff { - \override Staff.NoteHead #'color = #red + \override Staff.NoteHead.color = #red a } @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 -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' { c4 d e f } -} -@end lilypond - -Explicitly instantiating the @code{Voice} context fixes the -problem: - -@lilypond[quote,verbatim] -\new Voice { - \repeat unfold 2 { - \relative c' { c4 d e f } - } -} -@end lilypond - - -@node Apparent error in ../ly/init.ly -@unnumberedsubsec Apparent error in @code{../ly/init.ly} - -Various obscure error messages may appear about syntax errors in -@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. - -The most common error is a missing brace, (@code{@}}), at the end of -a @code{score} block. Here the solution is obvious: check the -@code{score} block is correctly terminated. The correct structure -of an input file is described in @rlearning{How LilyPond input files work}. -Using an editor which automatically highlights matching brackets and -braces is helpful to avoid such errors. - -A second common cause is no white space between the last syllable -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{Entering lyrics}. - -This error message can also appear if a terminating quote sign, -(@code{"}), is omitted. In this case an accompanying error message -@c keep "-matching straight in fancy editors -should give a line number close to the line in error. The -mismatched quote will usually be on the line one or two above. - @node Error message Unbound variable % @unnumberedsubsec Error message Unbound variable % @@ -841,6 +1072,7 @@ 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 @@ -848,9 +1080,93 @@ messages can be avoided by making one of the contexts behave as a staff by inserting @example -\override VerticalAxisGroup #'staff-affinity = ##f +\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}. + + +@node Error message unexpected new +@unnumberedsubsec Error message unexpected @code{@bs{}new} + +A @code{\score} block must contain a @emph{single} music expression. +If instead it contains several @code{\new Staff}, +@code{\new StaffGroup} or similar contexts introduced with @code{\new} +without them being enclosed in either curly brackets, +@code{@{ @dots{} @}}, or double angle brackets, @code{<< @dots{} >>}, +like this: + +@example +\score @{ + % Invalid! Generates error: syntax error, unexpected \new + \new Staff @{ @dots{} @} + \new Staff @{ @dots{} @} +@} +@end example + +@noindent +the error message will be produced. + +To avoid the error, enclose all the @code{\new} statements in +curly or double angle brackets. + +Using curly brackets will introduce the @code{\new} statements +sequentially: + +@lilypond[quote,verbatim] +\score { + { + \new Staff { a' a' a' a' } + \new Staff { g' g' g' g' } + } +} +@end lilypond + +@noindent +but more likely you should be using double angle brackets so the new +staves are introduced in parallel, i.e. simultaneously: + +@lilypond[quote,verbatim] +\score { + << + \new Staff { a' a' a' a' } + \new Staff { g' g' g' g' } + >> +} +@end lilypond + +@node Warning ignoring too many clashing note columns +@unnumberedsubsec Warning ignoring too many clashing note columns + +If notes from two different voices with stems in the same direction +occur at the same musical moment, but the voices have no +voice-specific shifts specified, the warning message +@samp{warning: ignoring too many clashing note columns} will appear +when compiling the LilyPond file. This warning will appear even when +the notes have no visible stems, e.g. whole notes, if the stems for +shorter notes at the same pitch would be in the same direction. + +Remember that the stem direction depends on the position of the +note on the staff unless the stem direction is specified, for example +by using @code{\voiceOne}, etc. In this case the warning will appear +only when the stems happen to be in the same direction, i.e. when the +notes are in the same half of the staff. + +By placing the notes in voices with stem directions and shifts +specified, for example by using @code{\voiceOne}, etc., these warnings +may be avoided. + +Notes in higher numbered voices, @code{\voiceThree} etc., are +automatically shifted to avoid clashing note columns. This causes a +visible shift for notes with stems, but whole notes are not visibly +shifted unless an actual clash of the note heads occurs, or when the +voices cross over from their natural order (when @code{\voiceThree} +is higher than @code{\voiceOne}, etc.) + +@seealso +@rlearning{Explicitly instantiating voices}, +@rlearning{Real music example}, +@ruser{Single-staff polyphony}, +@ruser{Collision resolution}.