4.1 Invoking lilypond

The lilypond 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. ¹

4.2 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 function ly:set-option allows for access to some internal variables. Use -e '(ly:option-usage)' for more information.

-f,--format=format

A comma separated list of back-end output formats to use. Choices are tex (for TeX output, to be processed with LaTeX, and ps for PostScript.

There are other output options, but they are intended for developers.

-h,--help

Show a summary of usage.

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

--ps

Generate PostScript.

--dvi

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

--png

Generate pictures of each page, in PNG format. This implies --ps.

--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, the --safe MUST be passed. This 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 limited in both allowed CPU and memory usage.

-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!)

4.3 Environment variables

For processing both the TeX and the PostScript output, the appropriate environment variables must be set. The following scripts do this:

• buildscripts/out/lilypond-profile (for SH shells)
• buildscripts/out/lilypond-login (for C-shells)

They should normally be sourced as part of the login process. If these scripts are not run from the system wide login process, then you must run it yourself.

If you use sh, bash, or a similar shell, then add the following to your .profile:

. /the/path/to/lilypond-profile

If you use csh, tcsh or a similar shell, then add the following to your ~/.login:

source /the/path/to/lilypond-login

Of course, in both cases, you should substitute the proper location of either script.

These scripts set the following variables:

TEXMF

To make sure that TeX and lilypond find data files (among others .tex, .mf and .tfm), you have to set TEXMF to point to the lilypond data file tree. A typical setting would be

     {/usr/share/lilypond/1.6.0,{!!/usr/share/texmf}}

The binary itself recognizes the following environment variables:

LILYPONDPREFIX

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.

Other languages: English.
Using automatic language selection.