lilypond-usage: Advanced command line options for LilyPond
Advanced command line options for LilyPond
------------------------------------------
‘-d[OPTION-NAME]=[VALUE],--define-default=[OPTION-NAME]=[VALUE]’
This sets the equivalent internal Scheme function to VALUE.
-dbackend=svg
If a VALUE is not supplied, then the default value is used. The
prefix ‘no-’ may be added to OPTION-NAME to switch ‘off’ an option,
e.g.
-dpoint-and-click=#f
is the same as
-dno-point-and-click
The following are supported along with their respective default values:
*Symbol* *Value* *Explanation/Options*
‘anti-alias-factor’ ‘1’ Render at higher resolution (using
given factor) and scale down result
to prevent ‘jaggies’ in ‘PNG’
images.
‘aux-files’ ‘#t’ Create ‘.tex’, ‘.texi’, ‘.count’
files in the ‘EPS’ backend.
‘backend’ ‘ps’ Select backend. Postscript files
(default) include ‘TTF’, ‘Type1’
and ‘OTF’ fonts. No subsetting of
these fonts is done. Using
‘oriental’ character sets can lead
to very large files.
‘eps’ Encapsulated PostScript. This
dumps every page (system) as a
separate ‘EPS’ file, without fonts,
and as one collated ‘EPS’ file with
all pages (systems) including
fonts. Used as default by
‘lilypond-book’.
‘null’ Do not output a printed score; has
the same effect as
‘-dno-print-pages’.
‘svg’ 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
‘/usr/share/VERSION/fonts/otf/’)
to ‘~/.fonts/’. The ‘SVG’ output
should be compatible with any SVG
editor or user agent. There is
also an option ‘svg-woff’ (below)
for use of woff font files in the
SVG backend.
‘scm’ Dump of the raw, internal
Scheme-based drawing commands.
‘check-internal-types’ ‘#f’ Check every property assignment for
types.
‘clip-systems’ ‘#f’ Generate cut-out snippets of a
score.
‘datadir’ Prefix for data files (read-only).
‘debug-gc’ ‘#f’ Dump memory debugging statistics.
‘debug-gc-assert-parsed-dead’‘#f’ For memory debugging: Ensure that
all references to parsed objects
are dead. This is an internal
option, and is switched on
automatically for ‘`-ddebug-gc'’.
‘debug-lexer’ ‘#f’ Debug the flex lexer.
‘debug-page-breaking-scoring’‘#f’ Dump scores for many different page
breaking configurations.
‘debug-parser’ ‘#f’ Debug the bison parser.
‘debug-property-callbacks’‘#f’ Debug cyclic callback chains.
‘debug-skylines’ ‘#f’ Debug skylines.
‘delete-intermediate-files’‘#t’ Delete the unusable, intermediate
‘.ps’ files created during
compilation.
‘dump-cpu-profile’ ‘#f’ Dump timing information
(system-dependent).
‘dump-profile’ ‘#f’ Dump memory and time information
for each file.
‘dump-signatures’ ‘#f’ Dump output signatures of each
system. Used for regression
testing.
‘eps-box-padding’ ‘#f’ Pad left edge of the output EPS
bounding box by the given amount
(in mm).
‘gs-load-fonts’ ‘#f’ Load fonts via Ghostscript.
‘gs-load-lily-fonts’ ‘#f’ Load only the LilyPond fonts via
Ghostscript.
‘gui’ ‘#f’ Runs silently and redirect all
output to a log file.
to Windows users* By default ‘lilypond.exe’ outputs all progress
information to the command window, ‘lilypond-windows.exe’ does not and
returns a prompt, with no progress information, immediately at the
command line. The ‘-dgui’ option can be used in this case to redirect
output to a log file.
‘help’ ‘#f’ Show this help.
‘include-book-title-preview’‘#t’ Include book titles in preview
images.
‘include-eps-fonts’ ‘#t’ Include fonts in separate-system
EPS files.
‘include-settings’ ‘#f’ Include file for global settings,
this is included before the score
is processed.
‘job-count’ ‘#f’ Process in parallel, using the
given number of jobs.
‘log-file’ ‘#f If string ‘FOO’ is given as a
[file]’ second argument, redirect output to
the log file ‘FOO.log’.
‘max-markup-depth’ ‘1024’ 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.
‘midi-extension’ ‘"midi"’ Set the default file extension for
MIDI output file to given string.
‘music-strings-to-paths’ ‘#f’ Convert text strings to paths when
glyphs belong to a music font.
‘paper-size’ ‘\"a4\"’ Set default paper size. Note the
string must be enclosed in escaped
double quotes.
‘pixmap-format’ ‘png16m’ Set GhostScript’s output format for
pixel images.
‘point-and-click’ ‘#f’ Add ‘point & click’ links to ‘PDF’
output. See
Point and click.
‘preview’ ‘#f’ Create preview images in addition
to normal output.
This option is supported by all backends; ‘pdf’, ‘png’, ‘ps’, ‘eps’ and
‘svg’, but not ‘scm’. It generates an output file, in the form
‘myFile.preview.extension’, containing the titles and the first system
of music. If ‘\book’ or ‘\bookpart’ blocks are used, the titles of
‘\book’, ‘\bookpart’ or ‘\score’ will appear in the output, including
the first system of every ‘\score’ block if the ‘\paper’ variable
‘print-all-headers’ is set to ‘#t’.
To suppress the usual output, use the ‘-dprint-pages’ or
‘-dno-print-pages’ options according to your requirements.
‘print-pages’ ‘#t’ Generate full pages, the default.
‘-dno-print-pages’ is useful in
combination with ‘-dpreview’.
‘profile-property-accesses’‘#f’ Keep statistics of ‘get_property()’
function calls.
‘protected-scheme-parsing’‘#t’ Continue when errors in inline
scheme are caught in the parser.
If set to ‘#f’, halt on errors and
print a stack trace.
‘read-file-list’ ‘#f Specify name of a file which
[file]’ contains a list of input files to
be processed.
‘relative-includes’ ‘#f’ When processing an ‘\include’
command, look for the included file
relative to the current file
(instead of the root file).
‘resolution’ ‘101’ Set resolution for generating ‘PNG’
pixmaps to given value (in dpi).
‘safe’ ‘#f’ Do not trust the ‘.ly’ input.
When LilyPond formatting is available through a web server, either the
‘--safe’ or the ‘--jail’ option MUST be passed. The ‘--safe’ option
will prevent inline Scheme code from wreaking havoc, e.g,
#(system "rm -rf /")
{
c4^$(ly:gulp-file "/etc/passwd")
}
The ‘-dsafe’ option works by evaluating in-line Scheme expressions in
a special safe module. This is derived from GUILE ‘safe-r5rs’ module,
but also adds a number of functions of the LilyPond API which are listed
in ‘scm/safe-lily.scm’.
In addition, safe mode disallows ‘\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.
‘-dsafe’ does _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 ‘--jail’ is an even more secure alternative, but requires more
work to set up. See Basic command line options for LilyPond.
‘separate-log-files’ ‘#f’ For input files ‘FILE1.ly’,
‘FILE2.ly’, etc. output log data
to files ‘FILE1.log’,
‘FILE2.log’...
‘show-available-fonts’ ‘#f’ List available font names.
‘strict-infinity-checking’‘#f’ Force a crash on encountering ‘Inf’
and ‘NaN’ floating point
exceptions.
‘strip-output-dir’ ‘#t’ Don’t use directories from input
files while constructing output
file names.
‘strokeadjust’ ‘#f’ Force PostScript stroke adjustment.
This option is mostly relevant when
‘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.
‘svg-woff’ ‘#f’ Use woff font files in SVG backend.
‘trace-memory-frequency’ ‘#f’ Record Scheme cell usage this many
times per second. Dump the results
to ‘FILE.stacks’ and ‘FILE.graph’.
‘trace-scheme-coverage’ ‘#f’ Record coverage of Scheme files in
‘FILE.cov’.
‘verbose’ ‘#f’ Verbose output, i.e. loglevel at
DEBUG (read-only).
‘warning-as-error’ ‘#f’ Change all warning and ‘programming
error’ messages into errors.
Info Catalog
lilypond-usage: Basic command line options for LilyPond
lilypond-usage: Command-line usage
lilypond-usage: Environment variables