13.1 Invoking lilypond

The lilypond executable may be called as follows from the command line.

lilypond [option]... file...

When invoked with a filename that has no extension, the .ly extension is tried first. To read input from stdin, use a dash (-) for file.

When filename.ly is processed it will produce filename.tex as output (or filename.ps for PostScript output). If filename.ly contains more than one \score block, then the rest of the scores will be output in numbered files, starting with filename-1.tex. Several files can be specified; they will each be processed independently. ¹

13.1.1 Command line options

The following options are supported:

-e,--evaluate=expr

Evaluate the Scheme expr before parsing any .ly files. Multiple -e options may be given, they will be evaluated sequentially.

The expression will be evaluated in the guile-user module, so if you want to use definitions in expr, use

     lilypond -e '(define-public a 42)'

on the command-line, and include

     #(use-modules (guile-user))

at the top of the .ly file.

-f,--format=format

which formats should be written. Choices for format are svg, ps, pdf, png, tex, dvi.

Example: lilypond -fpng filename.ly

-b,--backend=format

the output format to use for the back-end. Choices for format are

tex

for TeX output, to be processed with LaTeX. If present, the file file.textmetrics is read to determine text extents.

texstr

dump text strings to .texstr file, which can be run through (La)TeX, resulting in a .textmetrics file, which contains the extents of strings of text. Warning: this functionality is currently missing due to heavy restructuring of the source code.

ps

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.

eps

for 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.

This mode is used by default by lilypond-book.

svg

for SVG (Scalable Vector Graphics). This dumps every page as a separate SVG file, with embedded fonts. You need a SVG viewer which supports embedded fonts, or a SVG viewer which is able to replace the embedded fonts with OTF fonts. Under Unix, you may use Inkscape (version 0.42 or later), after copying the OTF fonts in directory PATH/TO/share/lilypond/VERSION/fonts/otf/ to ~/.fonts/.

scm

for a dump of the raw, internal Scheme-based drawing commands.

Example: lilypond -bsvg filename.ly

-d,--define-default=var=val

This sets the internal program option var to the Scheme value val. If val is not supplied, then #t is used. To switch off an option, no- may be prefixed to var, e.g.

     -dno-point-and-click

is the same as

     -dpoint-and-click='#f'

Another notable option is

     -dpaper-size=\"letter\"

Note that the string must be enclosed in escaped quotes ( \" ).

Setting the -dhelp option will print a summary of the options available, and exit.

-h,--help

Show a summary of usage.

-H,--header=FIELD

Dump a header field to file BASENAME.FIELD

--include, -I=directory

Add directory to the search path for input files.

-i,--init=file

Set init file to file (default: init.ly).

-o,--output=FILE

Set the default output file to FILE. The appropriate suffix will be added (ie .pdf for pdf, .tex for tex, etc).

--ps

Generate PostScript.

--dvi

Generate DVI files. In this case, the TeX backend should be specified, i.e., -b tex.

--png

Generate pictures of each page, in PNG format. This implies --ps. The resolution in DPI of the image may be set with

     -dresolution=110

--pdf

Generate PDF. This implies --ps.

--preview

Generate an output file containing the titles and the first system

--no-pages

Do not generate the full pages. Useful in combination with --preview.

-s,--safe

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, for example

          
          #(system "rm -rf /")
          {
            c4^#(ly:export (ly:gulp-file "/etc/passwd"))
          }
     

The --safe option works by evaluating in-line Scheme expressions in a special safe module. This safe module is derived from GUILE safe-r5rs module, but adds a number of functions of the LilyPond API. These functions are listed in scm/safe-lily.scm.

In addition, --safe disallows \include directives and disables the use of backslashes in TeX strings.

In --safe mode, it is not possible to import LilyPond variables into Scheme.

--safe does 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.

Note that --safe will prevent many useful LilyPond snippets from being compiled. For a softer but secure alternative you can use the --jail option.

-j,--jail=user,group,jail,dir

Run LilyPond in a chroot jail.

The --jail option provides a more flexible alternative to --safe when LilyPond formatting is available through a web server or whenever LilyPond executes externally provided sources.

The --jail option works by changing the root of LilyPond to 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 dir. This setup guarantees that it is not possible (at least in theory) to escape from the jail. Note that for --jail to work LilyPond must be run as root, which is usually accomplished in a safe way using sudo.

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 inside the jail. A typical setup comprises the following items:

Setting up a separate filesystem

A separate filesystem should be created for LilyPond, so that it can be mounted with safe options such as noexec, nodev, and 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.

Setting up a separate user

A separate user and group (say, `lily'/`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 dir.

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., /usr/share/lilypond) should be copied.

If problems arise, the simplest way to trace them down is to run LilyPond using strace, which will allow you to determine which files are missing.

Running LilyPond

In a jail mounted with 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 sudo. It is a good idea to limit the number of seconds of CPU time LilyPond can use (e.g., using ulimit -t), and, if your operating system supports it, the amount of memory that can be allocated.

-v,--version

Show version information.

-V,--verbose

Be verbose: show full paths of all files read, and give timing information.

-w,--warranty

Show the warranty with which GNU LilyPond comes. (It comes with NO WARRANTY!)

13.1.2 Environment variables

Lilypond recognizes the following environment variables:

LILYPOND_DATADIR

This specifies a directory where locale messages and data files will be looked up by default. The directory should contain subdirectories called ly/, ps/, tex/, etc.

LANG

This selects the language for the warning messages.

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 70.